Zacznij tutaj

Czym to jest#

Climate Memory serwuje trzy produkty z dwóch hostów, na jednym kluczu API.

Dwa hosty zamiast jednego, bo stopniodni czytają inne archiwum o innym profilu kosztów, a rozdzielenie ich pozwala jednemu być wolnym bez spowalniania drugiego. Poza skopiowaniem właściwego adresu bazowego nie musi cię to obchodzić.

Twoje pierwsze wywołanie#

Trzy kroki. Całość zajmuje jakąś minutę.

1. Odbierz klucz

Załóż konto na developers.climatememory.com/signin. Plan darmowy nie wymaga karty, daje 10 000 kredytów miesięcznie, a klucz pojawia się na ekranie od razu. Trzymaj go w zmiennej środowiskowej — wszystkie poniższe przykłady czytają $API_KEY.

export API_KEY="wd_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

2. Wykonaj wywołanie

curl -sH "X-API-Key: $API_KEY" \
  "https://api.climatememory.com/v1/forecast?lat=48.85&lon=2.35&days=3"

import os, httpx

r = httpx.get(
    "https://api.climatememory.com/v1/forecast",
    params={"lat": 48.85, "lon": 2.35, "days": 3},
    headers={"X-API-Key": os.environ["API_KEY"]},
    timeout=30,
)
r.raise_for_status()
data = r.json()
print(data["daily"]["temperature_2m_max"])

const res = await fetch(
  "https://api.climatememory.com/v1/forecast?lat=48.85&lon=2.35&days=3",
  { headers: { "X-API-Key": process.env.API_KEY } },
);
if (!res.ok) {
  const { error } = await res.json();
  throw new Error(`${error.code}: ${error.message}`);
}
const data = await res.json();
console.log(data.daily.temperature_2m_max);

req, _ := http.NewRequest("GET",
    "https://api.climatememory.com/v1/forecast?lat=48.85&lon=2.35&days=3", nil)
req.Header.Set("X-API-Key", os.Getenv("API_KEY"))

res, err := http.DefaultClient.Do(req)
if err != nil { return err }
defer res.Body.Close()

var out struct {
    Daily struct {
        TemperatureMax []float64 `json:"temperature_2m_max"`
    } `json:"daily"`
}
json.NewDecoder(res.Body).Decode(&out)

3. Przeczytaj odpowiedź

Każdy szereg wraca zorientowany kolumnowo — jako równoległe tablice dzielące jeden indeks time, a nie lista obiektów. Zobacz konwencje odpowiedzi, żeby dowiedzieć się dlaczego i jak to czytać.

Uwierzytelnianie#

Wysyłaj klucz w nagłówku X-API-Key przy każdym żądaniu. Nie ma przepływu OAuth, nie ma tokenu bearer do odświeżania ani podpisu do policzenia.

X-API-Key: wd_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Klucze są przechowywane w postaci skrótu. Jeśli któryś zgubisz, zostanie zrotowany, a nie odzyskany — nie możemy ci go pokazać ponownie, bo go nie mamy. Rotacja jest w konsoli i natychmiast wydaje nowy klucz.

Scope'y

Klucz niesie scope'y, a o tym, które, decyduje plan. Wywołanie endpointu spoza twoich scope'ów zwraca 403 scope_denied — to problem planu, a nie klucza, i komunikat to mówi.

Endpointy geokodowania nie wymagają żadnego z nich. Dowolny ważny klucz rozwiązuje nazwę miejsca, w każdym planie, bo każdy produkt tutaj potrzebuje współrzędnej, zanim cokolwiek odpowie. Zobacz geokodowanie.

Geokodowanie#

Parametry

Katalog to klasa obiektów P z GeoNames w całości — każde zamieszkane miejsce na Ziemi, aż po przysiółki liczące kilkadziesiąt osób, a nie wyciąg przefiltrowany po liczbie ludności. Wieś licząca 528 mieszkańców w nim jest.

Dopasowanie nigdy nie jest ograniczane językiem

