# API de datos para medios y desarrolladores

> Los JSON de resultados de las generales del 29N (Congreso y Senado) con clave: elecciones, flujo de consulta, campos, embargo, ejemplos de código y condiciones de uso.

> **Acceso solo con clave. Para conectar con la API necesitas una clave (token) válida, personal y concedida por Color Vivo. Sin ella, todas las peticiones se rechazan: 401 si falta la cabecera X-Api-Key y 403 si la clave no es válida o se ha revocado. No hay acceso abierto ni de prueba sin clave.** Pide la tuya en info@colorvivo.com.

## 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

### Elecciones del 29 de noviembre de 2026

| Slug | Qué es | Fichero de entrada |
| --- | --- | --- |
| `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

| Slug | Qué es | Fichero de entrada |
| --- | --- | --- |
| `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)

| Slug | Qué es | Fichero de entrada |
| --- | --- | --- |
| `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.

## Manifiesto

| Campo | Qué es |
| --- | --- |
| `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 (valores ilustrativos, no son datos reales):

```json
{
  "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 ({ámbito}.json)

| Campo | Qué es |
| --- | --- |
| `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 recortado: `v1/hist/congreso-2023-07/prov/13.json` (Ciudad Real, generales de 2023; solo las tres primeras candidaturas). Fuente: Ministerio del Interior (Infoelectoral).

```json
{
  "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

| phase | Qué significa |
| --- | --- |
| `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

### curl

Una petición del manifiesto desde la terminal.

```sh
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.

```js
// 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
// 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
# 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 [info@colorvivo.com](mailto:info@colorvivo.com) (asunto «Clave de la API de Generales29N») o usa el [formulario de contacto de Color Vivo Internet](https://colorvivo.com/contacto/), 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.

Página actualizada el 18 de noviembre de 2026. Datos abiertos, fuentes y licencias: https://generales29n.com/datos/. Widgets gratuitos sin clave: https://generales29n.com/compartir/.

---

Fuente: Ministerio del Interior (Infoelectoral).
Fuentes, licencias y metodología: https://generales29n.com/fuentes/ (Markdown: https://generales29n.com/fuentes/index.md).
URL canónica: https://generales29n.com/datos/api/
Generado: 18 de noviembre de 2026 a las 13:32 (hora de Madrid).
Elecciones 29N es una web informativa independiente de Color Vivo Internet, S.L.U.; no es una web oficial del Ministerio del Interior ni de la Junta Electoral.
