Aan de slag

Waar het om gaat#

Climate Memory levert drie producten vanaf twee hosts, op één API-sleutel.

Twee hosts in plaats van één omdat graaddagen een ander archief lezen met een ander kostenprofiel, en ze scheiden laat de een traag zijn zonder de ander te vertragen. Verder dan het kopiëren van de juiste basis-URL hoeft u zich er niet om te bekommeren.

Uw eerste aanroep#

Drie stappen. Het geheel duurt ongeveer een minuut.

1. Een sleutel krijgen

Maak een account aan op developers.climatememory.com/signin. Het gratis abonnement vraagt geen kaart, geeft u 10 000 credits per maand, en uw sleutel staat meteen op het scherm. Bewaar hem in een omgevingsvariabele — alle voorbeelden hieronder lezen $API_KEY.

export API_KEY="wd_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

2. De aanroep doen

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. Het antwoord lezen

Elke reeks komt kolomgeoriënteerd terug — parallelle arrays die één time-index delen, niet een lijst met objecten. Zie antwoordconventies voor het waarom, en voor hoe u ze leest.

Authenticatie#

Stuur uw sleutel bij elk verzoek mee in de X-API-Key-header. Er is geen OAuth-stroom, geen bearer-token om te vernieuwen en geen handtekening om te berekenen.

X-API-Key: wd_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Sleutels worden gehasht opgeslagen. Raakt u er een kwijt, dan wordt hij vernieuwd, niet hersteld — wij kunnen hem u niet opnieuw tonen, omdat wij hem niet hebben. Vernieuwen gebeurt in de console en geeft meteen een nieuwe sleutel uit.

Scopes

Een sleutel draagt scopes, en het abonnement beslist welke. Een endpoint buiten uw scopes aanroepen geeft 403 scope_denied — dat is een abonnementsprobleem, geen sleutelprobleem, en het bericht zegt dat ook.

De geocodering-endpoints vereisen er geen enkele. Elke geldige sleutel lost een plaatsnaam op, op elk abonnement, omdat elk product hier een coördinaat nodig heeft voordat het ook maar iets kan beantwoorden. Zie geocodering.

Geocodering#

Parameters

De catalogus is GeoNames-featureklasse P in zijn geheel — elke bewoonde plaats op aarde, tot gehuchten van enkele tientallen mensen, en geen op bevolking gefilterd uittreksel. Een dorp van 528 inwoners staat erin.

De match wordt nooit door de taal beperkt

De zoekterm wordt getoetst aan de lokale naam, de ASCII-transliteratie ervan en elke gelokaliseerde alias, wat lang ook zegt. Dat telt zwaarder dan het klinkt: 98 % van de plaatsen heeft helemaal geen gelokaliseerde naam — het Frans dekt 1,84 % van de catalogus — zodat een op taal gefilterde zoekopdracht hoofdsteden zou vinden en verder niets. lang kiest welke naam terugkomt en beïnvloedt de rangschikking; het beslist nooit wat in aanmerking komt.

GET /v1/geocode?q=ramillies&lang=fr
GET /v1/geocode?q=ramillies&lang=fr&near=50.63,3.06   # vanuit Rijsel
GET /v1/geocode?q=bruxelles&lang=fr                     # exoniem, via de aliasindex
GET /v1/geocode?q=zuesch&lang=de                        # umlaut uitgeschreven

Hoe resultaten worden gerangschikt

Elk resultaat draagt een score en, wanneer near is meegegeven, een distance_km. De rangschikking combineert vier signalen: hoe goed de naam overeenkwam, hoe prominent de plaats is, hoe dicht ze bij near ligt, en of de gevonden naam in de gevraagde taal stond.

Waarom near bestaat. Er zijn twee Ramillies — 5 749 inwoners in Waals-Brabant, 528 in Hauts-de-France, 126 km uit elkaar. Geen van beide is in abstracto het juiste antwoord. Zonder near wordt de grootste teruggegeven; vanuit Rijsel de Franse.

Prominentie is niet alleen bevolking. Voor 90,7 % van de catalogus is geen bevolking vastgelegd — voor sommige landen publiceert GeoNames er in het geheel geen — zodat het plaatstype (hoofdstad, hoofdplaats van een bestuurlijke eenheid, gewone plaats, wijk) de rangschikking draagt overal waar bevolking ontbreekt.

Umlauten worden uitgeschreven, niet weggelaten. Een Duits of Deens toetsenbord zonder diakritische tekens schrijft Zuesch voor Züsch en Koeln voor Köln. GeoNames voert die spelling niet — de ASCII-vorm is Zusch, met de umlaut verwijderd in plaats van uitgeschreven — dus wordt ze hier gegenereerd. Beide spellingen bereiken de plaats, en het resultaat toont in beide gevallen de echte naam.

