BODACC API Quick Start Guide

Open data e gratuità

L'API BODACC è gratuita e aperta: offre accesso in open data e in tempo reale all'intero database del Bollettino Ufficiale — 11,3 milioni di annunci, 6,7 milioni di imprese, 1,9 milioni di persone (dati live stats/counts). Mentre il file BODACC storico viene scaricato una volta al giorno, l'API espone gli annunci dal momento della pubblicazione, senza chiave per i dati pubblici.

# I contatori esatti, senza chiave
curl "https://bodacc.io/api/bodacc/stats/counts"

Prima chiamata

L'API pubblica BODACC è accessibile senza chiave per i dati. L'endpoint più utilizzato cerca annunci per parola chiave:

curl "https://bodacc.io/api/bodacc/annonces?q=boulangerie&limit=5"

Risposta (estratto):

{
  "total": 48231,
  "results": [
    {
      "id": "A2023001_000123",
      "dateparution": "2026-08-07",
      "typeavis": "A",
      "familleavis": "creation",
      "commercant": "BOULANGERIE DUPONT",
      "ville": "LYON",
      "numerodepartement": "69"
    }
  ],
  "limit": 5,
  "offset": 0
}

Specifica completa

L'API documenta 46 endpoint (verificato sull'OpenAPI live). Due modi per esplorarli:

• Swagger UI: https://bodacc.io/api/bodacc/docs
• https://bodacc.io/api/bodacc/openapi.json

Endpoint principali

Endpoint	Descrizione
GET /api/bodacc/annonces	Ricerca di annunci (parola chiave, famiglia, città, dipartimento, SIREN, date)
GET /api/bodacc/annonces/{id}	Dettaglio di un annuncio + relazioni (impresa, persone)
GET /api/bodacc/entreprises	Ricerca di imprese (nome, SIREN, NAF, stato, filtri avanzati)
GET /api/bodacc/entreprises/{siren}	Scheda completa di un SIREN
GET /api/bodacc/personnes/{id}	Scheda persona (identità + mandati)
GET /api/bodacc/annuaire/{role}	Elenco di liquidatori, mandatari, amministratori
GET /api/bodacc/stats/counts	Contatori globali (annunci, imprese, persone)

Autenticazione

L'accesso pubblico non richiede alcuna chiave. Per le offerte Pro ed Enterprise, gli endpoint documentati accettano una chiave API:

curl "https://bodacc.io/api/bodacc/annonces?q=boulangerie" \
  -H "X-API-Key: sk_bodacc_..."

La chiave può essere passata anche come Authorization: Bearer sk_bodacc_.... Una chiave non valida o revocata restituisce 401.

Errori

L'API restituisce errori HTTP standard con un corpo JSON che descrive il problema:

• 400: parametro non valido
• 401: chiave API non valida o revocata
• 404: risorsa non trovata
• 429: troppe richieste — rispettare l'intestazione Retry-After

Limiti

• limit: tra 1 e 500 per richiesta
• offset: fino a 10 000 (paginazione anti-dump)
• I dati vengono aggiornati in tempo reale dopo ogni pubblicazione del BODACC
• La ricerca per famiglia utilizza totali esatti materializzati (total_estime assente); le ricerche testuali combinate possono restituire un totale stimato ("total_estime": true)

Per approfondire

• Cercare annunci: tutti i parametri di ricerca
• Schede imprese: ricerca e scheda SIREN
• Persone ed elenchi: dirigenti e professionisti
• Statistiche: contatori e serie
• Autenticazione e limiti: chiavi API e buone pratiche