Empezar

De qué se trata#

Climate Memory sirve tres productos desde dos hosts, con una única clave de API.

Dos hosts en lugar de uno porque los grados-día leen otro archivo con un perfil de coste distinto, y separarlos permite que uno sea lento sin ralentizar al otro. No tiene que preocuparse por ello más allá de copiar la URL base correcta.

Su primera llamada#

Tres pasos. Todo junto lleva alrededor de un minuto.

1. Obtener una clave

Cree una cuenta en developers.climatememory.com/signin. El plan gratuito no pide tarjeta, le da 10 000 créditos al mes, y su clave aparece en pantalla de inmediato. Guárdela en una variable de entorno — todos los ejemplos de abajo leen $API_KEY.

export API_KEY="wd_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

2. Hacer la llamada

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. Leer la respuesta

Toda serie vuelve orientada a columnas — arrays paralelos que comparten un único índice time, y no una lista de objetos. Véase convenciones de respuesta para saber por qué, y cómo leerla.

Autenticación#

Envíe su clave en la cabecera X-API-Key en cada solicitud. No hay flujo OAuth, ni token de portador que refrescar, ni firma que calcular.

X-API-Key: wd_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Las claves se almacenan cifradas mediante hash. Si pierde una, se renueva, no se recupera — no podemos volver a mostrársela, porque no la tenemos. La renovación se hace en la consola y emite una clave nueva de inmediato.

Scopes

Una clave lleva scopes, y el plan decide cuáles. Llamar a un endpoint fuera de sus scopes devuelve 403 scope_denied — que es un problema de plan, no de clave, y el mensaje así lo dice.

Los endpoints de geocodificado no exigen ninguno. Cualquier clave válida resuelve un nombre de lugar, en cualquier plan, porque todos los productos de aquí necesitan una coordenada antes de poder responder nada. Véase geocodificado.

Geocodificado#

Parámetros

El catálogo es la clase de entidad P de GeoNames al completo — cada lugar habitado del planeta, hasta aldeas de unas pocas docenas de personas, y no un extracto filtrado por población. Un pueblo de 528 habitantes está en él.

La coincidencia nunca está restringida por el idioma

La consulta se prueba contra el nombre local, su transliteración ASCII y cada alias localizado, diga lo que diga lang. Eso importa más de lo que parece: el 98 % de los lugares no tiene ningún nombre localizado — el francés cubre el 1,84 % del catálogo — de modo que una búsqueda filtrada por idioma encontraría capitales y nada más. lang elige qué nombre vuelve e influye en la ordenación; nunca decide qué es elegible.

GET /v1/geocode?q=ramillies&lang=fr
GET /v1/geocode?q=ramillies&lang=fr&near=50.63,3.06   # desde Lille
GET /v1/geocode?q=bruxelles&lang=fr                     # exónimo, vía el índice de alias
GET /v1/geocode?q=zuesch&lang=de                        # diéresis escrita en letras

Cómo se ordenan los resultados

Cada resultado lleva un score y, cuando se indicó near, una distance_km. La ordenación combina cuatro señales: lo bien que coincidió el nombre, lo destacado que es el lugar, lo cerca que está de near, y si el nombre coincidente estaba en el idioma solicitado.

Por qué existe near. Hay dos Ramillies — 5 749 habitantes en el Brabante Valón, 528 en Alta Francia, a 126 km de distancia. Ninguna es la respuesta correcta en abstracto. Sin near se devuelve la mayor; desde Lille, la francesa.

La relevancia no es solo población. El 90,7 % del catálogo no tiene población registrada — GeoNames no publica ninguna en absoluto para algunos países — de modo que el tipo de lugar (capital nacional, capital de una división administrativa, lugar corriente, barrio) sostiene la ordenación allí donde falta la población.

Las diéresis se escriben en letras, no se eliminan. Un teclado alemán o danés sin diacríticos escribe Zuesch por Züsch y Koeln por Köln. GeoNames no recoge esa grafía — su forma ASCII es Zusch, con la diéresis suprimida y no desarrollada — así que se genera aquí. Ambas grafías llegan al lugar, y el resultado muestra el nombre real en los dos casos.

