facebook-ad-library/
search

Recherchez des publicités publiques de la Facebook Ad Library par mot-clé et filtres, et obtenez annonceur, texte de la création, médias, diffusion et métriques visibles sous forme d’enregistrements normalisés.

Facebook Ad Library Search API

Recherche de publicités par mot-clé
Création et contexte de diffusion
Données publicitaires publiques
0,5 crédit par résultat
Prêt
Prêt

Saisissez des paramètres et envoyez une requête. L’état de la tâche et les résultats normalisés s’afficheront ici.

README

Par SocQ · Mis à jour le

Facebook Ad Library Search

Les résultats de Facebook Ad Library Search sont des publicités publiques correspondant à un mot-clé, avec l’identité de la Page de l’annonceur, le texte et les médias de la création, les dates de diffusion, les plateformes de diffusion, les pays et des métriques visibles. Ces enregistrements servent à découvrir des créations, à étudier des annonceurs, à surveiller les publicités actives et à comparer des requêtes répétables.

Fonctionnalités de la Facebook Ad Library Search API

  • Correspondance par mot-clé et par expressionLancez la recherche avec une requête non vide et choisissez entre une correspondance de mots-clés sans ordre ou une correspondance d’expression exacte pour déterminer quelles publicités publiques sont retenues.
  • Filtres et tri de rechercheAffinez les résultats par type de publicité, pays, statut de diffusion, type de média, période et tri pris en charge par impressions ou par pertinence.
  • Publicités et annonceurs normalisésRenvoie, dans un enregistrement homogène, l’identité d’archive de la publicité, l’URL source publique, le contexte de la Page de l’annonceur, le titre de la création, le texte principal et l’heure de collecte.
  • Création, diffusion et contexte publicConserve les images ou vidéos disponibles, les dates de début et de fin, l’état actif, les plateformes de diffusion, les pays, les détails du CTA, les destinations et les métriques visibles.
  • Collecte bornée et dédoublonnéeDemandez de 20 à 2 000 résultats ; les ID d’archive ou URL de publicités en double ne sont enregistrés qu’une fois sur l’ensemble des pages de résultats disponibles.

Paramètres de la Facebook Ad Library Search API

ParamètresObligatoireDescription
queryObligatoireMot-clé ou expression obligatoire et non vide utilisé pour rechercher des publicités publiques.
results_limitFacultatifNombre maximal de publicités uniques à enregistrer. Vaut 100 par défaut et accepte des entiers de 20 à 2 000.
search_typeFacultatifMode de correspondance des mots-clés. Vaut keyword_unordered par défaut ; utilisez keyword_exact_phrase lorsque l’ordre des mots doit être respecté.
ad_typeFacultatifFiltre sur la catégorie de publicité. Vaut all par défaut et peut être restreint à political_and_issue_ads.
countryFacultatifFiltre par pays. Utilisez ALL ou un code pays à deux lettres ; les codes envoyés en lettres sont normalisés en majuscules.
statusFacultatifFiltre sur le statut de diffusion. Vaut ACTIVE par défaut et prend en charge ALL, ACTIVE ou INACTIVE.
media_typeFacultatifFiltre sur le média de la création. Prend en charge ALL, IMAGE, VIDEO, MEME, IMAGE_AND_MEME ou NONE et vaut ALL par défaut.
sort_byFacultatifOrdre des résultats. Vaut total_impressions par défaut et prend aussi en charge relevancy_monthly_grouped.
start_dateFacultatifDate de début facultative de la période d’impressions, au format YYYY-MM-DD.
end_dateFacultatifDate de fin facultative de la période d’impressions, au format YYYY-MM-DD ; elle ne peut pas précéder start_date.

Comment utiliser la Facebook Ad Library Search API

Envoyez un mot-clé avec les filtres qui définissent votre échantillon de publicités, puis lisez chaque enregistrement normalisé de la tâche asynchrone terminée.

  1. Préparez une requête non vide et choisissez, si besoin, les contrôles de correspondance, de publicité, de pays, de statut, de média, de tri, de période et de limite de résultats.
  2. Envoyez la requête en POST à /v1/facebook-ad-library/search et conservez le task_id renvoyé.
  3. Interrogez /v1/tasks/{task_id} jusqu’à ce que la tâche réussisse ou renvoie un échec.
  4. Lisez data.results.items, puis suivez next_cursor tant que has_more reste à 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

