Démarrer

De quoi il s'agit#

Climate Memory sert trois produits depuis deux hôtes, sur une seule clé d'API.

Deux hôtes plutôt qu'un parce que les degrés-jours lisent une autre archive, au profil de coût différent, et les séparer permet à l'une d'être lente sans ralentir l'autre. Vous n'avez pas à vous en soucier au-delà de copier la bonne URL de base.

Votre premier appel#

Trois étapes. L'ensemble prend environ une minute.

1. Obtenir une clé

Créez un compte sur developers.climatememory.com/signin. La formule gratuite ne demande pas de carte, vous donne 10 000 crédits par mois, et votre clé s'affiche immédiatement. Gardez-la dans une variable d'environnement — les exemples ci-dessous lisent tous $API_KEY.

export API_KEY="wd_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

2. Faire l'appel

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. Lire la réponse

Toute série revient orientée colonnes — des tableaux parallèles partageant un unique index time, et non une liste d'objets. Voir conventions de réponse pour le pourquoi, et pour savoir comment la lire.

Authentification#

Envoyez votre clé dans l'en-tête X-API-Key à chaque requête. Il n'y a aucun flux OAuth, aucun jeton de porteur à rafraîchir et aucune signature à calculer.

X-API-Key: wd_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Les clés sont stockées hachées. Si vous en perdez une, elle est renouvelée, pas récupérée — nous ne pouvons pas vous la remontrer, parce que nous ne l'avons pas. Le renouvellement se fait dans la console et délivre une nouvelle clé immédiatement.

Scopes

Une clé porte des scopes, et c'est la formule qui décide lesquels. Appeler un endpoint hors de vos scopes renvoie 403 scope_denied — ce qui est un problème de formule, pas de clé, et le message le dit.

Les endpoints de géocodage n'en exigent aucun. Toute clé valide résout un nom de lieu, sur n'importe quelle formule, parce que chaque produit ici a besoin d'une coordonnée avant de pouvoir répondre quoi que ce soit. Voir géocodage.

Géocodage#

Paramètres

Le catalogue est la classe P de GeoNames en entier — chaque lieu habité de la planète, jusqu'aux hameaux de quelques dizaines d'habitants, et non un extrait filtré par population. Un village de 528 habitants s'y trouve.

La correspondance n'est jamais restreinte par la langue

La requête est confrontée au nom local, à sa translittération ASCII et à chaque alias localisé, quoi que dise lang. Cela compte plus qu'il n'y paraît : 98 % des lieux n'ont aucun nom localisé — le français couvre 1,84 % du catalogue — si bien qu'une recherche filtrée par langue trouve les capitales et rien d'autre. lang choisit quel nom revient et influence le classement ; il ne décide jamais de ce qui est éligible.

GET /v1/geocode?q=ramillies&lang=fr
GET /v1/geocode?q=ramillies&lang=fr&near=50.63,3.06   # depuis Lille
GET /v1/geocode?q=bruxelles&lang=fr                     # exonyme, via l'index d'alias
GET /v1/geocode?q=zuesch&lang=de                        # tréma écrit en toutes lettres

Comment les résultats sont classés

Chaque résultat porte un score et, quand near a été fourni, une distance_km. Le classement combine quatre signaux : la qualité de la correspondance du nom, l'importance du lieu, sa proximité avec near, et le fait que le nom trouvé était ou non dans la langue demandée.

Pourquoi near existe. Il y a deux Ramillies — 5 749 habitants dans le Brabant wallon, 528 dans les Hauts-de-France, à 126 km l'une de l'autre. Aucune n'est la bonne réponse dans l'absolu. Sans near, c'est la plus grande qui est renvoyée ; depuis Lille, c'est la française.

