Saltar al contenido

Guía de la API REST

Todo lo que hace la web puede hacerse por programa: la API REST usa el mismo motor, los mismos límites y los mismos formatos. La referencia completa e interactiva (OpenAPI) vive en /docs —hace falta haber iniciado sesión para verla—; esta guía recorre el flujo entero con ejemplos curl.

1 · Emita un token

Necesita una cuenta gratuita. La única llamada que acepta contraseña es la emisión del token; todo lo demás viaja con la cabecera Authorization: Bearer. 

curl -X POST https://sarai-data.igme.es/api/v1/tokens \
  -H "Content-Type: application/json" \
  -d '{"login": "su-usuario", "password": "su-clave", "nombre": "mi-script"}'

La respuesta incluye valor — el token, con la forma sarai_… — una sola vez: guárdelo. Puede listar y revocar sus tokens desde la propia API o en su cuenta.

2 · La serie de un punto, al momento

Para la serie de un punto no hace falta pasar por la cola: GET /api/v1/meteo/serie la devuelve en la propia respuesta, en JSON o en CSV, en menos de un segundo incluso para la serie completa (1961–2026, siete variables). 

curl -H "Authorization: Bearer sarai_SU_TOKEN" \
  "https://sarai-data.igme.es/api/v1/meteo/serie?x=-3.7038&y=40.4168&desde=2024-08-01&hasta=2024-08-03&variables=pr&variables=tmax&formato=csv"

Admite los mismos parámetros que la consulta en cola (crs, modo=idw, vecinos, distancia_maxima_m) y la lista de variables repitiendo el parámetro. Tiene un tope de días × variables; por encima responde 413 y remite a la consulta en cola, que además admite zonas y Excel.

3 · O encole una consulta

Meteorológica puntual (nodo más próximo o "modo": "idw" para interpolar): 

curl -X POST https://sarai-data.igme.es/api/v1/consultas/meteo \
  -H "Authorization: Bearer sarai_SU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "tipo_espacial": "puntual",
    "crs": 4326, "x": "-3.7038", "y": "40.4168",
    "modo": "idw",
    "variables": ["pr", "tmax", "tmin"],
    "desde": "1981-01-01", "hasta": "2010-12-31",
    "formato": "csv",
    "identificador": "madrid-normal-climatica"
  }'

La lista variables elige las columnas del resultado entre pr, tmax, tmin, tdew, hr, ssrd y ws; si se omite, se entregan las siete.

Meteorológica de zona (rectángulo NW–SE con nw_x, nw_y, se_x, se_y) o piezométrica (punto y radio): 

curl -X POST https://sarai-data.igme.es/api/v1/consultas/piezo \
  -H "Authorization: Bearer sarai_SU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "crs": 25830, "x": "440291", "y": "4474255",
    "radio_m": 5000,
    "desde": "1990-01-01", "hasta": "2024-12-31",
    "formato": "json"
  }'

Ambas responden 202 Accepted con el id de la consulta: el resultado se genera en segundo plano. Las coordenadas admiten cualquier CRS oficial (catálogo en GET /api/v1/sistemas-referencia, público).

4 · Siga el estado y descargue

# Estado de la consulta (pendiente → procesando → completada)
curl -H "Authorization: Bearer sarai_SU_TOKEN" \
  https://sarai-data.igme.es/api/v1/consultas/123

# El fichero, cuando el estado sea "completada"
curl -OJ -H "Authorization: Bearer sarai_SU_TOKEN" \
  https://sarai-data.igme.es/api/v1/consultas/123/descarga

GET /api/v1/consultas lista su histórico con filtros por estado, fechas e identificador. Los ficheros caducan a los 3 días (la descarga responde entonces 410 Gone); la fila del histórico se conserva.

La serie de un nodo o piezómetro concretos

Lo mismo que hace el mapa de las páginas de datos —elegir un nodo o un piezómetro y descargar su serie completa— existe por programa en dos pasos. Primero, localice el punto con los endpoints públicos de catálogo (no requieren token): 

# Los nodos de rejilla más próximos a un punto (aquí, los 3 primeros)
curl "https://sarai-data.igme.es/api/v1/nodos/cercanos?x=-3.7038&y=40.4168&n=3"

# Los piezómetros en un radio, con su ficha (serie registrada y fechas)
curl "https://sarai-data.igme.es/api/v1/piezometros/cercanos?x=-3.7038&y=40.4168&radio_m=5000"

Después, pida la serie con las coordenadas lon/lat devueltas: para un nodo, POST /consultas/meteo en modo nodo_proximo (resolverá ese mismo nodo, a distancia 0); para un piezómetro, POST /consultas/piezo con un radio pequeño (100 m, como hace la web). Ambos catálogos aceptan crs para expresar x e y en cualquier sistema oficial.

Errores y límites

Cada fichero incluye sus metadatos (fuente, criterio aplicado, significado de cada columna): el resultado se explica solo, y se cita con sus parámetros exactos.