Iniziare

Di cosa si tratta#

Climate Memory serve tre prodotti da due host, con un'unica chiave API.

Due host anziché uno perché i gradi giorno leggono un altro archivio con un profilo di costo diverso, e separarli permette a uno di essere lento senza rallentare l'altro. Non deve preoccuparsene oltre il copiare l'URL di base giusto.

La sua prima chiamata#

Tre passi. Il tutto richiede circa un minuto.

1. Ottenere una chiave

Crei un account su developers.climatememory.com/signin. Il piano gratuito non richiede carta, le dà 10 000 crediti al mese, e la sua chiave compare subito a schermo. La conservi in una variabile d'ambiente — tutti gli esempi qui sotto leggono $API_KEY.

export API_KEY="wd_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

2. Effettuare la chiamata

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. Leggere la risposta

Ogni serie torna orientata a colonne — array paralleli che condividono un unico indice time, non un elenco di oggetti. Si vedano le convenzioni di risposta per il perché, e per come leggerla.

Autenticazione#

Invii la sua chiave nell'intestazione X-API-Key a ogni richiesta. Non c'è alcun flusso OAuth, nessun token bearer da rinnovare e nessuna firma da calcolare.

X-API-Key: wd_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Le chiavi sono memorizzate sotto forma di hash. Se ne perde una, viene rinnovata, non recuperata — non possiamo mostrargliela di nuovo, perché non la abbiamo. Il rinnovo si fa nella console ed emette immediatamente una chiave nuova.

Scope

Una chiave porta degli scope, ed è il piano a decidere quali. Chiamare un endpoint fuori dai suoi scope restituisce 403 scope_denied — che è un problema di piano, non di chiave, e il messaggio lo dice.

Gli endpoint di geocodifica non ne richiedono nessuno. Qualsiasi chiave valida risolve un nome di luogo, su qualsiasi piano, perché ogni prodotto qui ha bisogno di una coordinata prima di poter rispondere a qualcosa. Si veda geocodifica.

Geocodifica#

Parametri

Il catalogo è la classe di entità P di GeoNames per intero — ogni luogo abitato della Terra, fino a frazioni di qualche decina di persone, e non un estratto filtrato per popolazione. Un paese di 528 abitanti c'è.

La corrispondenza non è mai limitata dalla lingua

La query viene confrontata con il nome locale, la sua traslitterazione ASCII e ogni alias localizzato, qualunque cosa dica lang. Conta più di quanto sembri: il 98 % dei luoghi non ha alcun nome localizzato — il francese copre l'1,84 % del catalogo — quindi una ricerca filtrata per lingua troverebbe le capitali e nient'altro. lang sceglie quale nome torna e influenza l'ordinamento; non decide mai cosa è ammissibile.

GET /v1/geocode?q=ramillies&lang=fr
GET /v1/geocode?q=ramillies&lang=fr&near=50.63,3.06   # da Lille
GET /v1/geocode?q=bruxelles&lang=fr                     # esonimo, tramite l'indice degli alias
GET /v1/geocode?q=zuesch&lang=de                        # dieresi scritta per esteso

Come vengono ordinati i risultati

Ogni risultato porta uno score e, quando è stato fornito near, una distance_km. L'ordinamento combina quattro segnali: quanto bene ha corrisposto il nome, quanto è rilevante il luogo, quanto è vicino a near, e se il nome trovato era nella lingua richiesta.

Perché esiste near. Esistono due Ramillies — 5 749 abitanti nel Brabante Vallone, 528 negli Alti di Francia, a 126 km di distanza. Nessuna delle due è la risposta giusta in astratto. Senza near viene restituita la più grande; da Lille, quella francese.

La rilevanza non è solo la popolazione. Il 90,7 % del catalogo non ha alcuna popolazione registrata — per alcuni paesi GeoNames non ne pubblica affatto — quindi il tipo di luogo (capitale nazionale, capoluogo di una divisione amministrativa, luogo ordinario, quartiere) sostiene l'ordinamento ovunque manchi la popolazione.

Le dieresi sono scritte per esteso, non eliminate. Una tastiera tedesca o danese senza segni diacritici scrive Zuesch per Züsch e Koeln per Köln. GeoNames non riporta quella grafia — la sua forma ASCII è Zusch, con la dieresi rimossa anziché sviluppata — quindi viene generata qui. Entrambe le grafie raggiungono il luogo, e il risultato mostra il nome vero in entrambi i casi.

