Weather API

Forecast#

Parameters

Response

{
  "latitude": 48.85,
  "longitude": 2.35,
  "timezone": "Europe/Paris",
  "grid": {
    "latitude": 48.85, "longitude": 2.35,
    "distance_km": 0.42, "resolution_km": 1.3
  },
  "elevation": {
    "applied": true,
    "model_elevation_m": 91.0,
    "location_elevation_m": 113,
    "temperature_offset_c": -0.14
  },
  "source": {
    "model": "mf_arome",
    "model_run": "20260801T00Z",
    "reference_time": "2026-08-01T00:00:00+00:00",
    "data_age_hours": 3.95,
    "stale": false,
    "attribution": "Data: Météo-France (etalab-2.0)"
  },
  "hourly": {
    "time": ["2026-08-01T00:00:00+02:00", "..."],
    "temperature_2m": [18.1, 17.9, 17.6, "..."],
    "apparent_temperature": [17.4, "..."],
    "weather_code": [0, 1, 2, "..."]
  },
  "daily": {
    "date": ["2026-08-01", "..."],
    "temperature_2m_max": [26.6, "..."],
    "temperature_2m_min": [16.2, "..."],
    "precipitation_sum": [0.0, "..."],
    "uv_index_max": [7.6, "..."],
    "sunrise": ["2026-08-01T06:24:00+02:00", "..."],
    "sunset": ["2026-08-01T21:24:00+02:00", "..."],
    "daylight_hours": [15.0, "..."]
  }
}

Shrinking the payload

The full hourly block for 15 days is around 32 fields × 360 hours. If you plot three of them, ask for three:

GET /v1/forecast?lat=48.85&lon=2.35&days=3
    &hourly=temperature_2m,precipitation,weather_code
    &include_daily=false

Same price — the cost is reading the archive, not serialising it — but a tenth of the bytes and noticeably faster to parse on a phone.

Forecast by city#

Prefer this over raw coordinates where you can. The catalogue supplies two things a coordinate cannot: the city's true elevation, so the terrain correction applies without you supplying it, and its time zone, so daily aggregates are cut on the right local day.

GET /v1/forecast/city/dz/alger      # French slug
GET /v1/forecast/city/dz/algiers    # English slug — same city
GET /v1/forecast/city/fr/paris

country is an ISO-3166-1 alpha-2 code, lower case. slug is accent-insensitive: bejaia finds Béjaïa. An unknown slug returns 404 city_not_found with a suggestions array — show it rather than a dead end.

All the query parameters of /v1/forecast still apply except lat, lon and elevation, which the catalogue provides. Passing timezone overrides the city's own, which is almost never what you want.

Current conditions#

Temperature, humidity, wind and pressure are interpolated linearly to the current instant, between the two model steps that bracket it.

Use this for a "right now" display. For anything you will compare across time, use /v1/forecast and read the hour you want: the series is stable, whereas now moves under you between two calls.

Field reference#

Hourly fields

21 of these come back by default. The rest are yours for the asking — name them in hourly=, comma-separated — and they are held back for cost, not for doubt: each stored field is a separate compressed read, so a default response carrying all 45 would make every caller pay for the few who want snow depth.

GET /v1/forecast?lat=45.19&lon=5.72&hourly=temperature_2m,snow_line_altitude,soil_temperature_8cm

A field a model does not publish comes back as null for that model's stretch of the forecast rather than vanishing from the response — so a chain that starts on AROME and continues on ICON-EU returns visibility throughout, null for the first 51 hours. An unknown field name is a 400 unknown_field, with the closest match suggested; it used to be silently ignored.

Daily fields

date, temperature_2m_max, temperature_2m_min, temperature_2m_mean, precipitation_sum, wind_speed_max, wind_gust_max, shortwave_radiation_sum (MJ/m²), uv_index_max, sunrise, sunset, daylight_hours, weather_code.

Aggregated on local calendar days, not UTC. A partial day at either end of the range is omitted rather than reported with a misleading maximum — so a 7-day request can legitimately return 6 daily rows.

Models and resolution#

We serve the finest model that covers your point and your lead time. You never choose one; the choice is reported in source.model so you can always tell which answered.

High-resolution models are all short-range — at 1 km the atmosphere becomes chaotic within two days, so forecasting further would be meaningless — and the resolution therefore steps down as the forecast advances:

day 0 ─────── day 2 ─────── day 5 ───────────────── day 15
  AROME 1.3 km (France)
  ICON-D2 2.2 km (Germany, Alps, Benelux)
  HRRR 3 km (USA and southern Canada)
              ICON-EU 6.5 km (Europe)
                          ICON 13 km · ECMWF 28 km (global)
                                              AIFS (trend only)

Transitions across a model's domain edge are cross-faded, so two towns either side of a boundary never disagree by a step change.

