Începeți aici

Ce este#

Climate Memory servește trei produse de pe două gazde, cu o singură cheie de API.

Două gazde în loc de una pentru că gradele-zile citesc o altă arhivă, cu alt profil de cost, iar separarea lor permite ca una să fie lentă fără să o încetinească pe cealaltă. Dincolo de a copia URL-ul de bază potrivit, nu trebuie să vă intereseze.

Primul dumneavoastră apel#

Trei pași. Totul durează cam un minut.

1. Obțineți o cheie

Creați-vă cont la developers.climatememory.com/signin. Planul gratuit nu cere card, vă dă 10 000 de credite pe lună, iar cheia apare imediat pe ecran. Păstrați-o într-o variabilă de mediu — toate exemplele de mai jos citesc $API_KEY.

export API_KEY="wd_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

2. Faceți apelul

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. Citiți răspunsul

Toate seriile se întorc orientate pe coloane — vectori paraleli care împart un singur index time, nu o listă de obiecte. Vedeți convențiile de răspuns pentru de ce și pentru cum se citesc.

Autentificare#

Trimiteți cheia în antetul X-API-Key la fiecare cerere. Nu există flux OAuth, niciun bearer token de reînnoit și nicio semnătură de calculat.

X-API-Key: wd_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Cheile sunt stocate ca hash. Dacă pierdeți una, ea este rotită, nu recuperată — nu v-o putem arăta din nou, pentru că nu o avem. Rotirea se face din consolă și emite imediat o cheie nouă.

Scope-uri

O cheie poartă scope-uri, iar planul decide care. Apelarea unui endpoint din afara scope-urilor dumneavoastră întoarce 403 scope_denied — asta e o problemă de plan, nu de cheie, iar mesajul o spune.

Endpointurile de geocodare nu cer niciunul dintre ele. Orice cheie validă rezolvă un nume de loc, pe orice plan, pentru că fiecare produs de aici are nevoie de o coordonată înainte să poată răspunde ceva. Vedeți geocodare.

Geocodare#

Parametri

Catalogul este clasa de entități P din GeoNames în întregime — fiecare localitate de pe Pământ, până la cătune de câteva zeci de oameni, nu un extras filtrat după populație. Un sat de 528 de locuitori este acolo.

Potrivirea nu este niciodată restrânsă de limbă

Interogarea este testată pe numele local, pe transliterarea lui ASCII și pe toate aliasurile localizate, orice ar spune lang. Asta contează mai mult decât pare: 98 % dintre locuri nu au niciun nume localizat — franceza acoperă 1,84 % din catalog — deci o căutare filtrată după limbă găsește capitale și nimic altceva. lang alege ce nume se întoarce și influențează ordonarea; nu decide niciodată ce este eligibil.

GET /v1/geocode?q=ramillies&lang=fr
GET /v1/geocode?q=ramillies&lang=fr&near=50.63,3.06   # din Lille
GET /v1/geocode?q=bruxelles&lang=fr                     # exonim, prin indexul de aliasuri
GET /v1/geocode?q=zuesch&lang=de                        # umlaut scris desfășurat

Cum sunt ordonate rezultatele

Fiecare rezultat poartă un score și, când s-a dat near, un distance_km. Ordonarea combină patru semnale: cât de bine s-a potrivit numele, cât de important e locul, cât de aproape e de near și dacă numele potrivit era în limba cerută.

De ce există near. Sunt două localități Ramillies — 5 749 de locuitori în Brabantul Valon, 528 în Hauts-de-France, la 126 km una de alta. Niciuna nu e răspunsul corect în abstract. Fără near se întoarce cea mai mare; din Lille, se întoarce cea franceză.

Importanța nu înseamnă doar populație. 90,7 % din catalog nu are populația înregistrată — GeoNames nu publică niciuna pentru unele țări — așa că, acolo unde populația lipsește, ordonarea e purtată de tipul locului (capitală națională, reședință de unitate administrativă, localitate obișnuită, cartier).

Umlauturile se scriu desfășurat, nu se aruncă. O tastatură germană sau daneză fără diacritice scrie Zuesch pentru Züsch și Koeln pentru Köln. GeoNames nu are grafia asta — forma lui ASCII este Zusch, cu umlautul eliminat în loc de desfășurat — așa că este generată aici. Ambele grafii ajung la loc, iar rezultatul arată numele adevărat în ambele cazuri.