Ricerca di città#

/v1/cities/search è anteriore a /v1/geocode e mantiene il suo contratto per i chiamanti già costruiti su di esso: confronta solo il nome ASCII e ordina per popolazione.

/v1/cities/nearest è il verso opposto, ed è ciò che trasforma una posizione GPS in uno slug di città che può poi passare agli endpoint per città. Accetta lat, lon e un max_km facoltativo.

Entrambi contano sullo stesso tetto di geocodifica di /v1/geocode, e nessuno dei due costa crediti.

Convenzioni di risposta#

Sei regole valgono per tutti gli endpoint. Le impari una volta e il resto di questa documentazione sono solo nomi di campi.

1. Le serie sono colonne, non righe

Ogni serie temporale è un insieme di array paralleli che condividono un unico indice time, anziché un array di oggetti:

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

L'indice i di ogni array descrive lo stesso istante. Sulla rete è da tre a cinque volte più leggero della forma a righe, si decodifica direttamente in un dataframe o in una libreria grafica senza trasformazioni, ed è ciò che i client di forma Open-Meteo già si aspettano. Per percorrerlo per righe:

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

2. Gli orari sono ISO 8601 con scarto esplicito

Sempre. 2026-08-01T00:00:00+00:00, mai una stringa locale nuda né un intero Unix. Là dove passa una timezone, lo scarto nella risposta è quello di quel fuso — la stringa da sola è quindi inequivocabile, e non deve mai sapere cosa abbiamo supposto noi.

3. Le unità sono SI, fisse e mai negoziate

°C, mm, m/s, hPa, W/m², metri. Non esiste alcun parametro units=imperial, di proposito: un interruttore di unità è un campo il cui significato dipende da un altro campo, ed è così che un chiamante finisce per rappresentare Fahrenheit su un asse Celsius dopo un cambio di configurazione che nessuno ha riletto. Converta al suo bordo, dove sta il lettore.

Gli endpoint che portano unità insolite includono nella risposta un blocco units che le nomina esplicitamente, anziché aspettarsi che lei se ne ricordi.

4. null significa «ignoto», mai «zero»

Un'ora mancante è null nell'array, e conserva la sua posizione perché gli indici restino allineati. Non viene mai riempita in silenzio con 0 — per le precipitazioni le due sono affermazioni opposte, e una delle due è una menzogna su una siccità.

5. Ogni risposta dice da dove viene

Un blocco source (meteo) o un blocco quality (archivi) viaggia con i dati: quale modello o quale corsa ha risposto, quanto è vecchia, quanto era completo il periodo. Non deve mai dedurre la freschezza dall'orologio.

6. Obsoleto batte assente

Se la nostra corsa di modello più recente è più vecchia del previsto, rispondiamo comunque — con "stale": true e data_age_hours nel blocco source — anziché restituire un 503. Una previsione vecchia di otto ore è più utile di un errore. Controlli il flag se la freschezza è determinante per lei; lo ignori altrimenti.

Limiti di ritmo, crediti e quota#

Si applicano tre limiti indipendenti, e falliscono in modo diverso di proposito. Ogni risposta riuscita riporta a che punto è:

Crediti, non richieste

Una previsione di città in cache è una lettura da 3 ms. Dieci anni di gradi giorno orari su cinquecento siti no. Tariffare a richieste permetterebbe a un chiamante di restare dentro la sua quota costando più di quanto paga, in modo del tutto legittimo — quindi quanto costa una chiamata dipende da quanto archivio muove.

Cosa fare quando ne raggiunge uno

Il suo periodo di quota va dalla data dell'abbonamento allo stesso giorno del mese successivo — il periodo che Stripe fattura — e il contatore riparte intero ogni volta. X-Quota-Resets-At porta quella data in ogni risposta: la legga anziché supporre il primo del mese. Gli account senza abbonamento seguono il mese solare.

Errori#

Ogni errore ha la stessa forma, su entrambi gli host:

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

