API de Meteorología

Predicción#

Parámetros

Respuesta

{
  "latitude": 48.85,
  "longitude": 2.35,
  "timezone": "Europe/Paris",
  "grid": {
    "latitude": 48.85, "longitude": 2.35,
    "distance_km": 0.42, "resolution_km": 1.3
  },
  "elevation": {
    "applied": true,
    "model_elevation_m": 91.0,
    "location_elevation_m": 113,
    "temperature_offset_c": -0.14
  },
  "source": {
    "model": "mf_arome",
    "model_run": "20260801T00Z",
    "reference_time": "2026-08-01T00:00:00+00:00",
    "data_age_hours": 3.95,
    "stale": false,
    "attribution": "Data: Météo-France (etalab-2.0)"
  },
  "hourly": {
    "time": ["2026-08-01T00:00:00+02:00", "..."],
    "temperature_2m": [18.1, 17.9, 17.6, "..."],
    "apparent_temperature": [17.4, "..."],
    "weather_code": [0, 1, 2, "..."]
  },
  "daily": {
    "date": ["2026-08-01", "..."],
    "temperature_2m_max": [26.6, "..."],
    "temperature_2m_min": [16.2, "..."],
    "precipitation_sum": [0.0, "..."],
    "uv_index_max": [7.6, "..."],
    "sunrise": ["2026-08-01T06:24:00+02:00", "..."],
    "sunset": ["2026-08-01T21:24:00+02:00", "..."],
    "daylight_hours": [15.0, "..."]
  }
}

Reducir la carga útil

El bloque horario completo a 15 días son unos 32 campos × 360 horas. Si va a representar tres, pida tres:

GET /v1/forecast?lat=48.85&lon=2.35&days=3
    &hourly=temperature_2m,precipitation,weather_code
    &include_daily=false

Mismo precio — el coste está en leer el archivo, no en serializarlo — pero la décima parte de los bytes y notablemente más rápido de analizar en un teléfono.

Predicción por ciudad#

Prefiera esto a las coordenadas en bruto siempre que pueda. El catálogo aporta dos cosas que una coordenada no puede: la altitud real de la ciudad, con lo que la corrección de relieve se aplica sin que usted la facilite, y su huso horario, con lo que los agregados diarios se cortan en el día local correcto.

GET /v1/forecast/city/dz/alger      # slug en francés
GET /v1/forecast/city/dz/algiers    # slug en inglés — la misma ciudad
GET /v1/forecast/city/fr/paris

country es un código ISO-3166-1 alfa-2 en minúsculas. slug es insensible a los acentos: bejaia encuentra Béjaïa. Un slug desconocido devuelve 404 city_not_found con un array suggestions — muéstrelo en lugar de un callejón sin salida.

Siguen aplicándose todos los parámetros de consulta de /v1/forecast salvo lat, lon y elevation, que aporta el catálogo. Pasar timezone anula el de la ciudad, que casi nunca es lo que se busca.

Condiciones actuales#

Temperatura, humedad, viento y presión se interpolan linealmente al instante actual, entre los dos pasos del modelo que lo enmarcan.

Úselo para una vista de «ahora mismo». Para todo lo que vaya a comparar en el tiempo, use /v1/forecast y lea la hora que le interese: la serie es estable, mientras que ahora se le mueve bajo los pies entre dos llamadas.

Referencia de campos#

Campos horarios

21 de ellos vuelven por defecto. Los demás están a su disposición sin más que pedirlos — nómbrelos en hourly=, separados por comas — y se retienen por coste, no por desconfianza: cada campo almacenado es una lectura comprimida distinta, de modo que una respuesta por defecto que llevara los 45 haría pagar a todos los clientes por los pocos que quieren el espesor de nieve.

GET /v1/forecast?lat=45.19&lon=5.72&hourly=temperature_2m,snow_line_altitude,soil_temperature_8cm

