# Sample REST API contract note: Open-Meteo forecast

This is a compact documentation sample based on Open-Meteo's public Forecast API reference and one live public response. It is an independent example of the scoped REST API documentation service; it is not commissioned by, endorsed by, or affiliated with Open-Meteo.

## Request

`GET https://api.open-meteo.com/v1/forecast`

| Query parameter | Sample | Meaning |
|---|---|---|
| `latitude` | `47.56` | Required coordinate |
| `longitude` | `-52.71` | Required coordinate |
| `current` | `temperature_2m,wind_speed_10m` | Current variables to include |
| `hourly` | `temperature_2m` | Hourly variables to include |
| `forecast_days` | `1` | Number of forecast days in this example |
| `timezone` | `America/St_Johns` | Local-time convention for returned timestamps |

Reproducible PowerShell request:

```powershell
$uri = 'https://api.open-meteo.com/v1/forecast?latitude=47.56&longitude=-52.71&current=temperature_2m%2Cwind_speed_10m&hourly=temperature_2m&forecast_days=1&timezone=America%2FSt_Johns'
$response = Invoke-RestMethod -Uri $uri -Method Get
$response.current
$response.hourly.time.Count
$response.hourly.temperature_2m.Count
```

## Response contract

- A successful request returns a JSON object. The sample returned top-level `timezone`, `utc_offset_seconds`, `current`, `current_units`, `hourly`, and `hourly_units` fields.
- `current` contains one value per requested current variable plus `time` and `interval`. The observed sample included `temperature_2m: 2.4` °C and `wind_speed_10m: 16.9` km/h; values are time-sensitive and illustrative only.
- `hourly.time` and `hourly.temperature_2m` are parallel arrays. Pair by index; the live one-day response contained 24 entries in each.
- `current_units` and `hourly_units` carry measurement units. Do not hard-code units independently of the response.
- An invalid URL parameter returns HTTP 400 with a JSON error object containing `error: true` and a human-readable `reason` according to the API reference.

## Integration notes

1. URL-encode comma-separated values and timezone names when constructing a URL.
2. If requesting `daily` values, supply `timezone`; the reference says it is required for daily variables.
3. Returned ISO 8601 times use the response timezone and fixed `utc_offset_seconds`; the reference says this offset is held fixed over the requested range. For DST-aware local rendering, use `timeformat=unixtime` and convert with the returned timezone in the client.
4. Check HTTP status before treating a JSON body as success. Surface the API's `reason` on a 400 response without assuming all provider errors share the same shape.
5. The reference lists `forecast_days` from 0 to 16 (default 7). Keep requested ranges within documented bounds.
6. The API reference distinguishes non-commercial, commercial, and self-hosted usage. Confirm the applicable plan and license for the intended deployment; this note does not determine usage rights.

## Validation record

Fetched the request above on 2026-10-25 using PowerShell `Invoke-RestMethod`. Observed timezone `America/St_Johns`, offset `-9000` seconds, current fields `time, interval, temperature_2m, wind_speed_10m`, and 24 hourly timestamps matched to 24 hourly temperature values. The API's live forecast values are not stable fixtures; only the response shape, count alignment, and error-path checks are reported here.

## Sources

- [Open-Meteo Forecast API reference](https://open-meteo.com/en/docs): endpoint and query parameters; success/error response structures; timestamp, array, unit, and timezone behavior; usage-plan selector.
- Live public endpoint used for the validation above: `https://api.open-meteo.com/v1/forecast?latitude=47.56&longitude=-52.71&current=temperature_2m%2Cwind_speed_10m&hourly=temperature_2m&forecast_days=1&timezone=America%2FSt_Johns`