Cas d’usage de la Facebook Ad Library Search API

  • Découverte de publicités par mot-clé : Servez-vous de la requête envoyée, des ID de publicité, des textes de création, des noms d’annonceurs et des URL publiques pour constituer un ensemble traçable de publicités publiques correspondantes.
  • Comparaison des créations et des formats : Comparez titres de création, textes principaux, images, vidéos, formats d’affichage, valeurs de CTA, destinations et plateformes de diffusion entre les enregistrements trouvés.
  • Surveillance des publicités actives : Répétez une requête définie et comparez ID de publicité, état actif, dates de début et de fin, plateformes de diffusion et heures de collecte d’une observation à l’autre.
  • Recherche d’annonceurs candidats : Utilisez les ID de Page d’annonceur, noms, alias, URL, mentions J’aime visibles de la Page et la création correspondante pour repérer des Pages à approfondir.

Conseils d’expert pour la Facebook Ad Library Search API

  • Utilisez keyword_exact_phrase lorsque l’ordre des mots a un sens ; utilisez keyword_unordered lorsque les publicités peuvent varier l’ordre de l’expression.
  • Appliquez les filtres de pays, de statut, de média, de type de publicité et de période avant d’augmenter results_limit, afin que l’échantillon enregistré reste ciblé.
  • Considérez results_limit comme le plafond de collecte, puis suivez les curseurs de résultats de la tâche jusqu’à ce que has_more passe à false pour lire chaque enregistrement stocké.
  • Dédoublonnez les exécutions répétées par ID d’archive de la publicité ou URL publique, tout en conservant extra.search_query et collected_at pour le contexte d’observation.
  • Considérez la portée, les dépenses, les mentions J’aime de la Page, les dates de fin, les médias, le CTA ou les valeurs de pays manquants comme des données publiques indisponibles, et non comme des zéros.

En complément de la Facebook Ad Library Search API, utilisez ces API lorsque vous avez besoin d’un autre type de données publiques Facebook Ad Library.

  • Facebook Ad Library Company Search API — Trouvez des Pages d’annonceurs par nom d’entreprise ou de Page avec ID de Page, classifications, images, audience visible et signaux Instagram associés.
  • Facebook Ad Library Company Ads API — Collectez les publicités publiques d’une Page d’annonceur à partir de son ID avec création publicitaire, diffusion, marché, médias, CTA et signaux visibles.
  • Facebook Ad Library Ad API — Collectez une publicité publique de l’Ad Library à partir de son URL avec création publicitaire, annonceur, médias, diffusion, CTA et signaux visibles.

Explorer d’autres plateformes

Combinez les données Facebook Ad Library avec les données publiques d’autres plateformes sociales prises en charge.

Facebook Ad Library Search API — FAQ

Facebook Ad Library Search API récupère des publicités publiques à partir d’un mot-clé ou d’une expression non vide, avec des filtres de recherche facultatifs. Elle renvoie l’identité normalisée de la publicité, le contexte de la Page de l’annonceur, le texte et les médias de la création, les champs de diffusion et les métriques visibles.

query est obligatoire. La requête accepte aussi results_limit, sort_by, search_type, ad_type, country, status, media_type, start_date et end_date.

keyword_unordered fait correspondre les mots de query sans exiger leur ordre d’origine, tandis que keyword_exact_phrase conserve l’ordre de l’expression. La valeur par défaut est keyword_unordered.

Un résultat normalisé peut comprendre l’identité de la publicité et de l’annonceur, le texte de la création, des images ou vidéos, les dates et l’état de diffusion, les plateformes de diffusion, les pays, les champs de CTA et de destination, les mentions J’aime de la Page, la portée, le contexte de dépenses et l’heure de collecte. Les champs publics restent vides lorsqu’ils ne sont pas exposés.

Aucune publicité publique ne correspond peut-être au mot-clé, ou les filtres de pays, de statut, de média, de type de publicité ou de période choisis excluent tous les enregistrements disponibles. La disponibilité de la source publique peut aussi laisser une tâche terminée sans résultat.

results_limit vaut 100 par défaut et accepte des entiers de 20 à 2 000 comme nombre maximal de publicités uniques à enregistrer. Une fois la tâche terminée, suivez next_cursor tant que has_more vaut true pour lire chaque page de résultats stockée.

Chaque publicité normalisée renvoyée coûte 0,5 crédit SocQ. Les résultats vides n’entraînent aucun frais de résultat.