facebook-ad-library/
search

Cerca gli annunci pubblici della Facebook Ad Library per parola chiave e filtri, con inserzionista, testo creativo, media, diffusione e metriche visibili come record normalizzati.

Facebook Ad Library Search API

Ricerca di annunci per parola chiave
Contesto di creatività e diffusione
Dati pubblicitari pubblici
0,5 crediti per risultato
Pronto
Pronto

Inserisci i parametri e invia una richiesta. Qui compariranno lo stato dell’attività e i risultati normalizzati.

README

A cura di SocQ · Aggiornato il

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

ParametriObbligatorioDescrizione
queryObbligatorioParola chiave o frase obbligatoria e non vuota usata per cercare gli annunci pubblici.
results_limitFacoltativoNumero massimo di annunci unici da salvare. Il valore predefinito è 100 e sono accettati interi da 20 a 2.000.
search_typeFacoltativoModalità di corrispondenza delle parole chiave. Il valore predefinito è keyword_unordered; usa keyword_exact_phrase quando l’ordine delle parole deve coincidere.
ad_typeFacoltativoFiltro sulla categoria dell’annuncio. Il valore predefinito è all e può essere limitato a political_and_issue_ads.
countryFacoltativoFiltro per paese. Usa ALL oppure un codice paese di due lettere; i codici inviati in lettere vengono normalizzati in maiuscolo.
statusFacoltativoFiltro sullo stato di diffusione. Il valore predefinito è ACTIVE e supporta ALL, ACTIVE o INACTIVE.
media_typeFacoltativoFiltro sul tipo di media della creatività. Supporta ALL, IMAGE, VIDEO, MEME, IMAGE_AND_MEME o NONE e ha ALL come valore predefinito.
sort_byFacoltativoOrdinamento dei risultati. Il valore predefinito è total_impressions e supporta anche relevancy_monthly_grouped.
start_dateFacoltativoData di inizio facoltativa del periodo di impression nel formato YYYY-MM-DD.
end_dateFacoltativoData 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.

  1. Prepara una query non vuota e scegli i controlli facoltativi di corrispondenza, annuncio, paese, stato, media, ordinamento, date e limite dei risultati.
  2. Invia con POST la richiesta a /v1/facebook-ad-library/search e conserva il task_id restituito.
  3. Interroga /v1/tasks/{task_id} finché l’attività riesce o restituisce un errore.
  4. 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 true

Casi 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.

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.

Esplora altre piattaforme

Combina i dati di Facebook Ad Library con i dati pubblici delle altre piattaforme social supportate.

Facebook Ad Library Search API — FAQ

Facebook Ad Library Search API recupera annunci pubblici da una parola chiave o frase non vuota, più filtri di ricerca facoltativi. Restituisce identità normalizzata dell’annuncio, contesto della pagina dell’inserzionista, testo creativo e media, campi di diffusione e metriche visibili.

query è obbligatorio. La richiesta accetta anche results_limit, sort_by, search_type, ad_type, country, status, media_type, start_date e end_date.

keyword_unordered cerca le parole della query senza richiederne l’ordine originale, mentre keyword_exact_phrase mantiene l’ordine della frase. Il valore predefinito è keyword_unordered.

Un risultato normalizzato può includere identità dell’annuncio e dell’inserzionista, testo creativo, immagini o video, date e stato di diffusione, piattaforme di pubblicazione, paesi, campi di CTA e destinazione, Mi piace della pagina, copertura, contesto di spesa e orario di raccolta. I campi pubblici restano vuoti quando non sono esposti.

Nessun annuncio pubblico può corrispondere alla parola chiave, oppure i filtri selezionati su paese, stato, media, tipo di annuncio o date possono escludere ogni record disponibile. Anche la disponibilità della fonte pubblica può lasciare vuota un’attività completata.

results_limit ha 100 come valore predefinito e accetta interi da 20 a 2.000 come numero massimo di annunci unici da salvare. Dopo il completamento, segui next_cursor finché has_more è true per leggere ogni pagina di risultati salvata dell’attività.

Ogni annuncio normalizzato restituito costa 0,5 crediti SocQ. I risultati vuoti non comportano alcun addebito.