Zapytanie jest sprawdzane względem nazwy lokalnej, jej transliteracji ASCII i każdego zlokalizowanego aliasu, cokolwiek mówi lang. To znaczy więcej, niż brzmi: 98 % miejsc nie ma żadnej nazwy zlokalizowanej — francuski pokrywa 1,84 % katalogu — więc wyszukiwanie filtrowane językiem znajduje stolice i nic więcej. lang wybiera, która nazwa wraca, i wpływa na kolejność; nigdy nie decyduje, co jest brane pod uwagę.

GET /v1/geocode?q=ramillies&lang=fr
GET /v1/geocode?q=ramillies&lang=fr&near=50.63,3.06   # z Lille
GET /v1/geocode?q=bruxelles&lang=fr                     # egzonim, przez indeks aliasów
GET /v1/geocode?q=zuesch&lang=de                        # umlaut zapisany rozwinięciem

Jak wyniki są układane

Każdy wynik niesie score, a gdy podano near — także distance_km. Kolejność łączy cztery sygnały: jak dobrze nazwa pasowała, jak znaczące jest miejsce, jak blisko jest near i czy dopasowana nazwa była w żądanym języku.

Po co istnieje near. Są dwie miejscowości Ramillies — 5 749 mieszkańców w Brabancji Walońskiej, 528 w regionie Hauts-de-France, 126 km od siebie. Żadna nie jest właściwą odpowiedzią w oderwaniu od kontekstu. Bez near wraca ta większa; z Lille — ta francuska.

Znaczenie to nie sama liczba ludności. 90,7 % katalogu nie ma zapisanej ludności — dla części krajów GeoNames nie publikuje jej wcale — więc tam, gdzie ludności brak, kolejność niesie typ miejsca (stolica kraju, siedziba jednostki administracyjnej, zwykła miejscowość, dzielnica).

Umlauty są rozwijane, a nie porzucane. Niemiecka albo duńska klawiatura bez znaków diakrytycznych pisze Zuesch zamiast Züsch i Koeln zamiast Köln. GeoNames nie ma tego zapisu — jego forma ASCII to Zusch, z umlautem usuniętym, a nie rozwiniętym — więc jest generowany tutaj. Oba zapisy docierają do miejsca, a wynik i tak pokazuje prawdziwą nazwę.

Wyszukiwanie miast#

/v1/cities/search jest starszy niż /v1/geocode i zachowuje swój kontrakt dla tych, którzy już na nim zbudowali: dopasowuje wyłącznie nazwę ASCII i porządkuje według liczby ludności.

/v1/cities/nearest to kierunek odwrotny i to on zamienia pozycję GPS w slug miasta, który można potem podać endpointom miejskim. Przyjmuje lat, lon i opcjonalne max_km.

Oba liczą się do tego samego pułapu geokodowania co /v1/geocode i żaden nie kosztuje kredytów.

Konwencje odpowiedzi#

Sześć reguł obowiązuje w każdym endpoincie. Naucz się ich raz, a reszta tej dokumentacji to już tylko nazwy pól.

1. Szeregi to kolumny, nie wiersze

Każdy szereg czasowy to zestaw równoległych tablic dzielących jeden indeks time, a nie tablica obiektów:

"hourly": {
  "time":           ["2026-08-01T00:00:00+00:00", "2026-08-01T01:00:00+00:00"],
  "temperature_2m": [18.4, 18.1],
  "precipitation":  [0.0, 0.2]
}

Indeks i każdej tablicy opisuje ten sam moment. To trzy do pięciu razy mniej danych na łączu niż postać wierszowa, dekoduje się wprost do ramki danych albo biblioteki wykresów bez przekształcania i jest tym, czego klienci pisani pod Open-Meteo już oczekują. Aby przejść po tym wierszami:

rows = zip(h["time"], h["temperature_2m"], h["precipitation"])

2. Czasy są w ISO 8601 z jawnym przesunięciem

