API de datos para medios y desarrolladores
Para redacciones y equipos técnicos que quieren los resultados en bruto y pintarlos a su manera. Si solo quieres mostrarlos en tu web, los widgets gratuitos no necesitan clave.
Qué es
Los mismos ficheros JSON estáticos que usa esta web, en https://api.generales29n.com/v1/…. Salen del mismo almacén (Cloudflare R2) sin ningún servidor de aplicación en medio: un Worker de Cloudflare comprueba la clave y entrega los ficheros tal cual, así que lo que descargas es exactamente lo que ve el lector.
La cabecera X-Api-Key: <clave> es obligatoria en cada petición. Color Vivo da una clave a cada medio: es personal y se puede revocar. Sin clave, la API responde 401; con una clave no válida o revocada, 403.
Solo admite peticiones GET y HEAD bajo /v1/: fuera de /v1/ responde 404 y con otro método, 405.
Nuestra web y nuestros widgets leen de un host interno distinto; para terceros, el único punto de acceso es la API.
La documentación es pública; lo que protege los datos es la clave.
Elecciones
| Slug | Qué es | Fichero de entrada |
|---|---|---|
| Elecciones del 29 de noviembre de 2026 | ||
congreso-2026-11 | Congreso de los Diputados | v1/congreso-2026-11/manifest.json |
senado-2026-11 | Senado | v1/senado-2026-11/manifest.json |
| Entorno de pruebas | ||
congreso-simulacro | Simulacro del Ministerio del Interior del 18 de noviembre, Congreso (datos de prueba, no son resultados) | v1/congreso-simulacro/manifest.json |
senado-simulacro | Simulacro del Ministerio del Interior del 18 de noviembre, Senado (datos de prueba) | v1/senado-simulacro/manifest.json |
congreso-replay | Noche electoral simulada con los datos de 2023; solo cuando la activamos (a demanda) | v1/congreso-replay/manifest.json |
| Históricos (mismo esquema, sin manifiesto ni seq) | ||
congreso-2023-07 | Por ejemplo, Congreso del 23 de julio de 2023 | v1/hist/congreso-2023-07/es.json |
En los históricos, los ficheros están en v1/hist/{elección}/{ámbito}.json (es.json, ccaa/{código}.json, prov/{código}.json, mun/{código INE de 5 dígitos}.json) y no cambian: no hace falta sondear nada.
Flujo recomendado
- Pide
v1/{elección}/manifest.jsoncada 10–15 segundos. El manifiesto tiene una caché de 5 segundos: pedirlo más a menudo no da datos más frescos. - Compara su
seqcon el último que procesaste. Si es distinto, hay una publicación nueva. Compara con!==, nunca con>: elseqpuede bajar si retiramos una publicación errónea, y entonces debes volver a la anterior. - Descarga solo los ámbitos que necesites desde la carpeta
basedel manifiesto:es.json(España),ccaa/{código}.json(comunidad autónoma),prov/{código INE de 2 dígitos}.json(circunscripción) ycera/{código}.json(voto exterior por provincia). - Municipios, solo a través del índice: descarga
base+mun_index(con{prov}sustituido por el código de la provincia) y usa la ruta del municipio que da ese índice, relativa aroot:root+ ruta. No construyas nuncamun/X.jsona mano: en una publicación en la que un municipio no cambia, ese fichero no existe en su carpeta. - Los ficheros de cada
seqson inmutables (caché de un año): una vez descargados, no hace falta volver a pedirlos.
El manifiesto
version- Versión del contrato (
1). Los campos nuevos se añaden sin renombrar los existentes. election- Slug de la elección.
seq- Número de la publicación vigente. Puede bajar: compara con
!==. generated_at- Fecha y hora de la publicación (UTC, ISO 8601).
phase- Fase de la noche (ver «Fases y embargo»).
counted_pct- Porcentaje escrutado en España.
staletruesi la fuente lleva un rato sin actualizar: conviene avisar al lector con la hora del dato.embargotrueantes de la hora oficial de difusión: no hay resultados, solo participación.base- Carpeta de la publicación vigente:
…/v1/{elección}/{seq}/. root- Raíz de la elección:
…/v1/{elección}/. mun_index- Plantilla del índice de municipios, relativa a
base:_idx/mun/{prov}.json. winners_index- Más votada de cada municipio, relativo a
base. winners_scopes- Más votada de cada provincia y comunidad, relativo a
base. source- Fuente de los datos publicados.
source_url- Enlace a la fuente, si lo hay.
officialtruesi los datos son oficiales.
Ejemplo de manifiesto
Valores ilustrativos: no son datos reales.
{
"version": 1,
"election": "congreso-2026-11",
"seq": 42,
"generated_at": "2026-11-29T21:05:12Z",
"phase": "results",
"counted_pct": 12.48,
"stale": false,
"embargo": false,
"base": "https://api.generales29n.com/v1/congreso-2026-11/42/",
"root": "https://api.generales29n.com/v1/congreso-2026-11/",
"mun_index": "_idx/mun/{prov}.json",
"winners_index": "_idx/winners.json",
"winners_scopes": "_idx/winners/scopes.json",
"source": "Ministerio del Interior (resultados provisionales)",
"source_url": null,
"official": true
} Campos de un ámbito
Cada {ámbito}.json (España, comunidad, provincia o municipio) tiene la misma forma:
scopetype(es,ccaa,prov,mun,cera…),code(código INE:00España, 2 dígitos comunidad o provincia, 5 dígitos municipio) yname(tal como lo publica la fuente).seq- Publicación a la que pertenece el fichero (en
mun, la del último cambio del municipio). No viene en los históricos. updated_at- Fecha y hora del dato (UTC).
turnoutcensus,votersypct(participación), avancesadvance_1_pct(14:00) yadvance_2_pct(18:00),nullsi no hay dato (nunca 0 %);basis(resident: sin voto exterior, como la noche;census: incluye CERA) ylabel.ref: la misma participación en la elección de referencia.countedtables,total_tablesypct: mesas escrutadas y porcentaje escrutado.totalsvalid(votos válidos, incluye blancos),blankynull(votos en blanco y nulos).results[]- Una fila por candidatura:
candidacy(código),acronym(siglas),short_name(nombre corto editorial onull),name,family(familia editorial onull),color,votes,pct(sobre votos válidos, con 2 decimales),seatsyseats_source(officialocalc) donde se reparten escaños;refydelta: votos, % y escaños en la elección de referencia y diferencia. seats_label- Si no es
null, los escaños son un cálculo propio y este texto lo indica (hay que mostrarlo). seats_provisionaltruehasta el escrutinio general.last_seat- Solo en provincias:
winneryrunner_updel último escaño,votes_short(votos que le faltan a la siguiente) ylabel. En España y comunidades,last_seats: los escaños más ajustados. reference- Elección con la que se comparan
refydelta. source, source_url, official- Fuente del dato, enlace y si es oficial. Un fichero sin fuente no se publica.
Ejemplo real: Ciudad Real, generales de 2023
v1/hist/congreso-2023-07/prov/13.json, recortado a las tres primeras candidaturas («…»). Fuente:
Ministerio del Interior (Infoelectoral).
{
"scope": {
"type": "prov",
"code": "13",
"name": "Ciudad Real"
},
"updated_at": "2026-11-17T14:54:12Z",
"turnout": {
"census": 391495,
"voters": 286895,
"pct": 73.28,
"advance_1_pct": 45.46,
"advance_2_pct": 56.39,
"basis": "census",
"label": "Incluye voto exterior (CERA)",
"ref": {
"election": "congreso-2019-11",
"pct": 68.84,
"advance_1_pct": 36.19,
"advance_2_pct": 55.26,
"basis": "census"
}
},
"counted": {
"tables": 707,
"total_tables": 707,
"pct": 100
},
"totals": {
"valid": 282979,
"blank": 2353,
"null": 3916
},
"results": [
{
"candidacy": "000005",
"acronym": "PP",
"short_name": null,
"name": "PARTIDO POPULAR",
"family": "pp",
"color": "#1d84ce",
"votes": 114709,
"pct": 40.54,
"seats": 2,
"seats_source": "official",
"ref": {
"election": "congreso-2019-11",
"votes": 74835,
"pct": 27.86,
"seats": 2
},
"delta": {
"pct": 12.68,
"seats": 0
}
},
{
"candidacy": "000002",
"acronym": "PSOE",
"short_name": null,
"name": "PARTIDO SOCIALISTA OBRERO ESPAÑOL",
"family": "psoe",
"color": "#e30613",
"votes": 100102,
"pct": 35.37,
"seats": 2,
"seats_source": "official",
"ref": {
"election": "congreso-2019-11",
"votes": 92046,
"pct": 34.27,
"seats": 2
},
"delta": {
"pct": 1.1,
"seats": 0
}
},
{
"candidacy": "000006",
"acronym": "VOX",
"short_name": null,
"name": "VOX",
"family": "vox",
"color": "#63be21",
"votes": 46046,
"pct": 16.27,
"seats": 1,
"seats_source": "official",
"ref": {
"election": "congreso-2019-11",
"votes": 56050,
"pct": 20.87,
"seats": 1
},
"delta": {
"pct": -4.6,
"seats": 0
}
},
… (resto de candidaturas)
],
"source": "Ministerio del Interior (Infoelectoral)",
"source_url": "https://infoelectoral.interior.gob.es/estaticos/docxl/apliextr/02202307_MESA.zip",
"official": true,
"reference": {
"election": "congreso-2019-11",
"chamber": "congreso",
"date": "2019-11-10",
"name": "Congreso, 10 de noviembre de 2019"
},
"seats_label": null,
"seats_provisional": false,
"last_seat": {
"winner": {
"candidacy": "000006",
"acronym": "VOX",
"short_name": null
},
"runner_up": {
"candidacy": "000005",
"acronym": "PP",
"short_name": null
},
"votes_short": 23429,
"label": "Cálculo propio sobre datos del Ministerio del Interior"
}
} Fases y embargo
pre- Antes de la jornada: sin datos.
turnout- Jornada en curso: participación (avances de las 14:00 y las 18:00), sin resultados.
results- Escrutinio provisional en curso, desde la hora oficial de difusión.
provisional_final- Escrutinio provisional al 100 %.
final- Escrutinio general (incluye el voto exterior, CERA).
- Con
embargo: trueno hay resultados:resultsva vacío y solo se publica la participación. No se publica nada antes de la hora oficial de difusión, igual en la web, los widgets y la API. - Los escaños son provisionales (
seats_provisional: true) hasta el escrutinio general: el voto exterior (CERA) puede mover el último escaño de una provincia. - Si nuestro cálculo de escaños difiere del oficial, publicamos el oficial (
seats_source: "official"). - Senado en vivo: resumen del escrutinio y electos por circunscripción.
Frecuencia de actualización
Publicamos cada envío nuevo del Ministerio del Interior a los pocos segundos de recibirlo. La noche electoral, Interior hace varios envíos por hora al principio y uno cada pocos minutos durante el escrutinio.
Límite de peticiones
- Límite: 300 peticiones por minuto por clave. Al superarlo, la API responde 429 con la cabecera
Retry-After(segundos que hay que esperar antes de volver a pedir). - El flujo recomendado queda muy por debajo: el manifiesto cada 10–15 segundos son 4–6 peticiones por minuto, y los ámbitos solo se piden cuando cambia
seq. Si te acercas al límite, casi siempre es porque se piden ficheros sin comprobar elseqo porque cada lector consulta la API en vez de tu caché. - Si recibes un 429, espera lo que indique
Retry-Aftery sigue sirviendo el último dato bueno.
Navegador o servidor
- La API no envía cabeceras CORS: no se puede llamar desde el navegador. Una web debe consultarla desde su servidor y servir a sus lectores su propia copia.
- Nunca pongas la clave en el JavaScript del navegador: cualquiera podría leerla y usarla en tu nombre.
- Las apps nativas pueden llamar a la API directamente.
- Recomendado: cachear en tu servidor y que todos tus lectores lean de esa caché, no de la API.
Condiciones de uso (beta gratuita)
- Atribución visible junto a los datos: «Fuente: Ministerio del Interior · Datos: Generales29N.com (Color Vivo)». En los escaños, «Cálculo propio de Generales29N.com» cuando lo indique
seats_label. - La clave es personal e intransferible.
- Sin reventa ni redistribución de los datos como API.
- A cambio del acceso gratuito: mención visible a Color Vivo (https://colorvivo.com) y un enlace o espacio promocional a noticias.madrid (https://noticias.madrid) en la web o la app donde se usen los datos.
- Uso razonable: el manifiesto, cada 10–15 segundos como mucho; los demás ficheros, solo cuando cambie
seq; nunca más de 300 peticiones por minuto por clave. - Beta gratuita, sin SLA: el acceso se puede revocar.
- Manda siempre el dato oficial del Ministerio del Interior.
La API sirve una elaboración propia de Generales29N.com (datos normalizados y agregados por ámbito, con escaños y participación calculados) a partir de los resultados provisionales que difunde el Ministerio del Interior. No da acceso a ningún sistema del Ministerio. Citar siempre «Fuente: Ministerio del Interior».
Ejemplos de código
El mismo flujo en varios lenguajes: consultar el manifiesto, descargar es.json solo cuando cambia seq y respetar el límite (429 y Retry-After). Pon tu clave en una variable de entorno, nunca en el código.
curl
Una petición del manifiesto desde la terminal.
curl -H "X-Api-Key: TU_CLAVE" \
https://api.generales29n.com/v1/congreso-2026-11/manifest.json JavaScript
Node 18 o posterior, en tu servidor: sondea el manifiesto y descarga es.json solo cuando cambia seq.
// Node 18 o posterior (fetch nativo), en tu servidor. La clave, en una variable de entorno.
const headers = { 'X-Api-Key': process.env.GENERALES29N_API_KEY }; // TU_CLAVE
const MANIFEST = 'https://api.generales29n.com/v1/congreso-2026-11/manifest.json';
let lastSeq = null;
let espana = null; // último dato bueno: lo que sirves a tus lectores
async function getJson(url) {
const res = await fetch(url, { headers });
if (res.status === 429) {
// Límite por clave superado: esperar lo que diga Retry-After (segundos).
const wait = Number(res.headers.get('Retry-After')) || 60;
throw Object.assign(new Error('429'), { wait });
}
if (!res.ok) throw new Error(`${res.status} ${url}`); // 401 sin clave, 403 clave no válida
return res.json();
}
async function poll() {
let delay = 15_000;
try {
const m = await getJson(MANIFEST);
// El seq puede bajar (retirada de una publicación errónea): !==, nunca >.
if (m.seq !== lastSeq) {
espana = await getJson(new URL('es.json', m.base));
lastSeq = m.seq; // solo tras descargar bien
console.log(m.seq, m.phase, m.embargo, espana.counted.pct, espana.source);
}
} catch (err) {
console.error(err.message); // se conserva el último dato bueno
if (err.wait) delay = err.wait * 1000;
} finally {
setTimeout(poll, delay);
}
}
poll(); PHP
PHP 8 con curl, en tu servidor (CLI o cron): el mismo flujo.
<?php
// PHP 8 con la extensión curl, en tu servidor (CLI o cron). La clave, en una variable de entorno.
const MANIFEST = 'https://api.generales29n.com/v1/congreso-2026-11/manifest.json';
$key = getenv('GENERALES29N_API_KEY'); // TU_CLAVE
function getJson(string $url, string $key): array {
$ch = curl_init($url);
curl_setopt_array($ch, [
CURLOPT_HTTPHEADER => ['X-Api-Key: ' . $key],
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HEADER => true,
CURLOPT_ENCODING => '', // acepta gzip
CURLOPT_TIMEOUT => 10,
]);
$raw = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
$headerSize = curl_getinfo($ch, CURLINFO_HEADER_SIZE);
curl_close($ch);
if ($status === 429) {
// Límite por clave superado: esperar lo que diga Retry-After (segundos).
preg_match('/^retry-after:\s*(\d+)/mi', substr($raw, 0, $headerSize), $m);
throw new RuntimeException('429', (int) ($m[1] ?? 60));
}
if ($status !== 200) {
throw new RuntimeException("$status $url"); // 401 sin clave, 403 clave no válida
}
return json_decode(substr($raw, $headerSize), true, 512, JSON_THROW_ON_ERROR);
}
$lastSeq = null;
while (true) {
$delay = 15;
try {
$m = getJson(MANIFEST, $key);
// El seq puede bajar (retirada de una publicación errónea): !==, nunca >.
if ($m['seq'] !== $lastSeq) {
$espana = getJson($m['base'] . 'es.json', $key);
$lastSeq = $m['seq']; // solo tras descargar bien
// Guarda $espana en tu caché y sírvelo desde ahí a tus lectores.
echo $m['seq'], ' ', $m['phase'], ' ', $espana['counted']['pct'], ' ', $espana['source'], PHP_EOL;
}
} catch (RuntimeException $e) {
error_log($e->getMessage()); // se conserva el último dato bueno
if ($e->getMessage() === '429') {
$delay = max($e->getCode(), 1);
}
}
sleep($delay);
} Python
Python 3.9 o posterior, solo biblioteca estándar: el mismo flujo.
# Python 3.9 o posterior, solo con la biblioteca estándar, en tu servidor.
import json
import os
import time
import urllib.error
import urllib.request
MANIFEST = "https://api.generales29n.com/v1/congreso-2026-11/manifest.json"
KEY = os.environ["GENERALES29N_API_KEY"] # TU_CLAVE
class RateLimited(Exception):
def __init__(self, wait):
super().__init__("429")
self.wait = wait
def get_json(url):
req = urllib.request.Request(url, headers={"X-Api-Key": KEY})
try:
with urllib.request.urlopen(req, timeout=10) as res:
return json.load(res)
except urllib.error.HTTPError as err:
if err.code == 429:
# Límite por clave superado: esperar lo que diga Retry-After (segundos).
raise RateLimited(int(err.headers.get("Retry-After", 60)))
raise # 401 sin clave, 403 clave no válida
last_seq = None
espana = None # último dato bueno: lo que sirves a tus lectores
while True:
delay = 15
try:
m = get_json(MANIFEST)
# El seq puede bajar (retirada de una publicación errónea): !=, nunca >.
if m["seq"] != last_seq:
espana = get_json(m["base"] + "es.json")
last_seq = m["seq"] # solo tras descargar bien
print(m["seq"], m["phase"], espana["counted"]["pct"], espana["source"])
except RateLimited as err:
delay = err.wait
except Exception as err: # se conserva el último dato bueno
print("error:", err)
time.sleep(delay) Cómo pedir una clave
Escribe a [email protected] (asunto «Clave de la API de Generales29N») o usa el formulario de contacto de Color Vivo Internet, e indica:
- Nombre del medio, aplicación o proyecto y su web o enlace en la tienda de aplicaciones.
- Para qué vas a usar los datos (web, app, gráficos, redes…) y qué elecciones y ámbitos necesitas.
- Si consultarás desde un servidor propio o desde una app nativa, y una estimación del número de usuarios la noche electoral.
- Persona de contacto técnico, con correo y teléfono, por si hay que avisar de cambios o incidencias la noche del 29N.
A cambio del acceso gratuito pedimos:
- Citar siempre junto a los datos «Fuente: Ministerio del Interior · Datos: Generales29N.com (Color Vivo)» (la mención al Ministerio del Interior es obligatoria).
- Mención visible a Color Vivo (https://colorvivo.com) como proveedor de los datos.
- Un enlace o espacio promocional a noticias.madrid (https://noticias.madrid), el diario de la casa, en la web o la app donde uses los datos.
Damos claves a medios de comunicación y proyectos informativos. Cada clave es personal y se puede revocar; al recibirla aceptas las condiciones de uso de esta página.
Fuente de los datos: Ministerio del Interior. Fuentes y licencias en Datos abiertos y Fuentes y metodología. Página actualizada el .