Tier 2

API pubblica

Accesso programmatico ai dati elettorali ElectionLab per gli account Tier 2. Autenticazione tramite header X-API-Key: la chiave non va mai nell'URL.

Genera una API key Apri Swagger UI

Autenticazione

export KEY="elk_live_..."   # generata in Area personale → API ed export
curl -H "X-API-Key: $KEY" "https://api.electionlab.it/v1/public/elections"

Limiti

Un tetto giornaliero per utente, dichiarato nella pagina dei piani: vale per tutte le tue chiavi insieme e si azzera a mezzanotte UTC. Ogni risposta porta X-Quota-Remaining e X-Quota-Reset. Oltre il tetto la risposta è 429, con Retry-After in secondi e l'ora di reset nel corpo. In più, un limite di richieste al minuto per chiave (X-RateLimit-Remaining).

HTTP/1.1 429 Too Many Requests
Retry-After: 30512

{"detail": {"message": "Tetto giornaliero di richieste API raggiunto.",
            "limit": 10000, "reset_at": "2026-09-11T00:00:00Z", "retry_after": 30512}}

Endpoint

GET/public/elections

Lista elezioni con filtri (type_code, year, future).

curl -H "X-API-Key: $KEY" "https://api.electionlab.it/v1/public/elections?type_code=camera"

GET/public/elections/{id}/results

Risultati partitici aggregati di un'elezione.

curl -H "X-API-Key: $KEY" "https://api.electionlab.it/v1/public/elections/42/results"

GET/public/municipalities/{istat}/results

Risultati comunali per codice ISTAT (richiede election_id).

curl -H "X-API-Key: $KEY" "https://api.electionlab.it/v1/public/municipalities/058091/results?election_id=42"

GET/public/sentiment/{entity_type}/{entity_id}

Sentiment aggregato (politician|party) sugli ultimi 30 giorni.

curl -H "X-API-Key: $KEY" "https://api.electionlab.it/v1/public/sentiment/politician/abc-123"

GET/public/predictions

Elenco predizioni disponibili (elezioni future predicibili).

curl -H "X-API-Key: $KEY" "https://api.electionlab.it/v1/public/predictions"

GET/export/csv

Export raw CSV/JSON come job (Tier 2, chiave full). Limite 100k righe. Ritorna un job: si interroga /export/{job_id} finché non c'è il link firmato.

curl -H "X-API-Key: $KEY" "https://api.electionlab.it/v1/export/csv?election_id=42&level=municipality&format=csv"

Plugin / Widget embed

I partner possono incorporare widget tramite <iframe>. Le chiavi embed sono generate automaticamente alla creazione di un plugin e autorizzate solo sui domini in whitelist.

<iframe
  src="https://electionlab.it/embed/election-map?election_id=42&api_key=ELK_EMBED_KEY"
  width="420" height="560" style="border:0">
</iframe>