Zawsze. 2026-08-01T00:00:00+00:00, nigdy goły łańcuch lokalny ani liczba uniksowa. Gdy podasz timezone, przesunięcie w odpowiedzi jest przesunięciem tej strefy — więc sam łańcuch jest jednoznaczny i nigdy nie musisz wiedzieć, co założyliśmy.

3. Jednostki są w SI, stałe i nie podlegają negocjacji

°C, mm, m/s, hPa, W/m², metry. Nie ma parametru units=imperial, i to celowo: przełącznik jednostek to pole, którego znaczenie zależy od innego pola, i tak właśnie wywołujący kończy z Fahrenheitem na osi w stopniach Celsjusza po zmianie konfiguracji, której nikt nie przejrzał. Przeliczaj na swojej krawędzi, tam gdzie jest czytelnik.

Endpointy o nietypowych jednostkach dołączają do odpowiedzi blok units, który nazywa je wprost, zamiast liczyć na twoją pamięć.

4. null znaczy „nie wiadomo”, nigdy „zero”

Brakująca godzina to null w tablicy, trzymający swoją pozycję, żeby indeksy pozostały zgodne. Nigdy nie jest po cichu wypełniana zerem — dla opadu to dwa przeciwne twierdzenia, a jedno z nich to kłamstwo o suszy.

5. Każda odpowiedź mówi, skąd pochodzi

Wraz z danymi podróżuje blok source (pogoda) albo blok quality (archiwa): który model lub przebieg odpowiedział, jak stary jest, jak kompletny był okres. Nigdy nie musisz wnioskować świeżości z zegara.

6. Nieświeże jest lepsze niż nic

Jeśli nasz najnowszy przebieg modelu jest starszy, niż powinien, i tak odpowiadamy — z "stale": true i data_age_hours w bloku source — zamiast zwracać 503. Prognoza sprzed ośmiu godzin jest użyteczniejsza niż błąd. Sprawdź flagę, jeśli świeżość jest dla ciebie nośna; zignoruj ją, jeśli nie.

Limity tempa, kredyty i przydział#

Obowiązują trzy niezależne limity i celowo zawodzą w różny sposób. Każda udana odpowiedź mówi, gdzie stoisz:

Kredyty, nie żądania

Zbuforowana prognoza dla miasta to odczyt trwający 3 ms. Dziesięć lat godzinowych stopniodni dla pięciuset lokalizacji już nie. Wycena za żądania pozwoliłaby wywołującemu zmieścić się w przydziale i kosztować więcej, niż płaci, całkowicie legalnie — więc koszt wywołania zależy od tego, ile archiwum przenosi.

Co robić, gdy trafisz w każdy z nich

Twój okres rozliczeniowy biegnie od daty subskrypcji do tego samego dnia następnego miesiąca — to okres, który fakturuje Stripe — a licznik za każdym razem zaczyna od pełna. X-Quota-Resets-At niesie tę datę w każdej odpowiedzi, więc odczytuj ją, zamiast zakładać pierwszy dzień miesiąca. Konta bez subskrypcji idą według miesiąca kalendarzowego.

Błędy#

Każdy błąd ma ten sam kształt, na obu hostach:

{
  "error": {
    "code": "range_too_long",
    "message": "Requested span is 14.0 years; the maximum per request is 10.",
    "max_years": 10
  }
}

To cała lista i przy każdym budowaniu jest zestawiana ze źródłem: kod opublikowany tutaj, którego żaden handler nie zgłasza, wywraca testy — tak samo jak handler zgłaszający kod, którego nie ma w tej tabeli. Jeśli natrafisz na kod spoza powyższej listy, to błąd tej strony, a nie wartość, którą należy obsłużyć osobno.

Polityka ponawiania, która działa

RETRY = {"rate_limited", "data_unavailable"}

def should_retry(status, code, attempt):
    if code == "quota_exceeded":
        return False              # nic się nie zmieni do resetu
    if code == "geocode_quota_exceeded":
        return False              # i nie przerywaj: kredyty nadal działają
    if code in RETRY:
        return attempt < 5
    return status >= 500

Dokładność — czego się spodziewać#

