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
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), ouadvertisers, 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 sanspageId.pageId: l’ID numérique de la page Facebook d’un annonceur, comme266556540473351. Il liste les publicités de cet annonceur et, avecquery, cherche parmi elles.country: le pays de diffusion, en code pays à deux lettres, ouALLpour tous les pays.USpar défaut.activeStatus:active(par défaut),inactiveouall.limit: de 1 à 500 publicités. 30 par défaut.cursor: lenextCursord’une réponse précédente, pour lire les publicités suivantes.searchType:keyword_unordered(par défaut) oukeyword_exact_phrase.adType:all(par défaut),political_and_issue_ads,housing_ads,employment_adsoufinancial_products_and_services_ads.mediaType:all(par défaut),image,meme,image_and_meme,videoounone.publisherPlatforms: une ou plusieurs valeurs parmifacebook,instagram,audience_network,messenger,whatsappetthreads, 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) oumost_recent.impressions_low_to_highexigeadTypepolitical_and_issue_ads, les seules publicités que la bibliothèque trie ainsi.
400 VALIDATION_ERROR, et details nomme le champ.
Lire plus de publicités
Une réponse qui laisse des publicités à lire portenextCursor. 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.
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.
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,queryoupageId,activeStatuset les filtres reçus. totalCountest le nombre de publicités correspondantes compté par la bibliothèque, qui l’arrondit pour les grandes recherches.returnedCountcompte les publicités deads,hasMorevauttruequand la bibliothèque en a davantage, quenextCursorpermet de lire, etlibraryUrlouvre la même recherche dans la Bibliothèque publicitaire.- Chaque publicité a
position,libraryId,libraryUrl,isActive,startDateetendDate(jours en UTC),platforms,versions(le nombre de publicités qui utilisent ce contenu et ce texte),format(IMAGE,VIDEO,CAROUSEL,DCO,DPA,MULTI_IMAGESet d’autres),body,title,caption,linkUrl,linkDescription,ctaText,ctaTypeetcategories(les catégories de la publicité selon la bibliothèque, commePOLITICALouEMPLOYMENT). - L’annonceur est
pageId,pageName,pageProfileUrl,pageProfilePictureUrl,pageLikeCountetpageCategories. Les publicités sur des sujets sociaux, des élections ou la politique ajoutentbyline, qui a payé la publicité, etdisclaimerLabel, et un partenariat rémunéré ajoute la page du partenaire dansbrandedContent. - Les médias sont
images(url,resizedUrl),videos(hdUrl,sdUrl,previewImageUrl) etcards, les cartes d’une publicité carrousel ou catalogue, chacune avec sestitle,body,linkUrl,caption,linkDescription,ctaText,ctaType,imageUrl,resizedImageUrletvideo. Les autres textes, liens, images et vidéos d’une publicité dynamique sont dansextraTexts,extraLinks,extraImagesetextraVideos. - 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,impressionsetreachn’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
adsvide ettotalCountà0.
Prix
Une recherche bloque au démarrage 0.5 crédit par tranche de 30 publicités demandées parlimit, 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.