Referencia de la API

curl -H "X-API-Key: TU_API_KEY" https://api.spainelectoralproject.com/v1/elecciones

Si la clave es inválida, revocada o falta, la API responderá con:

{
  "detail": "API key requerida"
}

o

{
  "detail": "API key inválida o revocada"
}

Endpoints

Health

Elecciones

Territorios

Partidos

Resultados

Paginación

Todos los endpoints que devuelven listados (excepto /v1/tipos-eleccion) usan paginación.

Parámetros

Estructura de respuesta paginada

{
  "total": 254,
  "skip": 0,
  "limit": 50,
  "data": [...]
}

• total: número total de registros que cumplen los filtros.
• skip / limit: eco de los parámetros enviados.
• data: array con los registros de la página actual.

Recorrido completo

Para recorrer todos los registros se incrementa skip en cada petición:

Página 1: ?skip=0&limit=100
Página 2: ?skip=100&limit=100
Página 3: ?skip=200&limit=100
...hasta que skip >= total

Cuando no hay coincidencias, la respuesta es total=0 y data=[] (HTTP 200, no es error).

Con POST: la paginación va dentro del body como campo paginacion, no como query params (ver POST en endpoints de resultados).

Filtros

Convenciones generales

• Todos los filtros son opcionales. Sin filtros se devuelven todos los registros.
• Los filtros de texto (nombre, siglas, denominacion, agrupacion) usan búsqueda parcial case-insensitive (ILIKE).
• Para filtrar por múltiples valores, se repite el parámetro: ?tipo_eleccion=G&tipo_eleccion=A.

POST en endpoints de resultados

Los tres endpoints de resultados aceptan también el método POST en el mismo path. El comportamiento es idéntico al GET, pero los filtros se envían en el cuerpo JSON en lugar de en la query string.

¿Cuándo usar POST? Cuando necesitas filtrar por listas largas de municipios u otros identificadores. Las URLs con decenas de IDs superan los límites de longitud de proxies y servidores y producen errores 414 URI Too Long.

Estructura del body

Todos los campos son opcionales. Los campos null se pueden omitir.

{
  "paginacion": { "skip": 0, "limit": 200 },
  "eleccion_id": [208, 226],
  "territorio_id": null,
  "partido_id": [80, 73, 102],
  "year": ["2019", "2023"],
  "tipo_eleccion": ["G"],
  "tipo_territorio": ["municipio"],
  "codigo_ccaa": ["13"],
  "codigo_provincia": null,
  "codigo_municipio": ["28001", "28002", "28003", "..."]
}

partido_id solo está disponible en /votos-partido y /combinados, no en /totales-territorio.

La respuesta es exactamente la misma estructura PaginatedResponse que devuelve el GET.

Ejemplo con curl

curl -X POST https://api.spainelectoralproject.com/v1/resultados/combinados \
  -H "X-API-Key: TU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "paginacion": {"skip": 0, "limit": 500},
    "year": ["2023"],
    "tipo_eleccion": ["G"],
    "tipo_territorio": ["municipio"],
    "codigo_municipio": ["28001", "28002", "28003"]
  }'

Ejemplo con R (httr2)

library(httr2)

body <- list(
  paginacion    = list(skip = 0L, limit = 500L),
  year          = list("2023"),
  tipo_eleccion = list("G"),
  tipo_territorio = list("municipio"),
  codigo_municipio = as.list(mis_municipios)  # vector con todos los códigos
)

resp <- request("https://api.spainelectoralproject.com/v1/resultados/combinados") |>
  req_method("POST") |>
  req_headers(`X-API-Key` = Sys.getenv("ELECCIONESDB_API_KEY")) |>
  req_body_json(body) |>
  req_perform()

resultados <- resp |> resp_body_json(simplifyVector = TRUE)

Filtros por endpoint

/v1/elecciones

/v1/territorios

/v1/partidos

/v1/partidos-recode

/v1/elecciones/{id}/totales-territorio

/v1/resultados/totales-territorio

/v1/resultados/votos-partido y /v1/resultados/combinados

Los mismos filtros que resultados/totales-territorio, más:

Errores

414 URI Too Long

Ocurre cuando el GET de un endpoint de resultados recibe una query string demasiado larga (más de ~4000 caracteres, equivalente a unas 40-50 repeticiones del parámetro codigo_municipio).

{
  "detail": "La query string es demasiado larga y puede causar errores en servidores o proxies intermedios. Usa el endpoint POST en el mismo path enviando los filtros como JSON en el cuerpo de la petición.",
  "post_endpoint": "/v1/resultados/combinados",
  "docs": "/docs"
}

Solución: usa el método POST en el mismo path con los filtros en el body JSON. Ver POST en endpoints de resultados.

404 Not Found

El body siempre tiene la forma {"detail": "Mensaje descriptivo"}. Mensajes posibles: "Elección no encontrada", "Territorio no encontrado", "Partido no encontrado", etc.

422 Validation Error

{
  "detail": [
    {
      "type": "greater_than_equal",
      "loc": ["query", "limit"],
      "msg": "Input should be greater than or equal to 1",
      "input": "-5"
    }
  ]
}

loc indica dónde está el error: ["query", "param"] para query params, ["body", "campo"] para campos del body POST.