Questo è l'elenco completo, ed è verificato contro il codice sorgente a ogni compilazione: un codice pubblicato qui che nessun handler solleva fa fallire la suite di test, e lo stesso vale per un handler che ne sollevi uno che questa tabella non riporta. Se incontra un codice non presente qui sopra, è un difetto di questa pagina e non un valore da trattare in modo speciale.

Una politica di ritentativo che funziona

RETRY = {"rate_limited", "data_unavailable"}

def should_retry(status, code, attempt):
    if code == "quota_exceeded":
        return False              # nulla cambia fino all'azzeramento
    if code == "geocode_quota_exceeded":
        return False              # e non si fermi: i crediti funzionano
    if code in RETRY:
        return attempt < 5
    return status >= 500

Precisione — cosa aspettarsi#

Preferiamo fissare bene le aspettative piuttosto che lasciarle scoprire i limiti in produzione.

Dove la previsione è solida

Temperatura, pressione, vento sinottico, umidità, insolazione. L'errore tipico della temperatura a 2 m a 24 ore è di circa 1–1,5 °C. Il CEPMMT è il miglior modello deterministico globale al mondo, ed è quello che lei ottiene.

Dove è più debole

I temporali convettivi — una cella di 28 km non può risolvere un temporale, e anche 3 km lo accennano soltanto. La collocazione e il momento esatti dei rovesci. I microclimi costieri e di montagna sotto la risoluzione del modello. Le brezze di mare e i laghi d'aria fredda di valle, che la correzione per il rilievo non modella.

Onestà geografica

In Francia, Germania, Stati Uniti e Canada serviamo modelli nazionali a 1,3–3 km, e un piccolo paese ottiene davvero la sua cella. Altrove in Europa ottiene 6,5 km. In Africa, Medio Oriente e gran parte dell'Asia il miglior modello pubblico disponibile è a 13–28 km, quindi ottiene la meteorologia della zona anziché quella della via. La correzione per il rilievo riduce quel divario, ma non lo colma.

Gradi giorno

Una rianalisi su griglia copre ovunque, comprese le località senza stazione meteorologica entro 60 km — è questo il suo vantaggio sui fornitori basati su stazioni. La sua debolezza sono i centri urbani, che la rianalisi sottostima; gli endpoint per città applicano una correzione calibrata, quelli per coordinata no.

Due campi sono stime, e preferiamo dirlo

uv_index è derivato dall'elevazione solare e dalla radiazione a banda larga, non da una colonna di ozono — preciso a circa ±1 unità. precipitation_probability_proxy è una stima, non una probabilità; quella autentica sta su /v1/probability. Entrambi sono spiegati per esteso nel riferimento dei campi.

Piani#

La geocodifica sta fuori da questa tabella: non costa crediti su nessun piano, e porta un tetto proprio di cinque richieste per credito. Si vedano limiti di ritmo e quota.

La fatturazione annuale regala due mesi. Il catalogo aggiornato è su developers.climatememory.com/pricing — quella pagina legge direttamente il sistema di fatturazione, quindi se i due dovessero divergere fa fede lei.

Non esiste un endpoint di esportazione massiva su alcun piano. L'esportazione CSV esiste per gli archivi dei gradi giorno e del clima, è limitata allo stesso intervallo della chiamata JSON equivalente, e restituisce solo righe aggregate — mai la serie oraria.

Attribuzione e licenze#

Nessuno dei due endpoint qui sopra richiede una chiave, quindi può rendere l'avviso dall'API anziché scrivere a codice una stringa che diventerà obsoleta al cambiare di una fonte. L'attribuzione della corsa precisa che ha risposto viaggia inoltre su ogni risposta di dati, in source.attribution e nell'intestazione X-Data-Attribution.

Può dichiarare che utilizza questi dati. Non può lasciar intendere che una di queste organizzazioni abbia prodotto, approvato o avalli il suo prodotto.

Esclusione di responsabilità

Le previsioni sono fornite senza garanzia. Né la Commissione europea, né il CEPMMT, né il DWD, né la NOAA, né Météo-France sono responsabili dell'uso che viene fatto di queste informazioni. Non le utilizzi come unica base di decisioni in cui siano in gioco la vita, la sicurezza o i beni.

C'è una restrizione che non spetta a noi revocare: la licenza Copernicus riserva gli avvisi di piena alle autorità nazionali e regionali. Si vedano i fiumi.