taskType ADS avec l’une de deux plateformes, et action choisit ce qu’il faut lire. Pour choisir entre les bibliothèques publicitaires, voir Bibliothèques publicitaires comparées.
tiktok_ad_librarylit la Bibliothèque publicitaire de TikTok (la Commercial Content Library). Elle liste les publicités diffusées dans 34 régions : les pays de l’UE et de l’EEE, le Royaume-Uni, la Suisse, la Türkiye et le Brésil. Chaque publicité indique son premier et son dernier jour de diffusion et une fourchette d’impressions, etadajoute la page de destination, qui a payé, le ciblage et les impressions par pays, âge et genre. Utilisez-la pour voir toutes les publicités d’un concurrent.tiktok_creative_centerlit les meilleures publicités du TikTok Creative Center. Il liste les publicités les plus performantes d’un pays sur les 7, 30 ou 180 derniers jours, avec leur taux de clics, leurs mentions « J’aime » et leur secteur, pour 28 pays dont les États-Unis, la Corée et le Japon. Utilisez-le pour voir quelles créations fonctionnent sur un marché.
advertisers et ad coûtent 0.5 crédit chacun.
Bibliothèque publicitaire de TikTok
Requête
GET /v1/async/task/{id} ou recevez son webhook. Voir Tâches asynchrones. Une recherche de 300 publicités prend environ une minute.
Analyser les publicités d’un concurrent
Trois requêtes couvrent une analyse de la concurrence :advertisersavec le début du nom du concurrent renvoie les noms exacts et les IDs que connaît la bibliothèque.searchavec ce nom dansadvertiserNameliste les publicités de l’annonceur.sortByles classe par date de publication, date de dernière diffusion ou impressions,activeStatusconserve les publicités en cours ou arrêtées, etsummarycompte les formats et les publicités lancées chaque semaine.adavec lelibraryIdd’une publicité renvoie la page de destination, qui a payé, le ciblage, la taille de l’audience et les impressions par pays, âge et genre.
query à la place de advertiserName : il recherche dans le texte, les hashtags et les noms des annonceurs.
Paramètres
action:search(par défaut),advertisersouad.country: obligatoire sur chaque action. L’un deAT,BE,BG,BR,CH,CY,CZ,DE,DK,EE,ES,FI,FR,GB,GR,HR,HU,IE,IS,IT,LI,LT,LU,LV,MT,NL,NO,PL,PT,RO,SE,SI,SKetTR.ALLet les pays hors de la liste, commeUS,KRetJP, sont rejetés avec400 VALIDATION_ERROR, car la bibliothèque couvre ces régions uniquement.query: un mot-clé. Sursearch, il correspond au texte, aux hashtags et aux annonceurs par ordre de pertinence, et la bibliothèque compte au plus 5,000 publicités. Suradvertisers, c’est le début du nom d’un annonceur et il est obligatoire.searchexigequeryouadvertiserName, mais pas les deux.advertiserName: le nom exact d’un annonceur, commeNIKE Retail B.V.. La bibliothèque compte toutes ses publicités.libraryId: l’ID numérique d’une publicité, comme1879578148398450.adl’exige.activeStatus:all(par défaut),activeouinactive.mediaType:all(par défaut),videoouimage.startDate,endDate:YYYY-MM-DD. Conserve les publicités diffusées entre les deux jours. Par défaut, les 365 derniers jours.sortBy:published_desc(par défaut),published_asc,last_shown_desc,last_shown_asc,impressions_descouimpressions_asc. Il s’applique à une recherche paradvertiserName, et une recherche parquerysuit toujours l’ordre de pertinence.limit: de 1 à 300 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. advertisers lit query et country, et ad lit libraryId et country. 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, country, activeStatus, mediaType, une plage de dates ou un sortBy différents sont rejetés avec 400 VALIDATION_ERROR, tandis que limit peut changer. Dans une recherche par query, que la bibliothèque classe par pertinence, quelques publicités à la limite de deux pages peuvent apparaître deux fois ou manquer ; libraryId permet de distinguer les doublons.
Trouver un annonceur
action advertisers renvoie jusqu’à 20 annonceurs dont le nom commence par query. Envoyez le nom exact comme advertiserName pour rechercher les publicités de cet annonceur.
advertiserId et advertiserName. country, adCount et verified valent null, car les suggestions de la bibliothèque n’en donnent pas davantage. Une recherche d’annonceur coûte 0.5 crédit.
Réponse de recherche
- La réponse reprend
platform,action,country,queryouadvertiserName,activeStatus,mediaTypeetsortBy.totalCountest le compte de la bibliothèque pour les publicités correspondantes, qui s’arrête à 5,000 pour une recherche parquery.returnedCountcompte les publicités dansads,hasMorevauttruelorsque la bibliothèque en a davantage, ce quenextCursorlit, etlibraryUrlouvre la même recherche dans la Bibliothèque publicitaire. - Chaque publicité a
position,libraryId,libraryUrl,advertiserName,title,format(VIDEO,IMAGEouTEXT),images,videos(url,previewUrl),startDate,endDate,activeDays,impressions(min,max),estimatedAudience(la fourchette de la bibliothèque, comme400K-500K) etplatforms(TIKTOK). startDateetendDatesont le premier et le dernier jour où la bibliothèque montre la publicité (jours en UTC).activeDayscompte les jours destartDateàendDate, les deux inclus. La bibliothèque ne donne pas les dépenses.isActivevauttrueoufalselorsqueactiveStatusestactiveouinactive, etnulllorsqu’il estall.advertiserId,payer,linkUrl,landingDomain,utmettargetingvalentnulldans une recherche.adles remplit.summarycompte les publicités de cette réponse :ads,activeAds,advertisers(les 10 qui ont le plus de publicités),formats,platforms,oldestStartDate,newestStartDateetmedianActiveDays, aveclaunchesByWeek(les publicités lancées chaque semaine ISO) etlongestRunning(les 5 publicités avec le plus deactiveDays). Il ne contient nilandingDomainsniutmCampaigns, car une recherche ne porte aucune page de destination.- Les URL d’images et de vidéos sont signées et expirent environ 5 à 6 heures après la lecture. Enregistrez les fichiers dont vous avez besoin.
- Une recherche sans publicité correspondante se termine avec
adsvide et unsummaryde0publicité.
Ce que la bibliothèque conserve
La bibliothèque montre les publicités diffusées dans ses 34 régions et les conserve environ 13 mois. Elle donne le premier et le dernier jour de diffusion et une fourchette d’impressions pour chaque publicité. Elle ne publie pas les dépenses.Ouvrir une publicité
action ad ouvre la publicité avec le libraryId et le country que vous envoyez.
adcontient les champs d’une publicité de recherche, pluslinkUrl,landingDomain,payer(qui a payé la publicité),category,objective,ctaText,advertiserId,reachedCountriesettargeting.targetingcontientbyCountry(lesagesetgendersde chaque pays),provinces,cities,languages,interests,targetAudienceSize(la fourchette de la bibliothèque, comme15.5M-18.9M),customAudience,excludesAudience,highSpendingPower,operatingSystems,deviceModels,videoInteractionsetcreatorInteractions. Un élément que la bibliothèque ne publie pas pour la publicité vautnullou est vide.advertisercontientadvertiserId,advertiserName,payer,registryCountryet leaccountTikTok derrière les publicités (username,displayName,verified,followers,accountType,profileUrl,avatarUrl).transparencycontienttotalImpressionsetbyCountry: lesimpressionsde chaque pays et leursbreakdownsparageetgender.- Un
libraryIdpour lequel la bibliothèque n’a aucune publicité échoue avecPAGE_UNAVAILABLE.
TikTok Creative Center
Le Creative Center liste les publicités les plus performantes d’un pays, celles que TikTok sélectionne pour les 7, 30 ou 180 derniers jours. C’est un échantillon classé, et non l’ensemble des publicités d’un annonceur : le nom de l’annonceur est souvent vide, et la bibliothèque ne donne ni dates, ni dépenses, ni impressions. Elle donne le taux de clics, les mentions « J’aime », le niveau de coût, le secteur et les objectifs de chaque publicité. Utilisez-le pour trouver les accroches, formats et produits qui fonctionnent sur un marché.Requête
Paramètres
action:search(par défaut) ouad.advertisersest rejeté avec400 VALIDATION_ERROR, car le Creative Center n’a pas de recherche d’annonceur.country: obligatoire sursearch. L’un deAE,AR,AU,BR,CA,CO,DE,ES,FR,GB,ID,IT,JP,KR,MX,MY,NL,PH,PK,RO,SA,SE,SG,TH,TR,US,VNetZA.ALLest rejeté.query: un mot-clé.period:7,30(par défaut) ou180jours.industry: un ID de secteur, comme21103000000(Hardware & Electrical), tel que le nomme leindustry.idd’une publicité.objective:traffic,app_installs,conversions,video_views,reach,lead_generation,product_salesouapp_promotion.adLanguage: un code de langue :en,es,ar,vi,th,de,id,pt,fr,ms,nl,ja,it,ro,zh-Hantouko.adFormat:spark(publicités qui boostent la publication d’un créateur) ounon_spark.sortBy:for_you(par défaut),impression,ctr,play_2s_rate,play_6s_rate,cvroulike.limit: de 1 à 200 publicités. Par défaut 30.cursor: lenextCursord’une réponse précédente.libraryId: l’ID numérique d’une publicité du classement.adl’exige.
search lit tous les champs ci-dessus sauf libraryId, et ad lit uniquement libraryId. Le Creative Center liste au plus environ 400 à 500 publicités pour un pays, une période et un ensemble de filtres (totalCount).
Réponse de recherche
- La réponse reprend
platform,action,country,period,sortByet les filtres reçus.totalCountest le nombre de publicités du classement pour cette combinaison. - Chaque publicité a
position,libraryId,title,advertiserName(souventnull),format,ctrPercent(le taux de clics en pourcentage),costLevel,likes,industry(id,name),objectives,durationSeconds,width,height,voiceOver,images,videosetvideoUrls(le fichier vidéo par résolution, comme360pet1080p). - Le Creative Center ne donne ni
startDate, niendDate, niimpressions, nilibraryUrl, qui valent doncnull, etsummaryne compte que les formats, les annonceurs et les plateformes. - Les URL de vidéos et d’images sont signées et expirent environ 5 à 6 heures après la lecture.
Ouvrir une publicité
action ad ouvre une publicité du classement par libraryId et ajoute linkUrl, landingDomain, reachedCountries, comments, shares et source (où la publicité a été créée, comme TikTok Ads Manager).
libraryId pour lequel le Creative Center n’a aucune publicité échoue avec PAGE_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 300 sur la Bibliothèque publicitaire réserve 5 crédits. advertisers et ad coûtent 0.5 crédit chacun. Seules les requêtes terminées sont facturées.