API Pogoda

Prognoza#

Parametry

Odpowiedź

{
  "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, "..."]
  }
}

Zmniejszanie odpowiedzi

Pełny blok godzinowy na 15 dni to około 32 pól × 360 godzin. Jeśli rysujesz trzy z nich, poproś o trzy:

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

Ta sama cena — kosztuje odczyt archiwum, a nie serializacja — ale dziesięć razy mniej bajtów i zauważalnie szybsze parsowanie na telefonie.

Prognoza dla miasta#

Gdzie tylko możesz, wybieraj to zamiast surowych współrzędnych. Katalog dostarcza dwóch rzeczy, których współrzędna nie potrafi: prawdziwej wysokości miasta, dzięki czemu korekta terenu działa bez podawania jej przez ciebie, oraz jego strefy czasowej, dzięki czemu agregaty dobowe są cięte na właściwym dniu lokalnym.

GET /v1/forecast/city/dz/alger      # slug francuski
GET /v1/forecast/city/dz/algiers    # slug angielski — to samo miasto
GET /v1/forecast/city/fr/paris

country to kod ISO-3166-1 alfa-2, małymi literami. slug nie zważa na znaki diakrytyczne: bejaia znajduje Béjaïa. Nieznany slug zwraca 404 city_not_found z tablicą suggestions — pokaż ją zamiast ślepego zaułka.

Wszystkie parametry zapytania z /v1/forecast nadal obowiązują poza lat, lon i elevation, które dostarcza katalog. Podanie timezone nadpisuje strefę miasta, co prawie nigdy nie jest tym, czego chcesz.

Warunki bieżące#

Temperatura, wilgotność, wiatr i ciśnienie są interpolowane liniowo do bieżącej chwili, między dwoma krokami modelu, które ją obejmują.

Użyj tego do pokazania stanu „teraz”. Do czegokolwiek, co będziesz porównywać w czasie, użyj /v1/forecast i odczytaj interesującą cię godzinę: szereg jest stabilny, podczas gdy teraz przesuwa się pod tobą między dwoma wywołaniami.

Dokumentacja pól#

Pola godzinowe

21 z nich wraca domyślnie. Reszta jest twoja na życzenie — wymień je w hourly=, po przecinku — i są wstrzymane ze względu na koszt, a nie z wątpliwości: każde zapisane pole to osobny skompresowany odczyt, więc domyślna odpowiedź niosąca wszystkie 45 kazałaby każdemu płacić za tych nielicznych, którzy chcą grubości pokrywy śnieżnej.

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

Pole, którego dany model nie publikuje, wraca jako null na odcinku prognozy tego modelu, zamiast znikać z odpowiedzi — więc łańcuch, który zaczyna się na AROME i biegnie dalej na ICON-EU, zwraca visibility przez cały czas, puste przez pierwsze 51 godzin. Nieznana nazwa pola to 400 unknown_field, z podpowiedzianym najbliższym dopasowaniem; kiedyś była po cichu ignorowana.

Pola dobowe

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.

Agregowane na lokalnych dniach kalendarzowych, a nie na UTC. Niepełny dzień na którymkolwiek krańcu zakresu jest pomijany, zamiast być raportowanym z mylącym maksimum — więc żądanie na 7 dni może zgodnie z prawdą zwrócić 6 wierszy dobowych.

Modele i rozdzielczość#

Serwujemy najdrobniejszy model, który pokrywa twój punkt i twoje wyprzedzenie. Nigdy go nie wybierasz; wybór jest raportowany w source.model, żebyś zawsze wiedział, który odpowiedział.

Modele wysokiej rozdzielczości są wyłącznie krótkoterminowe — przy 1 km atmosfera staje się chaotyczna w ciągu dwóch dni, więc prognozowanie dalej nie miałoby sensu — i rozdzielczość schodzi więc w dół w miarę biegu prognozy:

dzień 0 ───── dzień 2 ───── dzień 5 ─────────────── dzień 15
  AROME 1,3 km (Francja)
  ICON-D2 2,2 km (Niemcy, Alpy, Beneluks)
  HRRR 3 km (USA i południe Kanady)
              ICON-EU 6,5 km (Europa)
                          ICON 13 km · ECMWF 28 km (globalnie)
                                              AIFS (tylko tendencja)

Przejścia przez krawędź domeny modelu są wzajemnie wygaszane, więc dwie miejscowości po obu stronach granicy nigdy nie różnią się skokowo.

