Open Meteo

Open Meteo

Goal

Provide a reliable, production-friendly way to call Open-Meteo APIs (Forecast, Air Quality, Geocoding), choose variables, control time/units/timezone, and parse responses consistently.

Steps

1. Pick the correct API and base URL

• Forecast: https://api.open-meteo.com/v1/forecast
• Air Quality: https://air-quality-api.open-meteo.com/v1/air-quality
• Geocoding: https://geocoding-api.open-meteo.com/v1/search

2. Resolve coordinates (if you only have a name)

• Call Geocoding with name and optional language, countryCode, count.
• Use the returned latitude, longitude, and timezone for subsequent calls.

3. Design your time axis (timezone, timeformat, and range)

• Prefer timezone=auto when results must align to local midnight.
• If you request daily=..., set timezone (docs: daily requires timezone).
• Choose timeformat=iso8601 for readability, or timeformat=unixtime for compactness.
• If using unixtime, remember timestamps are GMT+0 and you must apply utc_offset_seconds for correct local dates.
• Choose range controls:
• forecast_days and optional past_days, or
• explicit start_date/end_date (YYYY-MM-DD), and for sub-daily start_hour/end_hour.

4. Choose variables minimally (avoid "download everything")

• Forecast: request only the variables you need via hourly=..., daily=..., current=....
• Air Quality: request only the variables you need via hourly=..., current=....
• Keep variable names exact; typos return a JSON error with error: true.

5. Choose units and model selection deliberately

• Forecast units:
• temperature_unit (celsius / fahrenheit)
• wind_speed_unit (kmh / ms / mph / kn)
• precipitation_unit (mm / inch)
• Forecast model selection:
• default models=auto / “Best match” combines the best models.
• you can explicitly request models via models=....
• provider-specific forecast endpoints also exist (provider implied by path). See references/models.md (section "Endpoints vs models=") for examples and doc links.
• for provider/model-specific selection tradeoffs, see references/models.md.
• Air Quality domain selection:
• domains=auto (default) or cams_europe / cams_global.

6. Implement robust request/response handling

• Treat HTTP errors and JSON-level errors separately.
• JSON error format is:
• {"error": true, "reason": "..."}
• When requesting multiple locations (comma-separated coordinates), expect the JSON output shape to change to a list of structures.
• Optionally use format=csv or format=xlsx when you need data export.

7. Validate correctness with a “known city” check

• Geocode “Berlin” → Forecast hourly=temperature_2m for 1–2 days → verify timezone and array lengths.
• Air Quality hourly=pm10,pm2_5,european_aqi → verify units and presence of hourly_units.

Critical prohibitions

• Do not include out-of-scope APIs in this skill’s implementation guidance: Historical Weather, Ensemble Models, Seasonal Forecast, Climate Change, Marine, Satellite Radiation, Elevation, Flood.
• Do not omit timezone when requesting daily variables (per docs).
• Do not assume unixtime timestamps are local time; they are GMT+0 and require utc_offset_seconds adjustment.
• Do not silently ignore {"error": true} responses; fail fast with the provided reason.
• Do not request huge variable sets by default; keep queries minimal to reduce payload and avoid accidental overuse.

Definition of done

• You can geocode a place name and obtain coordinates/timezone.
• You can fetch Forecast data with at least one hourly, one daily (with timezone), and one current variable.
• You can fetch Air Quality data for at least one pollutant and one AQI metric.
• Your client code handles both HTTP-level failures and JSON-level error: true with clear messages.
• Attribution requirements from the docs are captured for Air Quality (CAMS) and Geocoding (GeoNames).

Links

• Documentation
• Releases
• GitHub

Open-Meteo Air Quality API (in-scope)

Source of truth: https://open-meteo.com/en/docs/air-quality-api

Base URL

• https://air-quality-api.open-meteo.com/v1/air-quality

Core query parameters

Required

• latitude (float)
• longitude (float)

Variable selection

• hourly (string array): comma-separated or repeated &hourly= parameters.
• current (string array): current-condition air-quality variables.

Domain selection

• domains (string, default auto)
• auto: combine both domains automatically.
• cams_europe: European domain.
• cams_global: global domain.

Docs note: European and global domains are not coupled and may show different forecasts.

Time controls

• timezone (string, default GMT)
• Supports TZ database names.
• timezone=auto resolves coordinates to local timezone.

• timeformat (string, default iso8601)
• iso8601 or unixtime.
• If unixtime: timestamps are GMT+0; apply utc_offset_seconds to derive correct local dates.

• forecast_days (int 0–7, default 5)
• past_days (int 0–92, default 0)

• Alternative timestep control:
• forecast_hours, past_hours

• Explicit time interval:
• start_date, end_date (YYYY-MM-DD)
• start_hour, end_hour (YYYY-MM-DDThh:mm)