Wolimy właściwie ustawić oczekiwania, niż pozwolić ci odkryć ograniczenia na produkcji.

Gdzie prognoza jest mocna

Temperatura, ciśnienie, wiatr synoptyczny, wilgotność, usłonecznienie. Typowy błąd temperatury na 2 m po 24 godzinach to około 1–1,5 °C. ECMWF jest najlepszym globalnym modelem deterministycznym na świecie i to właśnie dostajesz.

Gdzie jest słabsza

Burze konwekcyjne — komórka 28 km nie rozdzieli burzy, a nawet 3 km ledwie ją zasugeruje. Dokładne miejsce i czas przelotnych opadów. Mikroklimat wybrzeży i gór poniżej rozdzielczości modelu. Bryzy morskie i zastoiska zimnego powietrza w dolinach, których korekta terenu nie modeluje.

Uczciwość geograficzna

We Francji, Niemczech, USA i Kanadzie serwujemy modele krajowe o rozdzielczości 1,3–3 km i mała wieś naprawdę dostaje własną komórkę siatki. W pozostałej części Europy dostajesz 6,5 km. W Afryce, na Bliskim Wschodzie i w większości Azji najlepszy dostępny model publiczny ma 13–28 km, więc dostajesz pogodę okolicy, a nie ulicy. Korekta terenu zawęża tę lukę, ale jej nie zamyka.

Stopniodni

Reanaliza siatkowa pokrywa wszystko, także miejsca bez stacji meteorologicznej w promieniu 60 km — to jej przewaga nad dostawcami opartymi na stacjach. Jej słabością są centra miast, które reanaliza zaniża; endpointy miejskie stosują skalibrowaną korektę, endpointy współrzędnych nie.

Dwa pola są szacunkami i wolimy to powiedzieć

uv_index wywodzi się z wysokości Słońca i promieniowania szerokopasmowego, a nie z kolumny ozonu — z dokładnością mniej więcej ±1 jednostki. precipitation_probability_proxy to oszacowanie, a nie prawdopodobieństwo; prawdziwe jest pod /v1/probability. Oba są w całości wyjaśnione w dokumentacji pól.

Plany#

Geokodowanie stoi poza tą tabelą: nie kosztuje kredytów w żadnym planie i ma własny pułap pięciu żądań na kredyt. Zobacz limity tempa i przydział.

Rozliczenie roczne to dwa miesiące gratis. Aktualny cennik jest na developers.climatememory.com/pricing — ta strona czyta wprost system rozliczeniowy, więc jeśli obie kiedykolwiek się nie zgodzą, wygrywa ona.

W żadnym planie nie ma endpointu masowego eksportu. Eksport CSV istnieje w archiwach stopniodni i klimatu, jest ograniczony do tego samego zakresu co równoważne wywołanie JSON i zwraca wyłącznie wiersze zagregowane — nigdy szeregu godzinowego.

Atrybucja i licencje#

Oba powyższe endpointy nie wymagają klucza, więc możesz wyrenderować tę informację z API, zamiast zaszywać w kodzie łańcuch, który zdezaktualizuje się przy zmianie źródła. Atrybucja konkretnego przebiegu, który odpowiedział, podróżuje też w każdej odpowiedzi z danymi, w source.attribution i w nagłówku X-Data-Attribution.

Możesz podać, że korzystasz z tych danych. Nie możesz sugerować, że którakolwiek z tych organizacji stworzyła, zatwierdziła lub popiera twój produkt.

Zastrzeżenie

Prognozy są udostępniane bez gwarancji. Ani Komisja Europejska, ani ECMWF, DWD, NOAA czy Météo-France nie odpowiadają za jakiekolwiek wykorzystanie tych informacji. Nie używaj ich jako jedynej podstawy decyzji, w których zagrożone jest życie, bezpieczeństwo lub mienie.

Jednego ograniczenia nie możemy znieść: licencja Copernicus zastrzega ostrzeżenia powodziowe dla władz krajowych i regionalnych. Zobacz rzeki.