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

Slugs de las elecciones y fichero de entrada de cada una
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

  1. Pide v1/{elección}/manifest.json cada 10–15 segundos. El manifiesto tiene una caché de 5 segundos: pedirlo más a menudo no da datos más frescos.
  2. Compara su seq con el último que procesaste. Si es distinto, hay una publicación nueva. Compara con !==, nunca con >: el seq puede bajar si retiramos una publicación errónea, y entonces debes volver a la anterior.
  3. Descarga solo los ámbitos que necesites desde la carpeta base del manifiesto: es.json (España), ccaa/{código}.json (comunidad autónoma), prov/{código INE de 2 dígitos}.json (circunscripción) y cera/{código}.json (voto exterior por provincia).
  4. 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 a root: root + ruta. No construyas nunca mun/X.json a mano: en una publicación en la que un municipio no cambia, ese fichero no existe en su carpeta.
  5. Los ficheros de cada seq son 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.
stale
true si la fuente lleva un rato sin actualizar: conviene avisar al lector con la hora del dato.
embargo
true antes 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.
official
true si 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:

scope
type (es, ccaa, prov, mun, cera…), code (código INE: 00 España, 2 dígitos comunidad o provincia, 5 dígitos municipio) y name (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).
turnout
census, voters y pct (participación), avances advance_1_pct (14:00) y advance_2_pct (18:00), null si no hay dato (nunca 0 %); basis (resident: sin voto exterior, como la noche; census: incluye CERA) y label. ref: la misma participación en la elección de referencia.
counted
tables, total_tables y pct: mesas escrutadas y porcentaje escrutado.
totals
valid (votos válidos, incluye blancos), blank y null (votos en blanco y nulos).
results[]
Una fila por candidatura: candidacy (código), acronym (siglas), short_name (nombre corto editorial o null), name, family (familia editorial o null), color, votes, pct (sobre votos válidos, con 2 decimales), seats y seats_source (official o calc) donde se reparten escaños; ref y delta: 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_provisional
true hasta el escrutinio general.
last_seat
Solo en provincias: winner y runner_up del último escaño, votes_short (votos que le faltan a la siguiente) y label. En España y comunidades, last_seats: los escaños más ajustados.
reference
Elección con la que se comparan ref y delta.
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: true no hay resultados: results va 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 el seq o porque cada lector consulta la API en vez de tu caché.
  • Si recibes un 429, espera lo que indique Retry-After y 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.

Escribir a [email protected]

Fuente de los datos: Ministerio del Interior. Fuentes y licencias en Datos abiertos y Fuentes y metodología. Página actualizada el .