Grid cell selection

• cell_selection (string, default nearest)
• nearest, land, sea.

Export formats

• format=csv or format=xlsx to export.

Commercial usage

• apikey is optional; docs describe it as required only for commercial use to access reserved resources.
• Docs note the server URL requires the prefix customer- for commercial usage.

Hourly variables (docs list)

Common pollutants and indices:

• Particulate matter: pm10, pm2_5
• Gases: carbon_monoxide, nitrogen_dioxide, sulphur_dioxide, ozone
• AQI (European):
• european_aqi (consolidated max)
• european_aqi_pm2_5, european_aqi_pm10, european_aqi_nitrogen_dioxide, european_aqi_ozone, european_aqi_sulphur_dioxide
• AQI (United States):
• us_aqi (consolidated max)
• us_aqi_pm2_5, us_aqi_pm10, us_aqi_nitrogen_dioxide, us_aqi_ozone, us_aqi_sulphur_dioxide, us_aqi_carbon_monoxide

Pollen variables (Europe only, during pollen season with 4 days forecast):

• alder_pollen, birch_pollen, grass_pollen, mugwort_pollen, olive_pollen, ragweed_pollen

Other hourly variables called out in the docs UI include:

• carbon_dioxide, aerosol_optical_depth, dust, uv_index, uv_index_clear_sky, ammonia, methane

European AQI scale (docs)

• 0–20: good
• 20–40: fair
• 40–60: moderate
• 60–80: poor
• 80–100: very poor
• >100: extremely poor

Docs note: PM uses a 24-hour rolling average; gases use hourly values.

EU thresholds table (from docs)

US AQI scale (docs)

• 0–50: good
• 51–100: moderate
• 101–150: unhealthy for sensitive groups
• 151–200: unhealthy
• 201–300: very unhealthy
• 301–500: hazardous

US thresholds table (from docs)

Response structure (single-location)

The docs show the canonical response shape:

• latitude, longitude, elevation
• generationtime_ms
• utc_offset_seconds
• timezone, timezone_abbreviation
• hourly (object): time[] + arrays for each requested hourly variable
• hourly_units (object): unit per hourly variable

(If current was requested, a current object is included.)

Error handling

The docs show JSON error objects returned with HTTP 400:

{
  "error": true,
  "reason": "Cannot initialize WeatherVariable from invalid String value ..."
}

Attribution / acknowledgement (docs)

Docs require users to provide attribution to:

• CAMS ENSEMBLE data provider, and
• Open-Meteo

See the “Citation & Acknowledgement” section on the Air Quality docs page.

Examples (Geocoding → Forecast / Air Quality)

All examples are derived from the official docs pages:

• https://open-meteo.com/en/docs
• https://open-meteo.com/en/docs/air-quality-api
• https://open-meteo.com/en/docs/geocoding-api

Python (httpx) — geocode then forecast

from __future__ import annotations

from typing import Any

import httpx


def _raise_if_open_meteo_error(payload: dict[str, Any]) -> None:
    if payload.get("error") is True:
        reason = payload.get("reason")
        raise RuntimeError(f"Open-Meteo error: {reason}")


def geocode(name: str, *, language: str = "en", count: int = 1) -> dict[str, Any]:
    url = "https://geocoding-api.open-meteo.com/v1/search"
    params = {"name": name, "language": language, "count": count, "format": "json"}

    with httpx.Client(timeout=10.0) as client:
        resp = client.get(url, params=params)
        resp.raise_for_status()
        data = resp.json()

    _raise_if_open_meteo_error(data)

    results = data.get("results")
    if not results:
        raise ValueError(f"No geocoding results for: {name}")

    return results[0]


def forecast(latitude: float, longitude: float, timezone: str) -> dict[str, Any]:
    url = "https://api.open-meteo.com/v1/forecast"
    params = {
        "latitude": latitude,
        "longitude": longitude,
        "hourly": "temperature_2m,precipitation,weather_code",
        "daily": "temperature_2m_max,temperature_2m_min,precipitation_sum",
        "current": "temperature_2m,wind_speed_10m",
        "timezone": timezone,  # daily requires timezone per docs
        "forecast_days": 2,
    }

    with httpx.Client(timeout=10.0) as client:
        resp = client.get(url, params=params)
        resp.raise_for_status()
        data = resp.json()

    _raise_if_open_meteo_error(data)
    return data


place = geocode("Berlin", language="en", count=1)
lat = float(place["latitude"])
lon = float(place["longitude"])
tz = str(place.get("timezone") or "GMT")

payload = forecast(lat, lon, tz)
print(payload["timezone"], payload["hourly_units"].get("temperature_2m"))
print(payload["hourly"]["time"][0], payload["hourly"]["temperature_2m"][0])