Búsqueda de ciudad#

/v1/cities/search es anterior a /v1/geocode y mantiene su contrato para los clientes ya construidos sobre él: solo compara el nombre ASCII y ordena por población.

/v1/cities/nearest es el sentido inverso, y es lo que convierte una posición GPS en un slug de ciudad que después puede pasar a los endpoints por ciudad. Toma lat, lon y un max_km opcional.

Ambos cuentan contra el mismo tope de geocodificado que /v1/geocode, y ninguno cuesta créditos.

Convenciones de respuesta#

Seis reglas valen para todos los endpoints. Apréndalas una vez y el resto de esta documentación son solo nombres de campos.

1. Las series son columnas, no filas

Toda serie temporal es un conjunto de arrays paralelos que comparten un único índice time, en lugar de un array de objetos:

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

El índice i de cada array describe el mismo instante. Esto ocupa de tres a cinco veces menos en la red que la forma en filas, se descodifica directamente en un dataframe o en una biblioteca de gráficos sin transformación, y es lo que los clientes con forma de Open-Meteo ya esperan. Para recorrerlo por filas:

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

2. Las fechas son ISO 8601 con desplazamiento explícito

Siempre. 2026-08-01T00:00:00+00:00, nunca una cadena local pelada ni un entero Unix. Allí donde usted pase una timezone, el desplazamiento de la respuesta es el de ese huso — la cadena por sí sola es, pues, inequívoca, y nunca tiene que saber qué supusimos nosotros.

3. Las unidades son SI, fijas y no negociables

°C, mm, m/s, hPa, W/m², metros. No hay ningún parámetro units=imperial, y es a propósito: un conmutador de unidades es un campo cuyo significado depende de otro campo, y así es como un cliente acaba representando Fahrenheit sobre un eje Celsius tras un cambio de configuración que nadie revisó. Convierta en su borde, allí donde está el lector.

Los endpoints que llevan unidades poco habituales incluyen en la respuesta un bloque units que las nombra explícitamente, en lugar de esperar que usted las recuerde.

4. null significa «desconocido», nunca «cero»

Una hora que falta es null en el array, y conserva su posición para que los índices sigan alineados. Nunca se rellena en silencio con 0 — para la precipitación son dos afirmaciones opuestas, y una de las dos es una mentira sobre una sequía.

5. Cada respuesta dice de dónde viene

Un bloque source (meteorología) o un bloque quality (archivos) viaja con los datos: qué modelo o qué pasada respondió, qué antigüedad tiene, cómo de completo estaba el periodo. Nunca tiene que deducir la frescura del reloj.

6. Caducado gana a ausente

Si nuestra pasada de modelo más reciente es más antigua de lo esperado, respondemos igualmente — con "stale": true y data_age_hours en el bloque source — en lugar de devolver un 503. Una predicción de ocho horas de antigüedad es más útil que un error. Compruebe el indicador si la frescura es determinante para usted; ignórelo si no lo es.

Límites de ritmo, créditos y cuota#

Se aplican tres límites independientes, y fallan de forma distinta a propósito. Cada respuesta correcta informa de dónde está usted:

Créditos, no solicitudes

Una predicción de ciudad en caché es una lectura de 3 ms. Diez años de grados-día horarios sobre quinientos emplazamientos no lo es. Tarificar por solicitudes permitiría a un cliente permanecer dentro de su cuota y costar más de lo que paga, de forma enteramente legítima — así que lo que cuesta una llamada depende de cuánto archivo mueve.

Qué hacer cuando alcanza cada uno

Su periodo de cuota va desde la fecha de su suscripción hasta el mismo día del mes siguiente — el periodo que factura Stripe — y el contador vuelve a empezar entero cada vez. X-Quota-Resets-At lleva esa fecha en cada respuesta: léala en lugar de suponer el día uno del mes. Las cuentas sin suscripción siguen el mes natural.

Errores#

Todo error tiene la misma forma, en ambos hosts:

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