Stad opzoeken#

/v1/cities/search gaat vooraf aan /v1/geocode en behoudt zijn contract voor de aanroepers die er al op gebouwd zijn: het toetst alleen de ASCII-naam en sorteert op bevolking.

/v1/cities/nearest is de omgekeerde richting, en is wat een GPS-positie omzet in een stads-slug die u daarna aan de stads-endpoints kunt meegeven. Het neemt lat, lon en een optionele max_km.

Beide tellen mee voor hetzelfde geocodering-plafond als /v1/geocode, en geen van beide kost credits.

Antwoordconventies#

Zes regels gelden voor elk endpoint. Leer ze één keer en de rest van deze documentatie bestaat alleen nog uit veldnamen.

1. Reeksen zijn kolommen, geen rijen

Elke tijdreeks is een verzameling parallelle arrays die één time-index delen, in plaats van een array met objecten:

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

Index i van elke array beschrijft hetzelfde moment. Dit is over de lijn drie tot vijf keer kleiner dan de rijvorm, het decodeert rechtstreeks in een dataframe of een plotbibliotheek zonder omzetting, en het is wat clients in Open-Meteo-vorm al verwachten. Om er rijgewijs doorheen te lopen:

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

2. Tijden zijn ISO 8601 met expliciete verschuiving

Altijd. 2026-08-01T00:00:00+00:00, nooit een kale lokale tekenreeks en nooit een Unix-geheel getal. Waar u een timezone meegeeft, is de verschuiving in het antwoord die van die zone — de tekenreeks alleen is dus ondubbelzinnig, en u hoeft nooit te weten wat wij hebben aangenomen.

3. Eenheden zijn SI, vast en nooit onderhandelbaar

°C, mm, m/s, hPa, W/m², meters. Er is met opzet geen parameter units=imperial: een eenhedenschakelaar is een veld waarvan de betekenis van een ander veld afhangt, en zo komt een aanroeper er na een niet nagekeken configuratiewijziging toe Fahrenheit op een Celsius-as uit te zetten. Reken om aan uw rand, waar de lezer zit.

Endpoints met ongebruikelijke eenheden sturen in het antwoord een units-blok mee dat ze uitdrukkelijk benoemt, in plaats van te verwachten dat u het onthoudt.

4. null betekent „onbekend”, nooit „nul”

Een ontbrekend uur is null in de array en behoudt zijn plaats zodat de indices uitgelijnd blijven. Het wordt nooit stilzwijgend met 0 gevuld — voor neerslag zijn dat twee tegengestelde beweringen, en een van beide is een leugen over een droogte.

5. Elk antwoord zegt waar het vandaan komt

Een source-blok (weer) of een quality-blok (archieven) reist met de data mee: welk model of welke run heeft geantwoord, hoe oud die is, hoe volledig de periode was. U hoeft de versheid nooit uit de klok af te leiden.

6. Verouderd wint van afwezig

Is onze nieuwste modelrun ouder dan verwacht, dan antwoorden wij toch — met "stale": true en data_age_hours in het source-blok — in plaats van een 503 terug te geven. Een verwachting van acht uur oud is nuttiger dan een fout. Controleer de vlag als versheid voor u doorslaggevend is; negeer haar anders.

Tempolimieten, credits en quotum#

Er gelden drie onafhankelijke limieten, en ze falen met opzet verschillend. Elk geslaagd antwoord meldt waar u staat:

Credits, geen verzoeken

Een gecachte stadsverwachting is een leesbewerking van 3 ms. Tien jaar uurlijkse graaddagen over vijfhonderd locaties niet. Op verzoeken prijzen zou een aanroeper binnen zijn quotum kunnen laten blijven en toch meer kosten dan hij betaalt, volkomen legitiem — wat een aanroep kost hangt dus af van hoeveel archief hij verplaatst.

Wat te doen wanneer u er een raakt

Uw quotumperiode loopt van uw abonnementsdatum tot dezelfde dag van de volgende maand — de periode die Stripe factureert — en de teller begint elke keer weer heel opnieuw. X-Quota-Resets-At draagt die datum in elk antwoord: lees hem in plaats van de eerste van de maand aan te nemen. Accounts zonder abonnement volgen de kalendermaand.

Fouten#

Elke fout heeft dezelfde vorm, op beide hosts:

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