Python (httpx) — air quality for the same point

from __future__ import annotations

from typing import Any

import httpx


def _raise_if_open_meteo_error(payload: dict[str, Any]) -> None:
    if payload.get("error") is True:
        raise RuntimeError(f"Open-Meteo error: {payload.get('reason')}")


def air_quality(latitude: float, longitude: float, timezone: str) -> dict[str, Any]:
    url = "https://air-quality-api.open-meteo.com/v1/air-quality"
    params = {
        "latitude": latitude,
        "longitude": longitude,
        "hourly": "pm10,pm2_5,european_aqi,us_aqi",
        "current": "pm10,pm2_5,european_aqi",
        "timezone": timezone,
        "forecast_days": 2,
        "domains": "auto",
    }

    with httpx.Client(timeout=10.0) as client:
        resp = client.get(url, params=params)
        resp.raise_for_status()
        data = resp.json()

    _raise_if_open_meteo_error(data)
    return data

Notes

• Variable names must match the docs exactly: e.g., pm2_5 (not pm2.5).
• If you set timeformat=unixtime, timestamps are in GMT+0; use utc_offset_seconds to derive local dates.
• If you request daily=... on the Forecast API, you must set timezone (per docs).

Open-Meteo Weather Forecast API (in-scope)

Source of truth: https://open-meteo.com/en/docs

Base URL

• https://api.open-meteo.com/v1/forecast

Request shape

• HTTP method: GET
• Query parameters are URL-encoded.

Multi-location batching

• latitude and longitude accept comma-separated lists.
• When multiple locations are requested, the JSON output shape changes (docs note this explicitly).
• CSV/XLSX export adds a location_id column.

Core query parameters

Required

• latitude (float)
• longitude (float)

Variable selection

• hourly (string array): comma-separated or repeated &hourly= parameters.
• daily (string array): comma-separated or repeated &daily= parameters.
• Important: If daily variables are specified, timezone is required.
• current (string array): current-condition variables.

Time controls

• timezone (string, default GMT)
• Use a TZ database name (e.g., Europe/Berlin).
• timezone=auto resolves coordinates to the local timezone.
• If timezone is set, timestamps are returned in local time and data starts at 00:00 local-time.

• timeformat (string, default iso8601)
• iso8601 or unixtime.
• If `unixtime`: timestamps are returned in GMT+0; apply utc_offset_seconds to get correct local dates.

• forecast_days (int 0–16, default 7)
• past_days (int 0–92, default 0)

• Fine-grained timestep control:
• forecast_hours, past_hours
• For 15-minutely data: forecast_minutely_15, past_minutely_15

• Explicit time interval:
• start_date, end_date (YYYY-MM-DD)
• For hourly/15-minutely: start_hour, end_hour, start_minutely_15, end_minutely_15 (YYYY-MM-DDThh:mm)

Units

• temperature_unit (default celsius): set to fahrenheit to convert.
• wind_speed_unit (default kmh): alternatives ms, mph, kn.
• precipitation_unit (default mm): alternative inch.

Models

• models (string array, default auto)
• Docs note: “Best match” provides the best forecast worldwide.
• “Seamless” combines models from a provider into a seamless prediction.

Elevation and grid-cell selection

• elevation (float)
• Default: uses a 90m digital elevation model.
• elevation=nan disables downscaling.
• cell_selection (string, default land)
• land: prefers a land grid-cell with similar elevation.
• sea: prefers sea grid-cells.
• nearest: nearest possible grid-cell.

Export formats

• format=csv or format=xlsx to export.

Commercial usage

• apikey is optional and described as required only for commercial use to access reserved resources.
• Docs note the server URL requires the prefix `customer-` for commercial usage.

Variables (high-level map)

The docs provide extensive variable lists. These are common, high-signal variables to start with:

• Forecast hourly:
• temperature_2m, relative_humidity_2m, apparent_temperature
• precipitation, rain, showers, snowfall, precipitation_probability
• wind_speed_10m, wind_direction_10m, wind_gusts_10m
• weather_code, cloud_cover, pressure_msl, visibility

• Forecast daily:
• temperature_2m_max, temperature_2m_min
• precipitation_sum, rain_sum, snowfall_sum
• sunrise, sunset, daylight_duration, sunshine_duration
• wind_speed_10m_max, wind_gusts_10m_max

• Forecast current:
• any hourly variable can be requested as current; docs mention current values are based on 15-minutely data.

Response structure (single-location)

The docs show the canonical response shape:

• Top-level metadata:
• latitude, longitude, elevation
• generationtime_ms
• utc_offset_seconds
• timezone, timezone_abbreviation

• Variable blocks:
• current (object): values for requested current variables + time and interval (seconds)
• hourly (object): time[] + arrays for each requested hourly variable
• hourly_units (object): unit per hourly variable
• daily / daily_units analogous

