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ètres | Obligatoire | Description |
|---|---|---|
query | Obligatoire | Mot-clé ou expression obligatoire et non vide utilisé pour rechercher des publicités publiques. |
results_limit | Facultatif | Nombre maximal de publicités uniques à enregistrer. Vaut 100 par défaut et accepte des entiers de 20 à 2 000. |
search_type | Facultatif | Mode 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_type | Facultatif | Filtre sur la catégorie de publicité. Vaut all par défaut et peut être restreint à political_and_issue_ads. |
country | Facultatif | Filtre par pays. Utilisez ALL ou un code pays à deux lettres ; les codes envoyés en lettres sont normalisés en majuscules. |
status | Facultatif | Filtre sur le statut de diffusion. Vaut ACTIVE par défaut et prend en charge ALL, ACTIVE ou INACTIVE. |
media_type | Facultatif | Filtre 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_by | Facultatif | Ordre des résultats. Vaut total_impressions par défaut et prend aussi en charge relevancy_monthly_grouped. |
start_date | Facultatif | Date de début facultative de la période d’impressions, au format YYYY-MM-DD. |
end_date | Facultatif | Date 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.
- 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.
- Envoyez la requête en POST à /v1/facebook-ad-library/search et conservez le task_id renvoyé.
- Interrogez /v1/tasks/{task_id} jusqu’à ce que la tâche réussisse ou renvoie un échec.
- 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 trueCas 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.
API associées
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.