Can I use the API without a key?

Yes, all data endpoints (announcements, companies, people, directory, statistics) are open without a key. The key is only required for documented Pro and Enterprise endpoints.

How do I pass my API key?

Use the X-API-Key header with the value sk_bodacc_..., or Authorization with Bearer sk_bodacc_... An invalid or revoked key returns 401.

What to do in case of 429?

Respect the Retry-After header of the response before retrying. The quota is 60 requests per minute per IP without a key (600 with a key), plus 10 000 requests per day without a key (100 000 with a key).

Why is pagination limited?

To prevent full database dumps: limit is capped at 500, offset at 10 000, and the directory at 200 pages of 100. Iterate over offset to browse results.

API BODACC: autenticazione e limiti : BODACC.io

Accesso pubblico gratuito

L'API BODACC è aperta senza chiave su tutti gli endpoint dei dati: annunci, imprese, persone, annuario, statistiche. Puoi interrogare i dati pubblici immediatamente:

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

Ottenere una chiave API

Le offerte Pro ed Enterprise forniscono chiavi API (prefisso sk_bodacc_) dal tuo spazio Il mio account → API (/{locale}/mon-compte/api). La chiave sblocca l'accesso agli endpoint documentati che la richiedono.

Passare la chiave

Due intestazioni accettate:

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

# Oppure Authorization Bearer
curl "https://bodacc.io/api/bodacc/annonces?q=boulangerie" \
  -H "Authorization: Bearer sk_bodacc_..."

Una chiave invalida o revocata restituisce 401 con un corpo JSON esplicito. L'assenza di chiave lascia l'accesso pubblico aperto (nessun errore).

Codici di errore

Codice	Significato
`400`	Parametro non valido (es. ruolo annuario sconosciuto)
`401`	Chiave API non valida o revocata
`404`	Risorsa non trovata (annuncio, SIREN, persona)
`429`	Troppe richieste o quota superata: rispetta `Retry-After`

Limiti e buone pratiche

Rate limit: 60 richieste/minuto per IP senza chiave, 600 con una chiave valida
Quota giornaliera: 10.000 richieste/giorno per IP senza chiave, 100.000 con chiave: blocca l'iterazione sistematica dei filtri (dump completo del database); il contatore si azzera ogni giorno
Limiti anti-dump: limit ≤ 500, offset ≤ 10.000 su annunci/imprese/agenzie; annuario e attori limitati a 200 pagine da 100
Paginazione sistematica: itera su offset (o page/per_page per l'annuario) invece di richiedere grandi volumi
Retry-After: su 429, attendi la durata indicata prima di riprovare
Totali: preferisci stats/counts e stats/daily (materializzati) ai COUNT(*) per le dashboard
Dati in tempo reale: i dati vengono aggiornati dopo ogni pubblicazione del BODACC
Cache: le ricerche comuni sono servite dalla cache edge Cloudflare (300s): le tue richieste ripetute non contano nella quota

Approfondimenti

Avvio rapido: prima chiamata
Cercare annunci: parametri di ricerca
Statistiche: contatori e serie

API BODACC: autenticazione e limiti