WMO weather codes

• weather_code uses WMO interpretation codes.
• See: references/weather-codes.md.

Error handling

If URL parameters are invalid or variable names are misspelled, the API returns HTTP 400 with a JSON object:

{
  "error": true,
  "reason": "Cannot initialize WeatherVariable from invalid String value ..."
}

Open-Meteo Geocoding API (in-scope)

Source of truth: https://open-meteo.com/en/docs/geocoding-api

Base URL

• Search: https://geocoding-api.open-meteo.com/v1/search

Docs also mention IDs can be resolved via:

• Get by ID: https://geocoding-api.open-meteo.com/v1/get?id=<id>

Search parameters

Matching behavior (docs)

• empty string or 1 character → empty result
• 2 characters → exact matching only
• 3+ characters → fuzzy matching

Response

On success, returns:

{
  "results": [
    {
      "id": 2950159,
      "name": "Berlin",
      "latitude": 52.52437,
      "longitude": 13.41053,
      "elevation": 74.0,
      "feature_code": "PPLC",
      "country_code": "DE",
      "timezone": "Europe/Berlin",
      "population": 3426354,
      "postcodes": ["10967", "13347"],
      "country": "Deutschland",
      "admin1": "Berlin"
    }
  ]
}

Docs note:

• Empty fields are not returned (e.g., admin4 may be missing).
• The schema includes administrative levels (admin1..admin4) and corresponding IDs.

Error handling

Docs show HTTP 400 with a JSON error object, e.g.:

{
  "error": true,
  "reason": "Parameter count must be between 1 and 100."
}

Attribution (docs)

• Location data based on GeoNames
• Country flags from HatScripts/circle-flags

Forecast models= selection guide

Source: Official Open-Meteo provider documentation pages.

Scope: Weather Forecast API only. Does not cover Historical, Ensemble, Seasonal, Climate, Marine, Satellite Radiation, Elevation, or Flood APIs.

How model selection works

• models=auto (default) — "Best match" combines optimal models automatically
• Explicit models=<key> — select specific provider/model
• Provider-specific endpoints — some providers have dedicated endpoints (e.g., /v1/ecmwf)

Endpoints vs models=

Generic Forecast endpoint (recommended):

• URL: https://api.open-meteo.com/v1/forecast
• Use models=auto or models=<provider_key>
• Most flexible, supports switching providers per request

Provider-specific endpoints:

• /v1/dwd-icon — DWD ICON
• /v1/gfs — NOAA GFS/HRRR
• /v1/ecmwf — ECMWF IFS/AIFS
• /v1/bom — Australia BOM
• /v1/cma — China CMA

Start with the generic endpoint + models=auto unless you have specific requirements.

Model selection rules

1. Default to `models=auto` — works globally, picks best available

2. Use "seamless" models when you want:

• High-resolution short-range (2–3 days) + automatic extension with global models

3. Use regional models when you need:

• Higher spatial resolution
• Only care about short horizons (nowcast / 0–72h)

4. Variable availability varies:

• Not all providers have direct solar radiation (some derive it)
• Cloud cover at 2m (fog indicator) — only KMA, UKMO UKV, DMI
• Probability data — only NBM (NOAA), ARPEGE (Météo-France)

5. Licensing:

• UKMO: CC BY-SA 4.0 (derived products must stay compatible)

6. Operational notes:

• BOM: temporary suspension due to platform upgrades
• CMA: recent overload/reliability issues

Provider quick reference

Finding specific model keys

If you need a specific sub-model (not seamless): 1. Go to the provider's docs page 2. Use "Preview → URL" generator 3. Copy models=... values from the generated URL

Provider docs:

• https://open-meteo.com/en/docs/dwd-api
• https://open-meteo.com/en/docs/gfs-api
• https://open-meteo.com/en/docs/ecmwf-api
• https://open-meteo.com/en/docs/meteofrance-api
• https://open-meteo.com/en/docs/ukmo-api
• https://open-meteo.com/en/docs/kma-api
• https://open-meteo.com/en/docs/jma-api
• https://open-meteo.com/en/docs/meteoswiss-api
• https://open-meteo.com/en/docs/metno-api
• https://open-meteo.com/en/docs/gem-api
• https://open-meteo.com/en/docs/bom-api
• https://open-meteo.com/en/docs/cma-api
• https://open-meteo.com/en/docs/knmi-api
• https://open-meteo.com/en/docs/dmi-api
• https://open-meteo.com/en/docs/italia-meteo-arpae-api

WMO Weather interpretation codes (WW)

Source of truth: https://open-meteo.com/en/docs

Open-Meteo’s weather_code uses WMO interpretation codes.

\* Thunderstorm forecast with hail is only available in Central Europe (per docs).