Facebook Ad Library API: la guida per sviluppatori a ads_archive

La Facebook Ad Library API è l'endpoint ufficiale della Graph API di Meta, ads_archive, per cercare nell'archivio pubblico di annunci in modo programmatico. Ti autentichi con uno user access token, passi il parametro obbligatorio ad_reached_countries, e filtri per parole chiave, Page ID, tipo di annuncio, date e piattaforme per ricevere risultati in JSON. La copertura è limitata: annunci politici e di temi sociali in tutto il mondo per sette anni, più tutti gli annunci diffusi nell'UE o nel Regno Unito per un anno. Spend e impressions tornano come intervalli, il che li rende dati di ricerca competitiva gratuiti ma limitati.

Hai cercato nell'ad library da un browser, hai trovato ciò che ti serviva, e ora vuoi gli stessi dati in JSON: estrazioni programmate, una dashboard sui competitor, un dataset di ricerca. È esattamente a questo che serve l'Ad Library API (ufficialmente la Meta Ad Library API dal rebranding), ed è genuinamente gratuita. È anche l'API più fraintesa nella superficie sviluppatori di Meta, perché la maggior parte degli sviluppatori arriva aspettandosi accesso programmatico a tutto ciò che può vedere sul sito, e scopre che l'archivio ha regole proprie.

Se non hai ancora lavorato con lo strumento sottostante, parti dalla nostra guida completa alla Meta Ads Library, perché l'API eredita ogni proprietà della versione web e poi la restringe ulteriormente. Questa guida copre la parte che conta per gli sviluppatori: cosa restituisce davvero l'API, la configurazione dell'accesso, l'endpoint ads_archive con esempi funzionanti in curl e Python, rate limit e codici di errore, e la lista onesta delle cose che non ti darà mai, insieme a cosa usare al loro posto.

Cosa copre davvero la Facebook Ad Library API

Prima di scrivere anche solo una riga di codice, interiorizza l'ambito, perché spiega quasi ogni risposta vuota che otterrai mai. L'archivio dietro l'API contiene esattamente due categorie di annunci:

Tutto il resto semplicemente non esiste per l'API. Un annuncio commerciale trasmesso solo negli Stati Uniti non è archiviato, non è ricercabile e non è recuperabile. Quella domanda su Stack Overflow del 2019 sul perché le ricerche per parole chiave restituiscono solo annunci politici è ancora ben posizionata oggi perché la confusione non è mai sparita. La ricerca per parole chiave sugli annunci commerciali funziona solo dove quegli annunci sono stati diffusi a utenti dell'UE o del Regno Unito, dato che sono gli unici annunci commerciali nell'archivio.

Due cambiamenti recenti hanno stretto ulteriormente questo. La copertura del Regno Unito si applica agli annunci trasmessi dopo il 1° luglio 2025, quindi l'archivio del Regno Unito si sta ancora costruendo verso un anno mobile completo. E all'inizio di ottobre 2025, Meta ha smesso completamente di accettare annunci politici, elettorali e di temi sociali nell'UE, in risposta al regolamento UE su Trasparenza e Targeting della Pubblicità Politica. L'archivio politico storico dell'UE resta interrogabile, ma ora è congelato: le query per annunci politici UE dopo quella data non restituiscono nulla perché nessuno è più attivo.

Per uno sviluppatore, il test pratico è semplice. Se il tuo caso d'uso è la ricerca di annunci politici ovunque, o la ricerca di qualsiasi annuncio nei mercati UE e Regno Unito, l'API ufficiale funziona. Se ti servono annunci commerciali US per parola chiave, non può aiutarti, e dovresti saltare direttamente alla sezione delle alternative.

Ad Library API contro Marketing API

Le due vengono confuse costantemente, e non condividono nient'altro che un nome di dominio. La Marketing API gestisce la pubblicità che possiedi: crea campagne, carica creative e legge la performance degli account pubblicitari su cui hai permessi. L'Ad Library API è un accesso in sola lettura all'archivio pubblico di trasparenza degli annunci di tutti gli altri.

Le differenze attraversano ogni livello. La Marketing API richiede i permessi ads_read o ads_management e spesso App Review; l'Ad Library API non ha bisogno di nessuno dei due. La Marketing API restituisce spend e risultati esatti per i tuoi annunci; l'Ad Library API restituisce intervalli a bande per gli annunci politici e UE/Regno Unito di altre persone. Se vuoi i tuoi dati di campagna in modo programmatico, vuoi la Marketing API. Questa guida parla dell'altra.

Come ottenere l'accesso all'Ad Library API

L'accesso richiede tre passaggi una tantum. Nessuno è difficile, ma il primo comporta un periodo di attesa, quindi iniziarlo prima di avere bisogno dei dati.