Căutare de orașe#

/v1/cities/search este anterior lui /v1/geocode și își păstrează contractul pentru cei care au construit deja pe el: potrivește doar numele ASCII și ordonează după populație.

/v1/cities/nearest este sensul invers și este cel care transformă o poziție GPS într-un slug de oraș pe care îl puteți da apoi endpointurilor pe oraș. Primește lat, lon și un max_km opțional.

Amândouă se scad din același plafon de geocodare ca /v1/geocode și niciunul nu costă credite.

Convenții de răspuns#

Șase reguli sunt valabile pentru toate endpointurile. Învățați-le o dată și restul acestei documentații înseamnă doar nume de câmpuri.

1. Seriile sunt coloane, nu rânduri

Fiecare serie de timp este un set de vectori paraleli care împart un singur index time, în loc de un vector de obiecte:

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

Indexul i al fiecărui vector descrie același moment. Asta e de trei până la cinci ori mai mic pe rețea decât forma pe rânduri, se decodează direct într-un dataframe sau într-o bibliotecă de grafice fără transformare și este ceea ce clienții scriși pentru Open-Meteo se așteaptă deja să primească. Ca să-l parcurgeți pe rânduri:

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

2. Timpii sunt ISO 8601 cu decalaj explicit

Întotdeauna. 2026-08-01T00:00:00+00:00, niciodată un șir local simplu și niciodată un întreg Unix. Când transmiteți un timezone, decalajul din răspuns este al acelei zone — deci șirul singur este lipsit de ambiguitate și nu trebuie să știți niciodată ce am presupus noi.

3. Unitățile sunt SI, fixe și nenegociabile

°C, mm, m/s, hPa, W/m², metri. Nu există un parametru units=imperial, și asta e intenționat: un comutator de unități e un câmp al cărui înțeles depinde de alt câmp, și așa ajunge un apelant să deseneze Fahrenheit pe o axă în Celsius după o schimbare de configurație pe care n-a verificat-o nimeni. Convertiți la marginea dumneavoastră, acolo unde e cititorul.

Endpointurile cu unități neobișnuite trimit în răspuns un bloc units care le numește explicit, în loc să se aștepte să vă amintiți.

4. null înseamnă „nu se știe”, niciodată „zero”

O oră lipsă este null în vector, păstrându-și poziția pentru ca indicii să rămână aliniați. Nu este completată tăcut cu 0 — pentru precipitații cele două sunt afirmații opuse, iar una dintre ele e o minciună despre o secetă.

5. Fiecare răspuns spune de unde vine

Un bloc source (meteo) sau un bloc quality (arhive) călătorește cu datele: ce model sau ce rulare a răspuns, ce vechime are, cât de completă era perioada. Nu trebuie niciodată să deduceți prospețimea uitându-vă la ceas.

6. Mai bine învechit decât absent

Dacă cea mai nouă rulare a modelului nostru e mai veche decât ne așteptam, tot răspundem — cu "stale": true și data_age_hours în blocul source — în loc să întoarcem 503. O prognoză veche de opt ore e mai utilă decât o eroare. Verificați indicatorul dacă prospețimea e esențială pentru dumneavoastră; ignorați-l dacă nu e.

Limite de ritm, credite și cotă#

Se aplică trei limite independente, iar ele cedează diferit dinadins. Fiecare răspuns reușit spune unde vă aflați:

Credite, nu cereri

O prognoză de oraș din cache este o citire de 3 ms. Zece ani de grade-zile orare pentru cinci sute de situri nu este. Tarifarea pe cereri ar lăsa un apelant să stea în cota lui și să coste mai mult decât plătește, absolut legitim — deci cât costă un apel depinde de cât de multă arhivă mișcă.

Ce faceți când dați de fiecare

Perioada de cotă merge de la data abonării până în aceeași zi a lunii următoare — perioada pe care o facturează Stripe — iar contorul o ia de la capăt, întreg, de fiecare dată. X-Quota-Resets-At poartă data aceea în fiecare răspuns, deci citiți-o în loc să presupuneți întâi de lună. Conturile fără abonament urmează luna calendaristică.

Erori#

Toate erorile au aceeași formă, pe ambele gazde:

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

