Erste Schritte

Worum es geht#

Climate Memory liefert drei Produkte von zwei Hosts, mit einem einzigen API-Schlüssel.

Zwei Hosts statt einem, weil Gradtage ein anderes Archiv mit einem anderen Kostenprofil lesen, und die Trennung erlaubt es dem einen, langsam zu sein, ohne das andere zu bremsen. Sie müssen sich darum nicht kümmern, außer die richtige Basis-URL zu kopieren.

Ihr erster Aufruf#

Drei Schritte. Das Ganze dauert etwa eine Minute.

1. Einen Schlüssel holen

Legen Sie ein Konto auf developers.climatememory.com/signin an. Der kostenlose Tarif verlangt keine Karte, gibt Ihnen 10 000 Credits im Monat, und Ihr Schlüssel steht sofort auf dem Bildschirm. Bewahren Sie ihn in einer Umgebungsvariablen auf — die Beispiele unten lesen alle $API_KEY.

export API_KEY="wd_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

2. Den Aufruf machen

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. Die Antwort lesen

Jede Reihe kommt spaltenorientiert zurück — parallele Felder, die einen gemeinsamen time-Index teilen, und keine Liste von Objekten. Unter Antwortkonventionen steht, warum, und wie man sie liest.

Authentifizierung#

Senden Sie Ihren Schlüssel bei jeder Anfrage im X-API-Key-Header. Es gibt keinen OAuth-Ablauf, kein Bearer-Token zum Erneuern und keine Signatur zu berechnen.

X-API-Key: wd_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Schlüssel werden gehasht gespeichert. Wenn Sie einen verlieren, wird er erneuert, nicht wiederhergestellt — wir können ihn Ihnen nicht noch einmal zeigen, weil wir ihn nicht haben. Die Erneuerung erfolgt in der Konsole und gibt sofort einen neuen Schlüssel aus.

Scopes

Ein Schlüssel trägt Scopes, und der Tarif entscheidet, welche. Ein Endpunkt außerhalb Ihrer Scopes gibt 403 scope_denied zurück — das ist ein Tarifproblem, kein Schlüsselproblem, und die Meldung sagt das auch.

Die Geocoding-Endpunkte verlangen keinen davon. Jeder gültige Schlüssel löst einen Ortsnamen auf, in jedem Tarif, denn jedes Produkt hier braucht eine Koordinate, bevor es überhaupt antworten kann. Siehe Geocoding.

Geocoding#

Parameter

Der Katalog ist die GeoNames-Feature-Klasse P vollständig — jeder bewohnte Ort der Erde, bis hinunter zu Weilern mit ein paar Dutzend Menschen, und kein nach Einwohnerzahl gefilterter Auszug. Ein Dorf mit 528 Einwohnern ist darin.

Die Treffersuche ist nie durch die Sprache eingeschränkt

Die Anfrage wird gegen den lokalen Namen, seine ASCII-Transliteration und jeden lokalisierten Alias geprüft, ganz gleich was lang sagt. Das zählt mehr, als es klingt: 98 % der Orte haben überhaupt keinen lokalisierten Namen — Deutsch deckt einen kleinen Bruchteil des Katalogs ab — sodass eine sprachgefilterte Suche Hauptstädte fände und sonst nichts. lang wählt, welcher Name zurückkommt, und beeinflusst die Reihenfolge; es entscheidet nie, was infrage kommt.

GET /v1/geocode?q=ramillies&lang=fr
GET /v1/geocode?q=ramillies&lang=fr&near=50.63,3.06   # von Lille aus
GET /v1/geocode?q=bruxelles&lang=fr                     # Exonym, über den Alias-Index
GET /v1/geocode?q=zuesch&lang=de                        # Umlaut ausgeschrieben

Wie Treffer sortiert werden

Jeder Treffer trägt einen score und, wenn near angegeben war, eine distance_km. Die Reihenfolge verbindet vier Signale: wie gut der Name passte, wie bedeutend der Ort ist, wie nah er an near liegt, und ob der gefundene Name in der angefragten Sprache stand.

Warum es near gibt. Es gibt zwei Ramillies — 5 749 Einwohner in Wallonisch-Brabant, 528 in Hauts-de-France, 126 km auseinander. Keines ist abstrakt die richtige Antwort. Ohne near kommt das größere zurück; von Lille aus das französische.

Bedeutung ist nicht nur Einwohnerzahl. Für 90,7 % des Katalogs ist keine Einwohnerzahl hinterlegt — für manche Länder veröffentlicht GeoNames überhaupt keine — sodass überall dort, wo die Einwohnerzahl fehlt, die Ortsart (Landeshauptstadt, Sitz einer Verwaltungseinheit, gewöhnlicher Ort, Stadtteil) die Reihenfolge trägt.

Umlaute werden ausgeschrieben, nicht weggelassen. Eine deutsche oder dänische Tastatur ohne Diakritika schreibt Zuesch für Züsch und Koeln für Köln. GeoNames führt diese Schreibweise nicht — seine ASCII-Form ist Zusch, mit entferntem statt aufgelöstem Umlaut — sie wird deshalb hier erzeugt. Beide Schreibweisen erreichen den Ort, und das Ergebnis zeigt in beiden Fällen den echten Namen.