Passo 1: conferma la tua identità

Poiché l'archivio include dati di annunci politici, Meta richiede a ogni utente dell'API di confermare identità e posizione, lo stesso processo che completano gli inserzionisti per pubblicare annunci politici. Vai su facebook.com/ID da loggato e segui le istruzioni. Aspettati di dover caricare un documento d'identità governativo e confermare il tuo luogo di residenza. L'approvazione richiede tipicamente qualche giorno. Questo è per account e una tantum, ma saltarlo è il fallimento di configurazione più comune: il tuo token sarà valido e le tue query verranno comunque rifiutate.

Passo 2: crea un'app su Meta for Developers

Registrati su Meta for Developers se non l'hai già fatto, poi crea una nuova app da My Apps. Il tipo di app più semplice funziona; l'app è solo un contenitore che ti permette di generare token. Non serve aggiungerci prodotti, e l'Ad Library API non richiede App Review, perché stai solo leggendo dati pubblici dell'archivio.

Passo 3: genera un access token

Apri il Graph API Explorer dal menu degli strumenti per sviluppatori, seleziona la tua app, e genera uno user access token. Non servono permessi speciali oltre a quelli predefiniti; ciò che conta è che l'utente dietro il token abbia completato il passo 1.

I token dell'Explorer sono di breve durata, scadono in un'ora o due. Per qualsiasi cosa oltre a un test rapido, scambialo con un long-lived token, che dura circa 60 giorni, usando gli strumenti per i token nella dashboard sviluppatore. Le pipeline programmate hanno bisogno di una routine di rinnovo, perché quando il token scade le tue richieste iniziano a fallire con l'errore 190 finché non ne inserisci uno nuovo.

Per verificare che tutto funzioni, esegui una query di test nell'Explorer:

ads_archive? ad_reached_countries=['US']&ad_type=POLITICAL_AND_ISSUE_ADS&search_terms='election'

Se torna JSON, sei dentro.

Interrogare l'endpoint ads_archive

Ogni richiesta è una HTTP GET verso un unico URL:

https://graph.facebook.com/v25.0/ads_archive

Il segmento di versione segue le release trimestrali della Graph API di Meta (v25.0 a metà 2026). Due cose sono obbligatorie in ogni chiamata: il tuo access_token e ad_reached_countries, un array di codici paese ISO (o ALL) che definisce dove sono stati diffusi gli annunci che vuoi. Ogni query ha bisogno anche di search_terms o search_page_ids; ometti entrambi e l'API rifiuta la chiamata con un errore di parametro invece di restituire tutto. Ricorda la regola dell'ambito: ad_reached_countries=['US'] può far emergere solo annunci politici e di temi sociali, mentre ['GB'] o qualsiasi codice UE fa emergere anche annunci commerciali.

I parametri che contano

L'elenco completo dei parametri si trova nella reference di ads_archive di Meta, ma questi sono quelli con cui si costruiscono le query reali:

Una manciata di altri (delivery_by_region, estimated_audience_size_min e max) sono filtri esclusivi per il politico; altrimenti l'API li ignora o dà errore.

Scegliere i tuoi campi

Per default ottieni un record minimo: id, ad_snapshot_url, orari di inizio e fine diffusione, e page_id. Tutto il resto deve essere richiesto esplicitamente tramite il parametro fields. Quelli che vale la pena conoscere:

• Tutti gli annunci: page_name, ad_creative_bodies, ad_creative_link_titles, ad_creative_link_captions, ad_creative_link_descriptions, publisher_platforms, languages, ad_creation_time
• Solo annunci politici e di temi sociali: spend e impressions (intervalli a bande, da meno di 100 a oltre 1 milione), currency, demographic_distribution, delivery_by_region, estimated_audience_size, bylines
• Annunci diffusi nell'UE e nel Regno Unito: eu_total_reach, total_reach_by_location, age_country_gender_reach_breakdown, target_ages, target_gender, target_locations, e beneficiary_payers (solo UE)

I campi che non si applicano a un dato annuncio sono semplicemente assenti dal suo oggetto JSON, quindi scrivi il tuo codice di parsing in modo difensivo.

Esempio: curl

L'esempio canonico dalla documentazione ufficiale di Meta, ampliato con fields:

curl -G \
 -d "search_terms='california'" \
 -d "ad_type=POLITICAL_AND_ISSUE_ADS" \
 -d "ad_reached_countries=['US']" \
 -d "ad_active_status=ALL" \
 -d "fields=id, page_name, ad_creative_bodies, ad_delivery_start_time, spend, impressions" \
 -d "access_token=<ACCESS_TOKEN>" \
 "https://graph.facebook.com/v25.0/ads_archive"

