Passer au contenu principal
Recherchez dans la Bibliothèque publicitaire de Meta en JSON via l’API de tâches asynchrones. Envoyez taskType ADS avec platform meta_ad_library, et un mot-clé dans query ou l’ID de la page Facebook d’un annonceur dans pageId. Une recherche coûte 0.5 crédit par tranche de 30 publicités renvoyées. Pour trouver l’ID de page d’un annonceur à partir de son nom, envoyez action advertisers.

Requête

Soumettez la tâche, puis interrogez GET /v1/async/task/{id} ou recevez son webhook. Voir Tâches asynchrones. Une recherche de 30 publicités se termine en général en quelques secondes, et une recherche de 500 publicités en une minute environ.

Paramètres

  • action : search (par défaut), ou advertisers, qui trouve des annonceurs par leur nom.
  • query : un mot-clé. Il trouve les mots du texte d’une publicité dans n’importe quel ordre. Obligatoire sans pageId.
  • pageId : l’ID numérique de la page Facebook d’un annonceur, comme 266556540473351. Il liste les publicités de cet annonceur et, avec query, cherche parmi elles.
  • country : le pays de diffusion, en code pays à deux lettres, ou ALL pour tous les pays. US par défaut.
  • activeStatus : active (par défaut), inactive ou all.
  • limit : de 1 à 500 publicités. 30 par défaut.
  • cursor : le nextCursor d’une réponse précédente, pour lire les publicités suivantes.
  • searchType : keyword_unordered (par défaut) ou keyword_exact_phrase.
  • adType : all (par défaut), political_and_issue_ads, housing_ads, employment_ads ou financial_products_and_services_ads.
  • mediaType : all (par défaut), image, meme, image_and_meme, video ou none.
  • publisherPlatforms : une ou plusieurs valeurs parmi facebook, instagram, audience_network, messenger, whatsapp et threads, en tableau ou en texte séparé par des virgules.
  • contentLanguages : un ou plusieurs codes de langue à deux lettres.
  • startDate, endDate : YYYY-MM-DD. Garde les publicités affichées entre les deux dates.
  • sortBy : impressions_high_to_low (par défaut) ou most_recent. impressions_low_to_high exige adType political_and_issue_ads, les seules publicités que la bibliothèque trie ainsi.
Une valeur que la bibliothèque ne peut pas rechercher est refusée avec 400 VALIDATION_ERROR, et details nomme le champ.

Lire plus de publicités

Une réponse qui laisse des publicités à lire porte nextCursor. Envoyez-le comme cursor avec la même recherche pour recevoir les publicités suivantes, de nouveau jusqu’à limit. Les positions reprennent après la réponse précédente, et nextCursor vaut null quand la bibliothèque n’en a plus.
Un curseur ne sert qu’à la recherche qui l’a renvoyé : une autre valeur de query, pageId, country, activeStatus ou d’un filtre est refusée avec 400 VALIDATION_ERROR, tandis que limit peut changer. Le curseur s’allonge avec les publicités lues avant lui, jusqu’à environ 14 Ko après un millier de publicités ; conservez-le comme texte sans limite de longueur. La bibliothèque liste parfois une publicité deux fois, si bien qu’une publicité peut revenir dans une réponse suivante ; libraryId distingue les doublons.

Trouver un annonceur

action advertisers renvoie les pages Facebook des annonceurs dont le nom correspond à query, comme les suggère la barre de recherche de la bibliothèque. Envoyez le pageId choisi pour rechercher les publicités de cet annonceur.
Chaque annonceur comporte position, pageId, name, category, likeCount, verified (le badge bleu de Meta), country (le pays de la page quand Meta l’indique, comme la page britannique d’une marque mondiale), pageAlias, profileUrl, pictureUrl, instagramUsername, instagramFollowerCount, instagramVerified et libraryUrl, qui ouvre ses publicités dans la Bibliothèque publicitaire. keywords liste les recherches que la bibliothèque suggère pour ce nom. La bibliothèque cherche le nom tel que la page l’écrit : Shokz trouve les pages de Shokz, et 샥즈 n’en trouve aucune. Un nom qu’aucune page ne porte se termine avec advertisers vide. Une recherche d’annonceurs n’accepte que query et country, et coûte 0.5 crédit.

Exemple de réponse

Champs du résultat

  • La réponse reprend platform, action, country, query ou pageId, activeStatus et les filtres reçus.
  • totalCount est le nombre de publicités correspondantes compté par la bibliothèque, qui l’arrondit pour les grandes recherches. returnedCount compte les publicités de ads, hasMore vaut true quand la bibliothèque en a davantage, que nextCursor permet de lire, et libraryUrl ouvre la même recherche dans la Bibliothèque publicitaire.
  • Chaque publicité a position, libraryId, libraryUrl, isActive, startDate et endDate (jours en UTC), platforms, versions (le nombre de publicités qui utilisent ce contenu et ce texte), format (IMAGE, VIDEO, CAROUSEL, DCO, DPA, MULTI_IMAGES et d’autres), body, title, caption, linkUrl, linkDescription, ctaText, ctaType et categories (les catégories de la publicité selon la bibliothèque, comme POLITICAL ou EMPLOYMENT).
  • L’annonceur est pageId, pageName, pageProfileUrl, pageProfilePictureUrl, pageLikeCount et pageCategories. Les publicités sur des sujets sociaux, des élections ou la politique ajoutent byline, qui a payé la publicité, et disclaimerLabel, et un partenariat rémunéré ajoute la page du partenaire dans brandedContent.
  • Les médias sont images (url, resizedUrl), videos (hdUrl, sdUrl, previewImageUrl) et cards, les cartes d’une publicité carrousel ou catalogue, chacune avec ses title, body, linkUrl, caption, linkDescription, ctaText, ctaType, imageUrl, resizedImageUrl et video. Les autres textes, liens, images et vidéos d’une publicité dynamique sont dans extraTexts, extraLinks, extraImages et extraVideos.
  • Les URL des médias sont des liens du CDN de Meta qui expirent au bout de quelques jours. Enregistrez les fichiers dont vous avez besoin.
  • Les publicités catalogue (DPA, DCO) gardent dans leur texte les espaces réservés de la bibliothèque, comme {{product.name}}.
  • spend, currency, impressions et reach n’apparaissent que là où la bibliothèque les publie : publicités sur des sujets sociaux, des élections ou la politique, et publicités diffusées dans l’UE.
  • Une recherche sans publicité correspondante se termine avec ads vide et totalCount à 0.

Prix

Une recherche bloque au démarrage 0.5 crédit par tranche de 30 publicités demandées par limit, et coûte 0.5 crédit par tranche de 30 publicités renvoyées, avec un minimum de 0.5 crédit. La recherche par défaut de 30 publicités coûte 0.5 crédit, et une recherche avec limit 500 bloque 8.5 crédits. Une recherche d’annonceurs coûte 0.5 crédit. Seules les requêtes terminées sont facturées.

Voir aussi