/v1/models needs no key, which makes it the right thing to poll from a status page or to check before you buy: it reports each model's latest run and its age, so "is the data fresh" is answerable without spending a credit.

Ensemble probabilities#

A single forecast says 22 °C on Thursday. That is a guess presented as a fact. This endpoint answers the question you actually decide on: how sure is it, and what is the chance of rain worth planning around.

It is computed from ECMWF's ensemble — the same model run 50 times from slightly different starting conditions. Where the runs agree, the forecast is confident. Where they scatter, the atmosphere itself is uncertain, and no model however good can tell you more.

{
  "members": 50,
  "hourly": {
    "time": ["2026-08-01T00:00:00+00:00"],
    "temperature_2m_p10": [26.4],
    "temperature_2m_p50": [26.78],
    "temperature_2m_p90": [27.3],
    "temperature_2m_spread": [0.4],
    "precipitation_probability_0_1mm": [10.0],
    "precipitation_probability_1_0mm": [0.0],
    "precipitation_probability_5_0mm": [0.0],
    "precipitation_probability_10_0mm": [0.0],
    "precipitation_p90": [0.1]
  }
}

How to read it

p10 and p90 bracket the middle 80 % of the members: one in ten expects it colder than p10, one in ten warmer than p90. A spread of 0.4 °C is a settled situation you can trust; 3 °C means the models disagree and you should say so to your users rather than pick one.

The rain thresholds are decisions rather than round numbers — 0.1 mm is wet at all, 1 mm is take a coat, 5 and 10 mm are this is a problem. precipitation_p90 is the bad case: only one member in ten is wetter.

Air quality#

This is the endpoint that matters most across North Africa and the Mediterranean. A dust episode takes PM10 past a thousand micrograms per cubic metre for days at a time, which is a health decision rather than a number, and it is poorly covered by free consumer services.

{
  "current": {
    "pm2_5": 38.7,
    "band": "poor",
    "who_guidelines_ug_m3": {"pm2_5": 15.0, "pm10": 45.0,
                             "nitrogen_dioxide": 25.0, "ozone": 100.0}
  },
  "hourly": {
    "time": ["2026-08-01T00:00:00+00:00"],
    "pm2_5": [38.7], "pm10": [85.8], "ozone": [43.4],
    "nitrogen_dioxide": [19.0], "dust_aod_550nm": [0.24]
  },
  "units": {"pm2_5": "ug/m3", "pm10": "ug/m3", "dust_aod_550nm": "1"}
}

All concentrations are in µg/m³, the unit air quality is quoted in everywhere. dust_aod_550nm is an optical depth and has no unit: above about 0.5 the sky is visibly hazy, above 1.0 the sun is dimmed.

The WHO short-term guideline values ride along in every response so a number can be placed without looking it up. band follows the European air quality index for PM2.5: good, fair, moderate, poor, very poor, extremely poor.

Snow and the snow line#

Four fields, and they answer different questions. snowfall is how much falls; the rest describe what is on the ground and where.

Ask for them by name — they are not in the default response:

GET /v1/forecast?lat=45.19&lon=5.72&hourly=snowfall,snow_depth,snow_water_equivalent,snow_line_altitude,freezing_level_altitude

The snow line is the one worth reading. "It rains at 800 m and snows at 1200" is a decision a ski resort, a road authority or a driver can act on; "3 mm of precipitation" is not. It matters in North Africa too — the Atlas has ski areas at Chréa and Tikjda, and the high plateaux at Sétif, Batna and Djelfa sit above 1000 m.

These come from DWD's ICON, which covers the world at 13 km. ECMWF's open data publishes snow depth but not the snow line, so this is one place where the coarser model is the more useful one. snow_line_altitude is a regional product: ICON-EU and ICON-D2 publish it, ICON global does not, so outside Europe you get the freezing level and the depth but not the line itself.

Marine — sea state#

{
  "hourly": {
    "time": ["2026-08-01T00:00:00+00:00"],
    "wave_height": [0.32],
    "wave_direction": [264.3],
    "wave_period": [3.79],
    "wave_peak_period": [4.21]
  }
}

Wave height is the significant height — the mean of the highest third of the waves, which is roughly what an observer at sea reports. Individual waves reach about twice it, which is the number that matters if you are deciding whether to go out. Direction is where the waves come from, like wind direction.

Rivers#

It answers what no weather model can: not how much rain falls upstream, but how much water arrives here — a different number, separated from the rain by a catchment, a soil moisture state and a day or two of travel time.

{
  "disclaimer": "Information only. Only national and regional authorities
                 are authorised to issue flood warnings.",
  "daily": {
    "time": ["2026-08-01T00:00:00+00:00"],
    "river_discharge": [4.953],
    "soil_wetness_index": [0.448]
  }
}