Un campo que un modelo no publica vuelve como null en el tramo de predicción de ese modelo, en lugar de desaparecer de la respuesta — de modo que un encadenamiento que empieza en AROME y sigue en ICON-EU devuelve visibility de principio a fin, a null durante las primeras 51 horas. Un nombre de campo desconocido da un 400 unknown_field, con la coincidencia más próxima como sugerencia; antes se ignoraba en silencio.

Campos diarios

date, temperature_2m_max, temperature_2m_min, temperature_2m_mean, precipitation_sum, wind_speed_max, wind_gust_max, shortwave_radiation_sum (MJ/m²), uv_index_max, sunrise, sunset, daylight_hours, weather_code.

Agregados sobre días naturales locales, no UTC. Un día parcial en cualquiera de los extremos del rango se omite en lugar de informarse con un máximo engañoso — así que una solicitud de 7 días puede devolver legítimamente 6 filas diarias.

Modelos y resolución#

Servimos el modelo más fino que cubre a la vez su punto y su plazo. Usted nunca elige uno; la elección se informa en source.model, de modo que siempre puede saber cuál respondió.

Los modelos de alta resolución son todos de corto plazo — a 1 km la atmósfera se vuelve caótica en menos de dos días, así que predecir más lejos no tendría sentido — y la resolución baja por escalones a medida que avanza la predicción:

día 0 ─────── día 2 ─────── día 5 ───────────────── día 15
  AROME 1,3 km (Francia)
  ICON-D2 2,2 km (Alemania, Alpes, Benelux)
  HRRR 3 km (EE. UU. y sur de Canadá)
              ICON-EU 6,5 km (Europa)
                          ICON 13 km · ECMWF 28 km (global)
                                              AIFS (solo tendencia)

Las transiciones en el borde del dominio de un modelo se funden, de modo que dos localidades a ambos lados de una frontera nunca discrepan por un salto brusco.

/v1/models no necesita clave, lo que lo convierte en el endpoint adecuado para consultar desde una página de estado o antes de comprar: informa de la última pasada de cada modelo y de su antigüedad, así que «¿están frescos los datos?» se responde sin gastar un crédito.

Probabilidades de conjunto#

Una predicción única dice 22 °C el jueves. Eso es una conjetura presentada como un hecho. Este endpoint responde a la pregunta con la que usted realmente decide: ¿cuán segura es, y qué probabilidad de lluvia merece que se organice en torno a ella?

Se calcula a partir del conjunto del ECMWF — el mismo modelo ejecutado 50 veces desde condiciones iniciales ligeramente distintas. Donde las pasadas coinciden, la predicción es firme. Donde se dispersan, es la propia atmósfera la que es incierta, y ningún modelo, por bueno que sea, puede decirle más.

{
  "members": 50,
  "hourly": {
    "time": ["2026-08-01T00:00:00+00:00"],
    "temperature_2m_p10": [26.4],
    "temperature_2m_p50": [26.78],
    "temperature_2m_p90": [27.3],
    "temperature_2m_spread": [0.4],
    "precipitation_probability_0_1mm": [10.0],
    "precipitation_probability_1_0mm": [0.0],
    "precipitation_probability_5_0mm": [0.0],
    "precipitation_probability_10_0mm": [0.0],
    "precipitation_p90": [0.1]
  }
}

Cómo leerlo

p10 y p90 enmarcan el 80 % central de los miembros: uno de cada diez espera más frío que p10, uno de cada diez más calor que p90. Un spread de 0,4 °C es una situación asentada en la que puede confiar; 3 °C significa que los modelos discrepan y más vale decírselo a sus usuarios que elegir uno.

Los umbrales de lluvia son decisiones y no cifras redondas — 0,1 mm es mojado, sin más, 1 mm es coja un abrigo, 5 y 10 mm son esto es un problema. precipitation_p90 es el caso desfavorable: solo uno de cada diez miembros es más lluvioso.