Esa es la lista completa, y se comprueba contra el código fuente en cada compilación: un código publicado aquí que ningún handler lanza hace fallar la batería de pruebas, y lo mismo un handler que lance uno que esta tabla no recoja. Si se topa con un código que no está arriba, es un defecto de esta página y no un valor que deba tratar de forma especial.

Una política de reintento que funciona

RETRY = {"rate_limited", "data_unavailable"}

def should_retry(status, code, attempt):
    if code == "quota_exceeded":
        return False              # nada cambia hasta el reinicio
    if code == "geocode_quota_exceeded":
        return False              # y no se detenga: los créditos siguen
    if code in RETRY:
        return attempt < 5
    return status >= 500

Precisión — qué esperar#

Preferimos fijar bien las expectativas a que usted descubra los límites en producción.

Dónde la predicción es sólida

Temperatura, presión, viento sinóptico, humedad, insolación. El error típico de la temperatura a 2 m a 24 horas ronda 1 a 1,5 °C. El ECMWF es el mejor modelo determinista global del mundo, y es el que usted obtiene.

Dónde es más débil

Las tormentas convectivas — una celda de 28 km no puede resolver una tormenta, e incluso 3 km apenas la insinúan. La ubicación y el momento exactos de los chubascos. Los microclimas costeros y de montaña por debajo de la resolución del modelo. Las brisas marinas y las bolsas de aire frío de valle, que la corrección de relieve no modela.

Honestidad geográfica

En Francia, Alemania, Estados Unidos y Canadá servimos modelos nacionales de 1,3 a 3 km, y un pueblo pequeño obtiene realmente su propia celda. En el resto de Europa obtiene 6,5 km. En África, Oriente Medio y la mayor parte de Asia el mejor modelo público disponible es de 13 a 28 km, así que obtiene la meteorología de la zona en lugar de la de la calle. La corrección de relieve reduce esa brecha, pero no la cierra.

Grados-día

Un reanálisis en malla cubre todas partes, incluidos lugares sin estación meteorológica en 60 km a la redonda — esa es su ventaja frente a los proveedores basados en estaciones. Su debilidad son los centros urbanos, que el reanálisis subestima; los endpoints por ciudad aplican una corrección calibrada, los endpoints por coordenada no.

Dos campos son estimaciones, y preferimos decirlo

uv_index se deriva de la elevación solar y la radiación de banda ancha, no de una columna de ozono — preciso a ±1 unidad aproximadamente. precipitation_probability_proxy es una estimación, no una probabilidad; la auténtica está en /v1/probability. Ambos se explican por extenso en la referencia de campos.

Planes#

El geocodificado queda fuera de esta tabla: no cuesta créditos en ningún plan y lleva su propio tope de cinco solicitudes por crédito. Véanse límites de ritmo y cuota.

La facturación anual regala dos meses. El catálogo vigente está en developers.climatememory.com/pricing — esa página lee el sistema de facturación directamente, así que si ambos llegaran a discrepar, manda ella.

No hay endpoint de exportación masiva en ningún plan. La exportación CSV existe para los archivos de grados-día y de clima, está acotada al mismo intervalo que la llamada JSON equivalente, y devuelve solo filas agregadas — nunca la serie horaria.

Atribución y licencias#

Ninguno de los dos endpoints anteriores necesita clave, así que puede renderizar el aviso desde la API en lugar de incrustar una cadena que quedará obsoleta cuando cambie una fuente. La atribución de la pasada concreta que respondió viaja además en cada respuesta de datos, en source.attribution y en la cabecera X-Data-Attribution.

Puede declarar que utiliza estos datos. No puede dar a entender que alguna de estas organizaciones ha producido, aprobado o respalda su producto.

Descargo de responsabilidad

Las predicciones se facilitan sin garantía. Ni la Comisión Europea, ni el ECMWF, ni el DWD, ni la NOAA, ni Météo-France son responsables del uso que se haga de esta información. No la utilice como base única de decisiones en las que estén en juego la vida, la seguridad o los bienes.

Hay una restricción que no nos corresponde levantar: la licencia de Copernicus reserva los avisos de crecida a las autoridades nacionales y regionales. Véase ríos.