Städtesuche#

/v1/cities/search ist älter als /v1/geocode und behält seinen Vertrag für die Aufrufer, die bereits darauf aufbauen: es prüft nur den ASCII-Namen und sortiert nach Einwohnerzahl.

/v1/cities/nearest ist die Gegenrichtung und macht aus einer GPS-Position einen Städte-Slug, den Sie dann an die Stadt-Endpunkte übergeben können. Es nimmt lat, lon und ein optionales max_km.

Beide zählen gegen dieselbe Geocoding-Obergrenze wie /v1/geocode, und keines kostet Credits.

Antwortkonventionen#

Sechs Regeln gelten für jeden Endpunkt. Lernen Sie sie einmal, und der Rest dieser Dokumentation besteht nur noch aus Feldnamen.

1. Reihen sind Spalten, keine Zeilen

Jede Zeitreihe ist ein Satz paralleler Felder, die einen gemeinsamen time-Index teilen, und kein Feld von Objekten:

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

Der Index i jedes Feldes beschreibt denselben Zeitpunkt. Das ist auf der Leitung drei- bis fünfmal kleiner als die Zeilenform, es dekodiert ohne Umformung direkt in einen Dataframe oder eine Plot-Bibliothek, und es ist das, was Clients im Open-Meteo-Zuschnitt ohnehin erwarten. Um es zeilenweise zu durchlaufen:

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

2. Zeiten sind ISO 8601 mit explizitem Versatz

Immer. 2026-08-01T00:00:00+00:00, nie eine nackte lokale Zeichenkette und nie eine Unix-Ganzzahl. Wo Sie eine timezone übergeben, ist der Versatz in der Antwort der dieser Zone — die Zeichenkette allein ist damit eindeutig, und Sie müssen nie wissen, was wir angenommen haben.

3. Einheiten sind SI, fest und nicht verhandelbar

°C, mm, m/s, hPa, W/m², Meter. Es gibt absichtlich keinen Parameter units=imperial: ein Einheitenschalter ist ein Feld, dessen Bedeutung von einem anderen Feld abhängt, und so landet ein Aufrufer nach einer ungeprüften Konfigurationsänderung dabei, Fahrenheit auf einer Celsius-Achse darzustellen. Rechnen Sie an Ihrem Rand um, dort wo der Leser ist.

Endpunkte mit ungewöhnlichen Einheiten liefern in der Antwort einen units-Block mit, der sie ausdrücklich benennt, statt zu erwarten, dass Sie sich erinnern.

4. null heißt „unbekannt“, nie „null“

Eine fehlende Stunde ist null im Feld und behält ihren Platz, damit die Indizes ausgerichtet bleiben. Sie wird nie stillschweigend mit 0 gefüllt — beim Niederschlag sind das zwei gegenteilige Aussagen, und eine davon ist eine Lüge über eine Dürre.

5. Jede Antwort sagt, woher sie kommt

Ein source-Block (Wetter) oder ein quality-Block (Archive) reist mit den Daten mit: welches Modell oder welcher Lauf geantwortet hat, wie alt er ist, wie vollständig der Zeitraum war. Sie müssen die Frische nie aus der Uhr erschließen.

6. Veraltet schlägt fehlend

Wenn unser jüngster Modelllauf älter als erwartet ist, antworten wir trotzdem — mit "stale": true und data_age_hours im source-Block — statt 503 zurückzugeben. Eine acht Stunden alte Vorhersage ist nützlicher als ein Fehler. Prüfen Sie das Flag, wenn Frische für Sie tragend ist; ignorieren Sie es sonst.

Ratenlimits, Credits und Kontingent#

Drei voneinander unabhängige Grenzen gelten, und sie scheitern absichtlich unterschiedlich. Jede erfolgreiche Antwort meldet, wo Sie stehen:

Credits, keine Anfragen

Eine zwischengespeicherte Stadtvorhersage ist ein Lesevorgang von 3 ms. Zehn Jahre stündlicher Gradtage über fünfhundert Standorte nicht. Nach Anfragen zu bepreisen ließe einen Aufrufer innerhalb seines Kontingents bleiben und dabei völlig legitim mehr kosten, als er zahlt — was ein Aufruf kostet, hängt deshalb davon ab, wie viel Archiv er bewegt.

Was zu tun ist, wenn Sie an eine stoßen

Ihr Kontingentzeitraum läuft von Ihrem Abodatum bis zum gleichen Tag des Folgemonats — dem Zeitraum, den Stripe abrechnet — und der Zähler beginnt jedes Mal wieder von vorn. X-Quota-Resets-At trägt dieses Datum in jeder Antwort: lesen Sie es, statt den Monatsersten anzunehmen. Konten ohne Abo folgen dem Kalendermonat.

Fehler#

Jeder Fehler hat dieselbe Form, auf beiden Hosts:

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