Aceasta e toată lista, și e verificată față de sursă la fiecare construire: un cod publicat aici pe care niciun handler nu îl ridică pică suita de teste, la fel și un handler care ridică unul pe care tabelul acesta nu îl conține. Dacă dați de un cod care nu e mai sus, e o eroare a acestei pagini și nu o valoare pe care s-o tratați special.

O politică de reîncercare care funcționează

RETRY = {"rate_limited", "data_unavailable"}

def should_retry(status, code, attempt):
    if code == "quota_exceeded":
        return False              # nimic nu se schimbă până la resetare
    if code == "geocode_quota_exceeded":
        return False              # și nu vă opriți: creditele merg în continuare
    if code in RETRY:
        return attempt < 5
    return status >= 500

Acuratețe — la ce să vă așteptați#

Preferăm să setăm corect așteptările decât să descoperiți limitele în producție.

Unde prognoza e puternică

Temperatură, presiune, vânt sinoptic, umiditate, durata de strălucire a soarelui. Eroarea tipică a temperaturii la 2 m la 24 de ore e în jur de 1–1,5 °C. ECMWF e cel mai bun model global determinist din lume și el este cel pe care îl primiți.

Unde e mai slabă

Furtunile convective — o celulă de 28 km nu poate rezolva o furtună, iar nici măcar 3 km nu fac mai mult decât s-o sugereze. Locul și momentul exact al averselor. Microclimatul de coastă și de munte sub rezoluția modelului. Brizele marine și lacurile de aer rece din văi, pe care corecția de relief nu le modelează.

Onestitate geografică

În Franța, Germania, SUA și Canada servim modele naționale de 1,3–3 km, iar un sat mic chiar primește propria celulă de grilă. În restul Europei primiți 6,5 km. În Africa, Orientul Mijlociu și cea mai mare parte a Asiei, cel mai bun model public disponibil e de 13–28 km, deci primiți vremea zonei, nu a străzii. Corecția de relief îngustează diferența, dar nu o închide.

Grade-zile

Reanaliza pe grilă acoperă peste tot, inclusiv locuri fără nicio stație meteo pe o rază de 60 km — acesta e avantajul ei față de furnizorii bazați pe stații. Slăbiciunea ei sunt centrele orașelor, pe care reanaliza le subestimează; endpointurile pe oraș aplică o corecție calibrată, cele pe coordonate nu.

Două câmpuri sunt estimări și preferăm s-o spunem

uv_index e derivat din înălțimea soarelui și din radiația de bandă largă, nu dintr-o coloană de ozon — cu o acuratețe de circa ±1 unitate. precipitation_probability_proxy e o estimare, nu o probabilitate; cea adevărată e la /v1/probability. Amândouă sunt explicate pe larg în referința câmpurilor.

Planuri#

Geocodarea stă în afara acestui tabel: nu costă credite pe niciun plan și are plafonul ei de cinci cereri per credit. Vedeți limite de ritm și cotă.

Facturarea anuală înseamnă două luni gratuite. Catalogul viu este la developers.climatememory.com/pricing — pagina aceea citește direct sistemul de facturare, deci dacă vreodată cele două nu se potrivesc, ea are dreptate.

Nu există endpoint de export în masă pe niciun plan. Exportul CSV există pe arhivele de grade-zile și de climă, este limitat la același interval ca apelul JSON echivalent și întoarce doar rânduri agregate — niciodată seria orară.

Atribuire și licențiere#

Ambele endpointuri de mai sus nu cer cheie, deci puteți afișa mențiunea direct din API în loc să fixați în cod un șir care se învechește când se schimbă o sursă. Atribuirea pentru rularea concretă care a răspuns călătorește și ea în fiecare răspuns cu date, în source.attribution și în antetul X-Data-Attribution.

Puteți declara că folosiți aceste date. Nu puteți sugera că vreuna dintre aceste organizații v-a produs, aprobat sau susținut produsul.

Declinarea răspunderii

Prognozele sunt furnizate fără garanție. Nici Comisia Europeană, nici ECMWF, DWD, NOAA sau Météo-France nu răspund pentru vreo utilizare a acestor informații. Nu le folosiți ca unic temei pentru decizii în care viața, siguranța sau bunurile sunt în joc.

O restricție nu e a noastră ca s-o ridicăm: licența Copernicus rezervă avertizările de inundații autorităților naționale și regionale. Vedeți râuri.