Dat is de volledige lijst, en ze wordt bij elke build tegen de broncode gecontroleerd: een hier gepubliceerde code die geen enkele handler oproept laat de testsuite falen, en een handler die er een oproept die deze tabel niet voert evengoed. Komt u een code tegen die hierboven ontbreekt, dan is dat een gebrek van deze pagina en geen waarde die u apart moet behandelen.

Een herhaalstrategie die werkt

RETRY = {"rate_limited", "data_unavailable"}

def should_retry(status, code, attempt):
    if code == "quota_exceeded":
        return False              # er verandert niets tot de herstart
    if code == "geocode_quota_exceeded":
        return False              # en stop niet: credits werken nog
    if code in RETRY:
        return attempt < 5
    return status >= 500

Nauwkeurigheid — wat te verwachten#

Wij stellen de verwachtingen liever goed dan dat u de grenzen in productie ontdekt.

Waar de verwachting sterk is

Temperatuur, druk, synoptische wind, luchtvochtigheid, zonneschijn. De typische fout van de 2 m-temperatuur op 24 uur ligt rond 1 tot 1,5 °C. Het ECMWF is het beste globale deterministische model ter wereld, en dat is wat u krijgt.

Waar ze zwakker is

Convectieve onweersbuien — een cel van 28 km kan een onweersbui niet oplossen, en zelfs 3 km hint er slechts naar. De exacte plaats en het exacte moment van buien. Kust- en bergmicroklimaat onder de modelresolutie. Zeewind en koude luchtpoelen in dalen, die de terreincorrectie niet modelleert.

Geografische eerlijkheid

In Frankrijk, Duitsland, de VS en Canada leveren wij nationale modellen van 1,3 tot 3 km, en een klein dorp krijgt werkelijk zijn eigen rastercel. Elders in Europa krijgt u 6,5 km. In Afrika, het Midden-Oosten en het grootste deel van Azië is het beste beschikbare publieke model 13 tot 28 km, dus krijgt u het weer van de streek in plaats van dat van de straat. De terreincorrectie verkleint dat gat, maar dicht het niet.

Graaddagen

Een heranalyse op raster dekt overal, ook locaties zonder weerstation binnen 60 km — dat is haar voordeel ten opzichte van aanbieders op basis van stations. Haar zwakte zijn stadscentra, die de heranalyse te laag leest; de stads-endpoints passen een gekalibreerde correctie toe, de coördinaat-endpoints niet.

Twee velden zijn schattingen, en dat zeggen wij liever

uv_index is afgeleid uit de zonnehoogte en breedbandstraling, niet uit een ozonkolom — nauwkeurig tot ongeveer ±1 eenheid. precipitation_probability_proxy is een schatting, geen kans; de echte staat op /v1/probability. Beide worden volledig uitgelegd in de veldreferentie.

Abonnementen#

Geocodering staat buiten deze tabel: het kost op geen enkel abonnement credits en draagt een eigen plafond van vijf verzoeken per credit. Zie tempolimieten en quotum.

Jaarlijkse facturering geeft twee maanden gratis. De actuele catalogus staat op developers.climatememory.com/pricing — die pagina leest het factureringssysteem rechtstreeks, dus mochten de twee ooit uiteenlopen, dan gaat zij voor.

Er is op geen enkel abonnement een endpoint voor massa-export. CSV-export bestaat voor de graaddagen- en klimaatarchieven, is begrensd tot hetzelfde bereik als de gelijkwaardige JSON-aanroep, en geeft alleen geaggregeerde rijen terug — nooit de uurreeks.

Naamsvermelding en licenties#

Geen van beide bovengenoemde endpoints heeft een sleutel nodig, dus u kunt de vermelding vanuit de API renderen in plaats van een tekenreeks hard in te coderen die veroudert zodra een bron verandert. De naamsvermelding van de specifieke run die heeft geantwoord reist bovendien mee met elk data-antwoord, in source.attribution en in de header X-Data-Attribution.

U mag verklaren dat u deze data gebruikt. U mag niet suggereren dat een van deze organisaties uw product heeft gemaakt, goedgekeurd of onderschrijft.

Vrijwaring

Verwachtingen worden zonder garantie geleverd. Noch de Europese Commissie, noch het ECMWF, DWD, NOAA of Météo-France is verantwoordelijk voor enig gebruik van deze informatie. Gebruik haar niet als enige grondslag voor beslissingen waarbij leven, veiligheid of eigendom op het spel staan.

Eén beperking is niet aan ons om op te heffen: de Copernicus-licentie behoudt hoogwaterwaarschuwingen voor aan nationale en regionale overheden. Zie rivieren.