Calidad del aire#

Este es el endpoint que más importa en el norte de África y el Mediterráneo. Un episodio de polvo lleva las PM10 por encima de los mil microgramos por metro cúbico durante días seguidos, lo que es una decisión de salud más que una cifra, y está mal cubierto por los servicios gratuitos de consumo.

{
  "current": {
    "pm2_5": 38.7,
    "band": "poor",
    "who_guidelines_ug_m3": {"pm2_5": 15.0, "pm10": 45.0,
                             "nitrogen_dioxide": 25.0, "ozone": 100.0}
  },
  "hourly": {
    "time": ["2026-08-01T00:00:00+00:00"],
    "pm2_5": [38.7], "pm10": [85.8], "ozone": [43.4],
    "nitrogen_dioxide": [19.0], "dust_aod_550nm": [0.24]
  },
  "units": {"pm2_5": "ug/m3", "pm10": "ug/m3", "dust_aod_550nm": "1"}
}

Todas las concentraciones van en µg/m³, la unidad en la que se cita la calidad del aire en todas partes. dust_aod_550nm es un espesor óptico y no tiene unidad: por encima de 0,5 aproximadamente el cielo está visiblemente turbio, por encima de 1,0 el sol queda atenuado.

Los valores guía a corto plazo de la OMS viajan en cada respuesta, de modo que una cifra puede situarse sin ir a buscarla. band sigue el índice europeo de calidad del aire para PM2,5: buena, razonable, media, mala, muy mala, extremadamente mala.

La nieve y la cota de nieve#

Cuatro campos, y responden a preguntas distintas. snowfall es cuánta cae; los demás describen lo que hay en el suelo, y dónde.

Pídalos por su nombre — no están en la respuesta por defecto:

GET /v1/forecast?lat=45.19&lon=5.72&hourly=snowfall,snow_depth,snow_water_equivalent,snow_line_altitude,freezing_level_altitude

La cota de nieve es la que merece leerse. «Llueve a 800 m y nieva a 1200» es algo sobre lo que una estación de esquí, una autoridad de carreteras o un conductor pueden actuar; «3 mm de precipitación» no lo es. También importa en el norte de África — el Atlas tiene estaciones de esquí en Chréa y Tikjda, y las mesetas altas de Sétif, Batna y Djelfa superan los 1000 m.

Estos campos proceden de ICON, del DWD, que cubre el mundo a 13 km. Los datos abiertos del ECMWF publican el espesor de nieve pero no la cota: este es, pues, un caso en el que el modelo más grueso es el más útil. snow_line_altitude es un producto regional — ICON-EU e ICON-D2 lo publican, ICON global no, de modo que fuera de Europa obtiene la isoterma y el espesor, pero no la cota en sí.

Mar — estado del mar#

{
  "hourly": {
    "time": ["2026-08-01T00:00:00+00:00"],
    "wave_height": [0.32],
    "wave_direction": [264.3],
    "wave_period": [3.79],
    "wave_peak_period": [4.21]
  }
}

La altura de ola es la altura significativa — la media del tercio de olas más altas, que es aproximadamente lo que informa un observador en el mar. Las olas individuales alcanzan cerca del doble, y esa es la cifra que importa si está decidiendo si salir. La dirección es aquella desde la que vienen las olas, como en la dirección del viento.

Ríos#

Responde a lo que ningún modelo meteorológico puede: no cuánta lluvia cae aguas arriba, sino cuánta agua llega aquí — una cifra muy distinta, separada de la lluvia por una cuenca, un estado de humedad del suelo y uno o dos días de recorrido.

{
  "disclaimer": "Information only. Only national and regional authorities
                 are authorised to issue flood warnings.",
  "daily": {
    "time": ["2026-08-01T00:00:00+00:00"],
    "river_discharge": [4.953],
    "soil_wetness_index": [0.448]
  }
}