taskType ADS avec platform linkedin_ad_library, et action choisit ce qu’il faut lire. Pour choisir entre les bibliothèques publicitaires, voir Bibliothèques publicitaires comparées.
search(par défaut) liste les publicités par un mot-clé dansquery, par le nom d’un annonceur dansadvertiserName, par qui a payé danspayer, ou par une combinaison. Chaque publicité indique son annonceur, son format, son titre, son texte et ses médias, et la réponse se termine par unsummarydes publicités renvoyées.adouvre une publicité : l’annonceur, qui a payé, la page de destination et, là où la bibliothèque les publie, les dates de diffusion, les impressions, les pays touchés et son ciblage.
action advertisers est rejetée avec 400 VALIDATION_ERROR. Trouvez un concurrent avec advertiserName dans une recherche.
Une recherche coûte 0.5 crédit pour 30 publicités renvoyées. ad coûte 0.5 crédit.
Requête
GET /v1/async/task/{id} ou recevez son webhook. Voir Tâches asynchrones. La bibliothèque limite sa vitesse de lecture, donc une recherche de 120 publicités prend environ une demi-minute.
Analyser les publicités d’un concurrent
Trois requêtes couvrent une analyse de la concurrence :searchavec le nom du concurrent dansadvertiserNameliste ses publicités.advertiserNamecorrespond à une partie d’un nom, donc vérifiezadvertiserNamesur chaque publicité. Ajoutezquerypour restreindre les publicités à un sujet, etsortByoldestpour commencer par les plus anciennes.adavec lelibraryIdd’une publicité renvoie qui a payé, la page de destination et, pour les publicités diffusées dans l’UE, les dates de diffusion, les impressions et le ciblage.searchavecpayerliste les publicités payées par une agence ou une entreprise, quelle que soit la page qui les diffuse.
Paramètres
action:search(par défaut) ouad.query: un mot-clé dans le texte de la publicité.searchexigequery,advertiserNameoupayer.advertiserName: un nom, recherché comme partie du nom de l’annonceur, commesamsung.payer: le nom de celui qui a payé la publicité, recherché comme partie du nom, commeStarcom.libraryId: l’ID numérique d’une publicité, comme1638962914.adl’exige.country: où les publicités ont été diffusées, sous forme de code pays à deux lettres, ouALLpour tous les pays (par défaut).startDate,endDate:YYYY-MM-DD, envoyés ensemble, dans la dernière année. Conserve les publicités diffusées entre les deux jours.sortBy:newest(par défaut) ouoldest.limit: de 1 à 120 publicités. Par défaut 30.cursor: lenextCursord’une réponse précédente, pour lire les publicités suivantes.
search lit tous les champs ci-dessus sauf libraryId, et ad lit uniquement libraryId. Un filtre de la Bibliothèque publicitaire de Meta (pageId, pageIds, activeStatus, searchType, adType, mediaType, publisherPlatforms ou contentLanguages), une valeur que la bibliothèque ne peut pas rechercher ou un champ que l’action ne lit pas est rejeté avec 400 VALIDATION_ERROR, et details nomme le champ.
Lire plus de publicités
Une réponse qui a encore des publicités à lire contientnextCursor. Envoyez-le comme cursor avec la même recherche pour recevoir les publicités suivantes, là encore jusqu’à limit. nextCursor vaut null lorsque la bibliothèque n’en a plus. Un curseur ne fonctionne qu’avec la recherche qui l’a renvoyé : un query, advertiserName, payer, country, une plage de dates ou un sortBy différents sont rejetés avec 400 VALIDATION_ERROR, tandis que limit peut changer.
Réponse de recherche
- La réponse reprend
platform,action,country,query,advertiserName,payer,sortByet les dates reçues.returnedCountcompte les publicités dansads,hasMorevauttruelorsque la bibliothèque en a davantage, ce quenextCursorlit, etlibraryUrlouvre la même recherche dans la Bibliothèque publicitaire.totalCountvautnull, car la bibliothèque ne donne aucun compte. - Chaque publicité est une carte :
position,libraryId,libraryUrl,advertiserName,advertiserLogoUrl,creativeType(commeSPONSORED_STATUS_UPDATEouSPONSORED_VIDEO),format,title,body,imagesetvideos(l’affiche de la vidéo danspreviewUrl), etplatforms(LINKEDIN).formatvautIMAGE,VIDEO,CAROUSEL,DOCUMENT,ARTICLE,MESSAGE,JOB,SPOTLIGHTouFOLLOW_COMPANY. - Les publicités de message et les publicités Thought Leader comportent
member, l’expéditeur du message ou le membre dont la publication est promue, avecnameeturl;adle renvoie sous la même forme. Sur les autres publicités,membervautnull. - Une carte contient les 120 premiers caractères du texte, et
bodyTruncatedvauttruelorsque le texte est plus long.adrenvoie le texte complet. advertiserId,payer,startDate,endDate,activeDays,linkUrl,landingDomain,impressions,targeting,ctaTextetutmvalentnullsur une carte.adles remplit lorsque la bibliothèque les a.isActivevautnull, car la bibliothèque n’indique pas si une publicité est toujours diffusée.summarycompte les publicités de cette réponse :ads,advertisers(les 10 qui ont le plus de publicités :advertiserName,ads),formatsetplatforms. Ses champs de date (oldestStartDate,newestStartDate,medianActiveDays,launchesByWeeketlongestRunning) restent vides ou valentnull, car les cartes ne portent aucune date.- Une recherche sans publicité correspondante se termine avec
adsvide et unsummaryde0publicité.
Ce que la bibliothèque conserve
- La création, l’annonceur et le payeur de chaque publicité sont disponibles pour tous les pays.
- Les dates de diffusion, la fourchette d’impressions, la part des impressions par pays et le ciblage ne sont disponibles que pour les publicités diffusées dans l’UE.
- La bibliothèque conserve les publicités environ 12 mois, et son filtre de dates n’accepte que la dernière année.
Ouvrir une publicité
action ad ouvre la publicité avec le libraryId que vous envoyez, issu d’une recherche ou de l’adresse de la Bibliothèque publicitaire /ad-library/detail/<libraryId>.
adcontient les champs d’une carte de recherche avec le texte complet, plusadvertiserId,advertiserUrl,advertiserType(companyouperson),payer(qui a payé la publicité),linkUrl,landingDomain,ctaText,startDate,endDate,activeDays,impressions,targetingetreachedCountries.impressionsest la fourchette que publie la bibliothèque (min,max).targetingliste les langues et les lieux que l’annonceur a inclus ou exclus (language,location) et les paramètres de ciblage (parameters:parameter,targeted,excluded). Les dates,impressions,targetingetreachedCountriesvalentnullpour une publicité qui n’a pas été diffusée dans l’UE, comme la publicité Adobe1698237666. Le payeur et l’annonceur figurent pour toutes les publicités.videosliste chaque vidéo avecurl(le fichier au débit le plus élevé),files(chaque mp4 :url,type,bitrate) etpreviewUrl. Une publicité en carrousel ajoutecards(title,imageUrl) et une publicité de type document ajoutedocument(son titre, son nombre de pages et les couvertures des pages).advertiserest la page derrière la publicité :advertiserId,advertiserName,url,typeetlogoUrl.transparencyvautnullpour une publicité non diffusée dans l’UE. Pour une publicité diffusée dans l’UE, il contientimpressions,impressionsText(le texte de la bibliothèque, comme50k-100k) etreachByCountry, la part des impressions dans chaque pays (country,countryCode,share,shareText), y compris hors de l’UE.variantsliste les autres versions de la publicité lorsque la bibliothèque en montre plus d’une, et vautnullsinon.- Les URL des médias des créations restent ouvertes pendant des années. Les URL des cartes d’un carrousel expirent après environ une semaine, et les logos des annonceurs après environ deux semaines et demie. Enregistrez les fichiers dont vous avez besoin.
- Un
libraryIdpour lequel la bibliothèque n’a aucune publicité échoue avecPAGE_UNAVAILABLE.
Tarif
Une recherche réserve 0.5 crédit pour 30 publicités que demande sonlimit, et facture 0.5 crédit pour 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 120 réserve 2 crédits. ad coûte 0.5 crédit. Seules les requêtes terminées sont facturées.