Esempio: Python con paginazione

I risultati arrivano a pagine, e il lavoro vero consiste nel scorrerle in loop. Questo script estrae ogni annuncio archiviato dalla pagina di un competitor così come diffuso nel Regno Unito:

import requests

TOKEN = "YOUR_LONG_LIVED_TOKEN"
url = "https://graph.facebook.com/v25.0/ads_archive"
params = {
 "access_token": TOKEN,
 "ad_reached_countries": '["GB"]',
 "search_page_ids": '["123456789"]',
 "ad_active_status": "ALL",
 "fields": "id, page_name, ad_creative_bodies,"
 "ad_delivery_start_time, ad_delivery_stop_time,"
 "publisher_platforms, ad_snapshot_url, eu_total_reach",
 "limit": 250,
}

ads = []
while url:
 resp = requests. get(url, params=params, timeout=60)
 payload = resp. json()
 if "error" in payload:
 raise RuntimeError(payload["error"]["message"])
 ads. extend(payload. get("data", []))
 url = payload. get("paging", {}). get("next")
 params = {} # the next URL already carries every parameter

print(f"Collected {len(ads)} ads")

Sostituisci page ID, paese e fields per il tuo caso d'uso. Come codice di riferimento, il proprio Ad Library API Script Repository di Meta su GitHub include una semplice interfaccia a riga di comando ed esempi in Python, anche se punta a versioni più vecchie della Graph API e non viene più aggiornato attivamente.

Rate limit, paginazione ed errori comuni

La paginazione si basa su cursori. Ogni risposta contiene un array data e un oggetto paging con cursori e un URL next; hai raggiunto la fine quando data torna vuoto. La dimensione di pagina predefinita è 25 annunci, e il parametro limit la aumenta. Spingila troppo in alto e scambi problemi di rate limit con problemi di timeout su query pesanti, motivo per cui la maggior parte degli script in produzione si assesta su qualche centinaio di annunci per pagina.

I rate limit su ads_archive sono dinamici e non pubblicati. Scalano per app e per token, e l'uso intenso viene sottoposto a throttling piuttosto che misurato in modo pulito. Tre abitudini ti tengono sotto il tetto: richiedi solo i campi che ti servono, vincola le query con codici paese e search_page_ids invece che parole chiave ampie, e aggiungi un backoff esponenziale ogni volta che vedi l'errore 613. Per i job ricorrenti, raggruppare fino a 10 page ID per chiamata è il guadagno di efficienza più economico disponibile.

Gli errori che incontrerai davvero:

Una particolarità strutturale prima o poi frega tutti: non esiste un endpoint per recuperare un singolo annuncio tramite il suo Library ID. Se hai un ID dal sito web, interroga la pagina dell'inserzionista con search_page_ids e filtra i risultati lato client per l'id corrispondente.

Cosa non ti darà l'API

L'Ad Library API è uno strumento di trasparenza, e Meta ha tracciato i suoi confini deliberatamente. Conoscerli in anticipo ti risparmia di progettare funzionalità che i dati non possono supportare.

• Nessuna metrica di performance. Nessun clic, CTR, conversione o conteggio di engagement, per nessun annuncio, mai. Spend e impressions esistono solo per annunci politici e UE/Regno Unito, e solo come intervalli.
• Nessun file creative. Le risposte includono un ad_snapshot_url che mostra l'annuncio in un browser, ma mai file immagine o video. Il download in blocco di media dalle pagine snapshot non è supportato e si scontra con i termini di servizio di Meta.
• Nessun dettaglio reale di targeting. Non puoi vedere interessi, custom audience o lookalike. Gli annunci UE e Regno Unito espongono solo le selezioni ampie di età, genere e posizione.
• Una memoria commerciale breve. Gli annunci non politici escono dall'archivio un anno dopo la loro ultima impression. Gli annunci politici persistono per sette anni. Se ti serve una storia più lunga, devi raccogliere in continuo e costruire il tuo archivio.

Nessuno di questi è un bug, e nessuna query per quanto ingegnosa li aggira. Quando il divario conta, cambi strumento.

Alternative quando l'API è troppo limitata

Fai combaciare lo strumento con il divario invece di combattere contro l'API ufficiale.

Ti servono annunci commerciali fuori dall'UE e dal Regno Unito. Questo è il caso grosso, e la risposta è fare scraping del sito Ad Library, che mostra annunci commerciali attivi in ogni paese anche se l'API non li serve. Scraper costruiti apposta e API wrapper (Apify actors da circa 0,75 $ per 1.000 annunci, più servizi come SearchApi e ScrapeCreators che vendono gli stessi dati come JSON pulito) gestiscono l'automazione del browser per te. I compromessi sono reali: sei fuori dai termini dell'API ufficiale, gli schemi si rompono quando Meta aggiorna il sito, e prendere quella strada è una decisione di rischio deliberata che spetta all'acquirente, non qualcosa che consigliamo.