L'importance n'est pas que la population. 90,7 % du catalogue n'a aucune population renseignée — GeoNames n'en publie strictement aucune pour certains pays — si bien que le type de lieu (capitale nationale, chef-lieu d'une division administrative, lieu ordinaire, quartier) porte le classement partout où la population est absente.

Les trémas sont écrits en toutes lettres, pas supprimés. Un clavier allemand ou danois sans diacritiques écrit Zuesch pour Züsch et Koeln pour Köln. GeoNames ne porte pas cette graphie — sa forme ASCII est Zusch, tréma retiré plutôt que développé — elle est donc générée ici. Les deux graphies atteignent le lieu, et le résultat affiche le vrai nom dans les deux cas.

Recherche de ville#

/v1/cities/search est antérieur à /v1/geocode et conserve son contrat pour les appelants déjà bâtis dessus : il ne compare que le nom ASCII et trie par population.

/v1/cities/nearest est le sens inverse, et c'est ce qui transforme un point GPS en slug de ville que vous pourrez ensuite passer aux endpoints par ville. Il prend lat, lon et un max_km facultatif.

Les deux comptent sur le même plafond de géocodage que /v1/geocode, et aucun ne coûte de crédits.

Conventions de réponse#

Six règles valent pour tous les endpoints. Apprenez-les une fois et le reste de cette documentation n'est plus que des noms de champs.

1. Les séries sont des colonnes, pas des lignes

Toute série temporelle est un ensemble de tableaux parallèles partageant un unique index time, plutôt qu'un tableau d'objets :

"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 de chaque tableau décrit le même instant. C'est trois à cinq fois plus léger sur le réseau que la forme en lignes, cela se décode directement dans un dataframe ou une bibliothèque de tracé sans transformation, et c'est ce que les clients de forme Open-Meteo attendent déjà. Pour la parcourir en lignes :

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

2. Les dates sont en ISO 8601 avec décalage explicite

Toujours. 2026-08-01T00:00:00+00:00, jamais une chaîne locale nue et jamais un entier Unix. Là où vous passez un timezone, le décalage de la réponse est celui de ce fuseau — la chaîne seule est donc sans ambiguïté, et vous n'avez jamais à savoir ce que nous avons supposé.

3. Les unités sont SI, fixes, et jamais négociées

°C, mm, m/s, hPa, W/m², mètres. Il n'y a pas de paramètre units=imperial, et c'est volontaire : un commutateur d'unités est un champ dont le sens dépend d'un autre champ, et c'est ainsi qu'un appelant finit par tracer des Fahrenheit sur un axe Celsius après un changement de configuration que personne n'a relu. Convertissez à votre périphérie, là où se trouve le lecteur.

Les endpoints qui portent des unités inhabituelles embarquent dans la réponse un bloc units qui les nomme explicitement, plutôt que d'attendre que vous vous en souveniez.

4. null signifie « inconnu », jamais « zéro »

Une heure manquante vaut null dans le tableau, en conservant sa place pour que les indices restent alignés. Elle n'est jamais silencieusement remplie par 0 — pour les précipitations, les deux sont des affirmations opposées, et l'une des deux est un mensonge sur une sécheresse.

5. Chaque réponse dit d'où elle vient

Un bloc source (météo) ou un bloc quality (archives) voyage avec la donnée : quel modèle ou quel run a répondu, quel âge il a, à quel point la période était complète. Vous n'avez jamais à déduire la fraîcheur depuis l'horloge.

6. Périmé vaut mieux qu'absent

Si notre run de modèle le plus récent est plus vieux que prévu, nous répondons quand même — avec "stale": true et data_age_hours dans le bloc source — plutôt que de renvoyer un 503. Une prévision vieille de huit heures est plus utile qu'une erreur. Vérifiez le drapeau si la fraîcheur est déterminante pour vous ; ignorez-le sinon.

Plafonds de débit, crédits et quota#

Trois plafonds indépendants s'appliquent, et ils échouent différemment à dessein. Chaque réponse réussie indique où vous en êtes :

Des crédits, pas des requêtes

Une prévision de ville en cache est une lecture de 3 ms. Dix ans de degrés-jours horaires sur cinq cents sites, non. Tarifer à la requête permettrait à un appelant de rester dans son quota tout en coûtant plus qu'il ne paie, en toute légitimité — ce que coûte un appel dépend donc de la quantité d'archive qu'il déplace.

Que faire quand vous atteignez chacun

Votre période de quota court de votre date d'abonnement au même jour du mois suivant — la période que Stripe facture — et le compteur repart entier à chaque fois. X-Quota-Resets-At porte cette date dans chaque réponse : lisez-la plutôt que de supposer le premier du mois. Les comptes sans abonnement suivent le mois calendaire.

Erreurs#

Toute erreur a la même forme, sur les deux hôtes :

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

C'est la liste entière, et elle est vérifiée contre le code source à chaque construction : un code publié ici qu'aucun handler ne lève fait échouer la suite de tests, et un handler qui en lève un que ce tableau ne porte pas également. Si vous rencontrez un code absent ci-dessus, c'est un défaut de cette page et non une valeur à traiter spécialement.

Une politique de réessai qui fonctionne

RETRY = {"rate_limited", "data_unavailable"}

def should_retry(status, code, attempt):
    if code == "quota_exceeded":
        return False              # rien ne change avant la remise à zéro
    if code == "geocode_quota_exceeded":
        return False              # et ne vous arrêtez pas : les crédits marchent
    if code in RETRY:
        return attempt < 5
    return status >= 500

Précision — à quoi s'attendre#

Nous préférons poser les attentes correctement plutôt que vous laisser découvrir les limites en production.

Là où la prévision est solide

Température, pression, vent synoptique, humidité, ensoleillement. L'erreur typique sur la température à 2 m à 24 heures est d'environ 1 à 1,5 °C. L'ECMWF est le meilleur modèle déterministe mondial au monde, et c'est celui que vous obtenez.

Là où elle est plus faible

Les orages convectifs — une maille de 28 km ne peut pas résoudre un orage, et même 3 km ne fait que le suggérer. Le placement et le calage exacts des averses. Les microclimats côtiers et de montagne sous la résolution du modèle. Les brises de mer et les lacs d'air froid de vallée, que la correction de relief ne modélise pas.

Honnêteté géographique

En France, en Allemagne, aux États-Unis et au Canada, nous servons des modèles nationaux à 1,3–3 km, et un petit village obtient réellement sa propre maille. Ailleurs en Europe, vous obtenez 6,5 km. À travers l'Afrique, le Moyen-Orient et la majeure partie de l'Asie, le meilleur modèle public disponible est à 13–28 km : vous obtenez donc la météo de la zone plutôt que celle de la rue. La correction de relief réduit cet écart mais ne le comble pas.

Degrés-jours

Une réanalyse sur grille couvre partout, y compris les lieux sans station météo à moins de 60 km — c'est son avantage sur les fournisseurs adossés à des stations. Sa faiblesse, ce sont les centres-villes, que la réanalyse sous-estime ; les endpoints par ville appliquent une correction calibrée, les endpoints par coordonnée non.

Deux champs sont des estimations, et nous préférons le dire

uv_index est dérivé de l'élévation solaire et du rayonnement large bande, pas d'une colonne d'ozone — précis à environ ±1 unité. precipitation_probability_proxy est une estimation, pas une probabilité ; la véritable se trouve sur /v1/probability. Les deux sont expliqués en détail dans la référence des champs.

Formules#

Le géocodage est hors de ce tableau : il ne coûte aucun crédit sur aucune formule, et porte son propre plafond de cinq requêtes par crédit. Voir plafonds de débit et quota.

La facturation annuelle offre deux mois. Le catalogue à jour est sur developers.climatememory.com/pricing — cette page lit directement le système de facturation, donc si les deux venaient à diverger, c'est elle qui fait foi.

Il n'y a d'endpoint d'export en masse sur aucune formule. L'export CSV existe sur les archives de degrés-jours et de climat, est borné à la même amplitude que l'appel JSON équivalent, et ne renvoie que des lignes agrégées — jamais la série horaire.

Attribution et licences#

Les deux endpoints ci-dessus ne demandent aucune clé : vous pouvez donc rendre la mention depuis l'API plutôt que d'inscrire en dur une chaîne qui se périmera au changement d'une source. L'attribution du run précis qui a répondu voyage également sur chaque réponse de données, dans source.attribution et dans l'en-tête X-Data-Attribution.

Vous pouvez déclarer que vous utilisez ces données. Vous ne pouvez pas laisser entendre que l'une de ces organisations a produit, approuvé ou cautionne votre produit.

Clause de non-responsabilité

Les prévisions sont fournies sans garantie. Ni la Commission européenne, ni l'ECMWF, ni la DWD, ni la NOAA, ni Météo-France ne sont responsables de l'usage qui est fait de ces informations. Ne les utilisez pas comme seule base de décisions mettant en jeu la vie, la sécurité ou les biens.

Une restriction n'est pas la nôtre à lever : la licence Copernicus réserve les alertes de crue aux autorités nationales et régionales. Voir rivières.