/v1/models nie wymaga klucza, co czyni go właściwą rzeczą do odpytywania ze strony statusu albo do sprawdzenia przed zakupem: raportuje najnowszy przebieg każdego modelu i jego wiek, więc na pytanie „czy dane są świeże” da się odpowiedzieć bez wydawania kredytu.

Prawdopodobieństwa z ensemble'u#

Pojedyncza prognoza mówi 22 °C w czwartek. To domysł podany jak fakt. Ten endpoint odpowiada na pytanie, na podstawie którego naprawdę decydujesz: jak bardzo jest to pewne i jakie prawdopodobieństwo deszczu warto wziąć pod uwagę w planach.

Liczone jest z ensemble'u ECMWF — tego samego modelu puszczonego 50 razy z lekko różnych warunków początkowych. Tam, gdzie przebiegi się zgadzają, prognoza jest pewna. Tam, gdzie się rozjeżdżają, niepewna jest sama atmosfera i żaden model, choćby najlepszy, nie powie ci więcej.

{
  "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]
  }
}

Jak to czytać

p10 i p90 obejmują środkowe 80 % członków: jeden na dziesięciu spodziewa się chłodniej niż p10, jeden na dziesięciu cieplej niż p90. spread równy 0,4 °C to sytuacja ustabilizowana, której możesz ufać; 3 °C oznacza, że modele się nie zgadzają i powinieneś powiedzieć o tym użytkownikom, zamiast wybierać jeden.

Progi opadu to decyzje, a nie okrągłe liczby — 0,1 mm to w ogóle mokro, 1 mm to weź kurtkę, 5 i 10 mm to to już problem. precipitation_p90 to zły scenariusz: tylko jeden członek na dziesięciu jest bardziej mokry.

Jakość powietrza#

To endpoint, który najbardziej liczy się w Afryce Północnej i nad Morzem Śródziemnym. Epizod pyłowy wynosi PM10 ponad tysiąc mikrogramów na metr sześcienny na całe dnie, co jest decyzją zdrowotną, a nie liczbą, i jest słabo pokryty przez darmowe serwisy konsumenckie.

{
  "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"}
}

Wszystkie stężenia są w µg/m³, jednostce, w której jakość powietrza podaje się wszędzie. dust_aod_550nm to grubość optyczna i nie ma jednostki: powyżej mniej więcej 0,5 niebo jest widocznie zamglone, powyżej 1,0 słońce jest przygaszone.

Krótkoterminowe wartości wytyczne WHO jadą w każdej odpowiedzi, żeby dało się umiejscowić liczbę bez szukania. band podąża za europejskim indeksem jakości powietrza dla PM2,5: dobra, w porządku, umiarkowana, zła, bardzo zła, skrajnie zła.

Śnieg i granica śniegu#

Cztery pola, a odpowiadają na różne pytania. snowfall to ile spada; reszta opisuje to, co leży, i gdzie.

Poproś o nie po nazwie — nie ma ich w domyślnej odpowiedzi:

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

To granica śniegu jest tą wartą odczytania. „Na 800 m pada deszcz, a na 1200 śnieg” to informacja, na podstawie której ośrodek narciarski, zarządca drogi albo kierowca mogą działać; „3 mm opadu” nie jest. Liczy się to także w Afryce Północnej — Atlas ma ośrodki narciarskie w Chréa i Tikjda, a wysokie płaskowyże pod Sétif, Batną i Dżelfą leżą powyżej 1000 m.

Te dane pochodzą z ICON-a od DWD, który pokrywa świat w 13 km. Otwarte dane ECMWF publikują grubość śniegu, ale nie granicę śniegu, więc to jeden z przypadków, w których model zgrubniejszy jest użyteczniejszy. snow_line_altitude jest produktem regionalnym: ICON-EU i ICON-D2 go publikują, ICON globalny nie, więc poza Europą dostajesz poziom zera stopni i grubość, ale nie samą granicę.

Morze — stan morza#

{
  "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]
  }
}

Wysokość fali to wysokość znacząca — średnia z najwyższej jednej trzeciej fal, czyli mniej więcej to, co raportuje obserwator na morzu. Pojedyncze fale sięgają około dwukrotności tej wartości i to ta liczba ma znaczenie, jeśli decydujesz, czy wypłynąć. Kierunek to ten, z którego fale idą, tak jak przy wietrze.

Rzeki#

Odpowiada na to, czego nie potrafi żaden model pogodowy: nie ile deszczu pada w górze zlewni, ale ile wody dociera tutaj — a to inna liczba, oddzielona od deszczu zlewnią, stanem wilgotności gleby i dniem lub dwoma przepływu.

{
  "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]
  }
}