Non sei uno sviluppatore, o il tuo team non lo è. La maggior parte dei task di ricerca competitiva che sembrano progetti API sono in realtà problemi di esportazione: qualcuno vuole gli annunci dei competitor o i dati del proprio account in un foglio di calcolo. Gli strumenti di esportazione massiva no-code coprono questo senza token o script, e la nostra guida per esportare i dati degli annunci Facebook ripercorre le opzioni dall'inizio alla fine.

Stai facendo ricerca formale. Accademici e ricercatori qualificati possono richiedere la Meta Content Library e la sua API, la successora di CrowdTangle, che copre post pubblici e contenuti oltre gli annunci con una verifica più rigorosa e garanzie più forti. Per studiare la copertura organica e l'attività coordinata insieme agli annunci, è lo strumento più completo.

Ti servono solo una manciata di inserzionisti, occasionalmente. Salta l'ingegneria. Il sito web più i suoi filtri nativi, controllato settimanalmente, batte il mantenere una pipeline di rinnovo token per dati che potresti leggere in dieci minuti.

Domande frequenti

La Facebook Ad Library API è gratuita? Sì, completamente. Nessun livello di utilizzo, nessun credito. I costi sono indiretti: tempo di verifica dell'identità, ingegneria dei rate limit, e le restrizioni di ambito che potrebbero spingerti verso alternative a pagamento.

Posso vedere tutti gli annunci dei competitor in qualsiasi paese? No. Gli annunci politici e di temi sociali in tutto il mondo, più gli annunci diffusi nell'UE o nel Regno Unito, sono l'intero archivio. Gli annunci commerciali esclusivamente US sono semplicemente assenti.

Posso scaricare immagini e video degli annunci tramite l'API? No. Ottieni un ad_snapshot_url per vedere ogni annuncio in un browser. I file media non appaiono mai nelle risposte, e raccoglierli in blocco dalle pagine snapshot viola i termini di Meta.

Posso cercare un singolo annuncio tramite il suo Library ID? No. Non esiste un endpoint per ID. Interroga la pagina dell'inserzionista con search_page_ids e filtra lato client per l'id che vuoi.

Quanti risultati può restituire una query? 25 per pagina di default, aumentabili tramite il parametro limit, con paginazione a cursore tramite paging.next finché data non torna vuoto. Qualche centinaio per pagina è il tetto affidabile prima che i timeout diventino comuni.

Cosa significa l'errore 613? Hai superato il rate limit. I limiti sono dinamici e non pubblicati, quindi integra un backoff esponenziale, richiedi meno campi, e raggruppa i page ID per restare sotto la soglia.

Mi serve App Review per usare l'Ad Library API? No. Ti serve una conferma di identità su facebook.com/ID, un'app sviluppatore, e uno user access token. App Review si applica solo ai dati privati degli utenti e ai permessi sull'account pubblicitario.

Qual è il rate limit dell'Ad Library API? Meta non ne pubblica uno. Il throttling è dinamico per app e token. Tratta gli errori 613 come il segnale, rallenta quando compaiono, e distribuisci nel tempo le estrazioni programmate invece di lanciarle tutte insieme.

Costruisci tenendo a mente l'ambito

La Facebook Ad Library API è eccellente esattamente in ciò per cui è stata costruita: accesso gratuito, ufficiale e programmatico alla trasparenza degli annunci politici in tutto il mondo e a ogni annuncio che tocca utenti UE e del Regno Unito. Entro quell'ambito è la scelta giusta ogni volta, e la configurazione (conferma di identità, un'app sviluppatore, un long-lived token) richiede un pomeriggio più qualche giorno di attesa per la verifica.

La modalità di fallimento è costruire contro l'archivio che hai immaginato invece dell'archivio che esiste davvero. Quindi decidi in anticipo: la ricerca politica o UE/Regno Unito passa attraverso ads_archive; l'intelligence commerciale su tutti i paesi significa scraper o API di dati di terze parti; i problemi a forma di foglio di calcolo meritano strumenti di esportazione no-code invece di un progetto di ingegneria. Qualunque sia il percorso adatto, il lato dati della ricerca competitiva è ora la metà facile. La metà difficile è quella che è sempre stata: trasformare ciò che impari dagli annunci degli altri nei tuoi test creativi, a un volume che ti insegni davvero qualcosa.