Facebook Ad Library Search
I risultati di Facebook Ad Library Search sono annunci pubblici corrispondenti a una parola chiave, con identità della pagina dell’inserzionista, testo creativo e media, date di diffusione, piattaforme di pubblicazione, paesi e metriche visibili. Questi record supportano la scoperta di creatività, la ricerca sugli inserzionisti, il monitoraggio degli annunci attivi e il confronto tra query ripetibili.
Funzionalità della Facebook Ad Library Search API
- Corrispondenza per parola chiave e fraseCerca con una query non vuota e scegli tra corrispondenza non ordinata delle parole chiave e corrispondenza esatta della frase, per controllare quali annunci pubblici risultano idonei.
- Filtri di ricerca e ordinamentoRestringi i risultati per tipo di annuncio, paese, stato di diffusione, tipo di media, intervallo di date e ordinamento supportato per impression o pertinenza.
- Record normalizzati di annunci e inserzionistiRestituisce in un record coerente identità dell’archivio dell’annuncio, URL pubblico di origine, contesto della pagina dell’inserzionista, titolo creativo, testo e orario di raccolta.
- Contesto di creatività, diffusione e dati pubbliciMantiene immagini o video disponibili, orari di inizio e di fine, stato attivo, piattaforme di pubblicazione, paesi, dettagli della CTA, destinazioni e metriche visibili.
- Raccolta limitata e deduplicataRichiedi da 20 a 2.000 risultati, mentre gli ID dell’archivio o gli URL pubblici degli annunci duplicati vengono salvati una sola volta tra le pagine di risultati disponibili.
Parametri della Facebook Ad Library Search API
| Parametri | Obbligatorio | Descrizione |
|---|---|---|
query | Obbligatorio | Parola chiave o frase obbligatoria e non vuota usata per cercare gli annunci pubblici. |
results_limit | Facoltativo | Numero massimo di annunci unici da salvare. Il valore predefinito è 100 e sono accettati interi da 20 a 2.000. |
search_type | Facoltativo | Modalità di corrispondenza delle parole chiave. Il valore predefinito è keyword_unordered; usa keyword_exact_phrase quando l’ordine delle parole deve coincidere. |
ad_type | Facoltativo | Filtro sulla categoria dell’annuncio. Il valore predefinito è all e può essere limitato a political_and_issue_ads. |
country | Facoltativo | Filtro per paese. Usa ALL oppure un codice paese di due lettere; i codici inviati in lettere vengono normalizzati in maiuscolo. |
status | Facoltativo | Filtro sullo stato di diffusione. Il valore predefinito è ACTIVE e supporta ALL, ACTIVE o INACTIVE. |
media_type | Facoltativo | Filtro sul tipo di media della creatività. Supporta ALL, IMAGE, VIDEO, MEME, IMAGE_AND_MEME o NONE e ha ALL come valore predefinito. |
sort_by | Facoltativo | Ordinamento dei risultati. Il valore predefinito è total_impressions e supporta anche relevancy_monthly_grouped. |
start_date | Facoltativo | Data di inizio facoltativa del periodo di impression nel formato YYYY-MM-DD. |
end_date | Facoltativo | Data di fine facoltativa del periodo di impression nel formato YYYY-MM-DD; non può precedere start_date. |
Come usare la Facebook Ad Library Search API
Invia una parola chiave con i filtri che definiscono il tuo campione di annunci, poi leggi tutti i record normalizzati dall’attività asincrona completata.
- Prepara una query non vuota e scegli i controlli facoltativi di corrispondenza, annuncio, paese, stato, media, ordinamento, date e limite dei risultati.
- Invia con POST la richiesta a /v1/facebook-ad-library/search e conserva il task_id restituito.
- Interroga /v1/tasks/{task_id} finché l’attività riesce o restituisce un errore.
- Leggi data.results.items, poi segui next_cursor finché has_more resta true.
curl -X POST "https://api.socq.ai/v1/facebook-ad-library/search" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query":"running shoes","results_limit":100,"country":"US","status":"ACTIVE","media_type":"VIDEO","search_type":"keyword_unordered"}'
# Poll GET /v1/tasks/{task_id}
# Read data.results.items and follow next_cursor while has_more is trueCasi d’uso della Facebook Ad Library Search API
- Scoperta di annunci guidata dalle parole chiave: Usa la query inviata, gli ID degli annunci, il testo creativo, i nomi degli inserzionisti e gli URL pubblici per assemblare un insieme tracciabile di annunci pubblici corrispondenti.
- Confronto di creatività e formati: Confronta titoli creativi, testi, immagini, video, formati di visualizzazione, valori della CTA, destinazioni e piattaforme di pubblicazione tra i record corrispondenti.
- Monitoraggio degli annunci attivi: Ripeti una query definita e confronta ID degli annunci, stato attivo, orari di inizio e di fine, piattaforme di pubblicazione e orari di raccolta tra le osservazioni.
- Ricerca di candidati tra gli inserzionisti: Usa ID delle pagine inserzioniste, nomi, alias, URL, Mi piace visibili della pagina e creatività corrispondente per individuare le pagine su cui approfondire la ricerca.
Consigli degli esperti per la Facebook Ad Library Search API
- Usa keyword_exact_phrase quando l’ordine delle parole ha un significato; usa keyword_unordered quando gli annunci possono variare l’ordine della frase.
- Applica i filtri su paese, stato, media, tipo di annuncio e date prima di aumentare results_limit, così il campione salvato resta mirato.
- Considera results_limit come il tetto della raccolta, poi segui i cursori dei risultati dell’attività finché has_more è false per leggere ogni record salvato.
- Deduplica le esecuzioni ripetute per ID dell’archivio dell’annuncio o URL pubblico dell’annuncio, conservando extra.search_query e collected_at come contesto dell’osservazione.
- Tratta copertura, spesa, Mi piace della pagina, date di fine, media, CTA o valori dei paesi mancanti come dati pubblici non disponibili e non come zero.
API correlate
Oltre alla Facebook Ad Library Search API, usa queste API quando ti serve un altro tipo di dati pubblici di Facebook Ad Library.
- Facebook Ad Library Company Search API — Trova le Pagine inserzioniste candidate per nome di azienda o Pagina, con ID della Pagina, classificazioni, immagini, pubblico visibile e segnali di Instagram collegati.
- Facebook Ad Library Company Ads API — Raccoglie gli annunci pubblici di una Pagina inserzionista tramite il suo ID con creatività, diffusione, mercato, media, CTA e segnali visibili.
- Facebook Ad Library Ad API — Raccoglie un annuncio pubblico della Ad Library dal suo URL con creatività, inserzionista, media, diffusione, CTA e segnali visibili.