Das ist die vollständige Liste, und sie wird bei jedem Build gegen den Quelltext geprüft: ein hier veröffentlichter Code, den kein Handler auslöst, lässt die Testsuite scheitern, und ein Handler, der einen auslöst, den diese Tabelle nicht führt, ebenso. Wenn Ihnen ein Code begegnet, der oben fehlt, ist das ein Fehler dieser Seite und kein Wert, den Sie gesondert behandeln sollten.

Eine Wiederholungsstrategie, die funktioniert

RETRY = {"rate_limited", "data_unavailable"}

def should_retry(status, code, attempt):
    if code == "quota_exceeded":
        return False              # bis zur Zurücksetzung ändert sich nichts
    if code == "geocode_quota_exceeded":
        return False              # und nicht anhalten: Credits gehen weiter
    if code in RETRY:
        return attempt < 5
    return status >= 500

Genauigkeit — was zu erwarten ist#

Wir setzen die Erwartungen lieber richtig, als dass Sie die Grenzen im Produktivbetrieb entdecken.

Wo die Vorhersage stark ist

Temperatur, Druck, synoptischer Wind, Luftfeuchte, Sonnenschein. Der typische Fehler der 2-m-Temperatur nach 24 Stunden liegt bei etwa 1 bis 1,5 °C. Das EZMW ist das weltweit beste globale deterministische Modell, und genau das bekommen Sie.

Wo sie schwächer ist

Konvektive Gewitter — eine 28-km-Zelle kann kein Gewitter auflösen, und selbst 3 km deuten es nur an. Genaue Lage und Zeit von Schauern. Küsten- und Bergmikroklima unterhalb der Modellauflösung. Seewind und Kaltluftseen in Tälern, die die Geländekorrektur nicht abbildet.

Geografische Ehrlichkeit

In Frankreich, Deutschland, den USA und Kanada liefern wir nationale Modelle mit 1,3 bis 3 km aus, und ein kleines Dorf bekommt tatsächlich seine eigene Gitterzelle. Sonst in Europa bekommen Sie 6,5 km. In Afrika, im Nahen Osten und im größten Teil Asiens ist das beste verfügbare öffentliche Modell 13 bis 28 km grob: Sie bekommen dort also das Wetter der Gegend statt das der Straße. Die Geländekorrektur verkleinert diese Lücke, schließt sie aber nicht.

Gradtage

Eine Gitter-Reanalyse deckt alles ab, auch Orte ohne Wetterstation im Umkreis von 60 km — das ist ihr Vorteil gegenüber stationsbasierten Anbietern. Ihre Schwäche sind Innenstädte, die die Reanalyse zu niedrig liest; die Stadt-Endpunkte wenden eine kalibrierte Korrektur an, die Koordinaten-Endpunkte nicht.

Zwei Felder sind Schätzungen, und wir sagen das lieber

uv_index wird aus Sonnenhöhe und Breitbandstrahlung abgeleitet, nicht aus einer Ozonsäule — genau auf etwa ±1 Einheit. precipitation_probability_proxy ist eine Schätzung, keine Wahrscheinlichkeit; die echte steht unter /v1/probability. Beide sind in der Feldreferenz vollständig erklärt.

Tarife#

Geocoding steht außerhalb dieser Tabelle: es kostet in keinem Tarif Credits und trägt seine eigene Obergrenze von fünf Anfragen je Credit. Siehe Ratenlimits und Kontingent.

Bei jährlicher Zahlung sind zwei Monate frei. Der aktuelle Katalog steht auf developers.climatememory.com/pricing — diese Seite liest das Abrechnungssystem direkt, wenn beide je voneinander abweichen, gilt sie.

Es gibt in keinem Tarif einen Endpunkt für Massenexporte. Den CSV-Export gibt es für die Gradtag- und Klimaarchive, er ist auf dieselbe Spanne wie der entsprechende JSON-Aufruf begrenzt und gibt nur aggregierte Zeilen zurück — niemals die Stundenreihe.

Namensnennung und Lizenzen#

Beide oben genannten Endpunkte brauchen keinen Schlüssel, Sie können den Hinweis also aus der API rendern, statt eine Zeichenkette fest einzuschreiben, die veraltet, sobald sich eine Quelle ändert. Die Namensnennung des konkreten Laufs, der geantwortet hat, reist außerdem in jeder Datenantwort mit, in source.attribution und im Header X-Data-Attribution.

Sie dürfen angeben, dass Sie diese Daten verwenden. Sie dürfen nicht den Eindruck erwecken, eine dieser Organisationen habe Ihr Produkt erstellt, geprüft oder empfohlen.

Haftungsausschluss

Vorhersagen werden ohne Gewähr bereitgestellt. Weder die Europäische Kommission noch EZMW, DWD, NOAA oder Météo-France haften für eine Verwendung dieser Informationen. Nutzen Sie sie nicht als alleinige Grundlage für Entscheidungen, bei denen Leben, Sicherheit oder Sachwerte auf dem Spiel stehen.

Eine Einschränkung steht uns nicht zu aufzuheben: die Copernicus-Lizenz behält Hochwasserwarnungen den nationalen und regionalen Behörden vor. Siehe Flüsse.