Passer au contenu principal
Lisez les sources publicitaires de TikTok en JSON via l’API asynchrone de tâches. ADS est un moteur à part entière : envoyez 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_library lit 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, et ad ajoute 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_center lit 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é.
Une recherche coûte 0.5 crédit pour 30 publicités renvoyées sur les deux plateformes. advertisers et ad coûtent 0.5 crédit chacun.

Bibliothèque publicitaire de TikTok

Requête

Soumettez la tâche, puis interrogez 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 :
  1. advertisers avec le début du nom du concurrent renvoie les noms exacts et les IDs que connaît la bibliothèque.
  2. search avec ce nom dans advertiserName liste les publicités de l’annonceur. sortBy les classe par date de publication, date de dernière diffusion ou impressions, activeStatus conserve les publicités en cours ou arrêtées, et summary compte les formats et les publicités lancées chaque semaine.
  3. ad avec le libraryId d’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.
Pour trouver des publicités d’après ce qu’elles disent, utilisez query à la place de advertiserName : il recherche dans le texte, les hashtags et les noms des annonceurs.

Paramètres

  • action : search (par défaut), advertisers ou ad.
  • country : obligatoire sur chaque action. L’un de AT, 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, SK et TR. ALL et les pays hors de la liste, comme US, KR et JP, sont rejetés avec 400 VALIDATION_ERROR, car la bibliothèque couvre ces régions uniquement.
  • query : un mot-clé. Sur search, il correspond au texte, aux hashtags et aux annonceurs par ordre de pertinence, et la bibliothèque compte au plus 5,000 publicités. Sur advertisers, c’est le début du nom d’un annonceur et il est obligatoire. search exige query ou advertiserName, mais pas les deux.
  • advertiserName : le nom exact d’un annonceur, comme NIKE Retail B.V.. La bibliothèque compte toutes ses publicités.
  • libraryId : l’ID numérique d’une publicité, comme 1879578148398450. ad l’exige.
  • activeStatus : all (par défaut), active ou inactive.
  • mediaType : all (par défaut), video ou image.
  • 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_desc ou impressions_asc. Il s’applique à une recherche par advertiserName, et une recherche par query suit toujours l’ordre de pertinence.
  • limit : de 1 à 300 publicités. Par défaut 30.
  • cursor : le nextCursor d’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 contient nextCursor. 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.
Chaque annonceur a 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, query ou advertiserName, activeStatus, mediaType et sortBy. totalCount est le compte de la bibliothèque pour les publicités correspondantes, qui s’arrête à 5,000 pour une recherche par query. returnedCount compte les publicités dans ads, hasMore vaut true lorsque la bibliothèque en a davantage, ce que nextCursor lit, et libraryUrl ouvre la même recherche dans la Bibliothèque publicitaire.
  • Chaque publicité a position, libraryId, libraryUrl, advertiserName, title, format (VIDEO, IMAGE ou TEXT), images, videos (url, previewUrl), startDate, endDate, activeDays, impressions (min, max), estimatedAudience (la fourchette de la bibliothèque, comme 400K-500K) et platforms (TIKTOK).
  • startDate et endDate sont le premier et le dernier jour où la bibliothèque montre la publicité (jours en UTC). activeDays compte les jours de startDate à endDate, les deux inclus. La bibliothèque ne donne pas les dépenses.
  • isActive vaut true ou false lorsque activeStatus est active ou inactive, et null lorsqu’il est all.
  • advertiserId, payer, linkUrl, landingDomain, utm et targeting valent null dans une recherche. ad les remplit.
  • summary compte les publicités de cette réponse : ads, activeAds, advertisers (les 10 qui ont le plus de publicités), formats, platforms, oldestStartDate, newestStartDate et medianActiveDays, avec launchesByWeek (les publicités lancées chaque semaine ISO) et longestRunning (les 5 publicités avec le plus de activeDays). Il ne contient ni landingDomains ni utmCampaigns, 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 ads vide et un summary de 0 publicité.

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.
  • ad contient les champs d’une publicité de recherche, plus linkUrl, landingDomain, payer (qui a payé la publicité), category, objective, ctaText, advertiserId, reachedCountries et targeting.
  • targeting contient byCountry (les ages et genders de chaque pays), provinces, cities, languages, interests, targetAudienceSize (la fourchette de la bibliothèque, comme 15.5M-18.9M), customAudience, excludesAudience, highSpendingPower, operatingSystems, deviceModels, videoInteractions et creatorInteractions. Un élément que la bibliothèque ne publie pas pour la publicité vaut null ou est vide.
  • advertiser contient advertiserId, advertiserName, payer, registryCountry et le account TikTok derrière les publicités (username, displayName, verified, followers, accountType, profileUrl, avatarUrl).
  • transparency contient totalImpressions et byCountry : les impressions de chaque pays et leurs breakdowns par age et gender.
  • Un libraryId pour lequel la bibliothèque n’a aucune publicité échoue avec PAGE_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) ou ad. advertisers est rejeté avec 400 VALIDATION_ERROR, car le Creative Center n’a pas de recherche d’annonceur.
  • country : obligatoire sur search. L’un de AE, 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, VN et ZA. ALL est rejeté.
  • query : un mot-clé.
  • period : 7, 30 (par défaut) ou 180 jours.
  • industry : un ID de secteur, comme 21103000000 (Hardware & Electrical), tel que le nomme le industry.id d’une publicité.
  • objective : traffic, app_installs, conversions, video_views, reach, lead_generation, product_sales ou app_promotion.
  • adLanguage : un code de langue : en, es, ar, vi, th, de, id, pt, fr, ms, nl, ja, it, ro, zh-Hant ou ko.
  • adFormat : spark (publicités qui boostent la publication d’un créateur) ou non_spark.
  • sortBy : for_you (par défaut), impression, ctr, play_2s_rate, play_6s_rate, cvr ou like.
  • limit : de 1 à 200 publicités. Par défaut 30.
  • cursor : le nextCursor d’une réponse précédente.
  • libraryId : l’ID numérique d’une publicité du classement. ad l’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, sortBy et les filtres reçus. totalCount est le nombre de publicités du classement pour cette combinaison.
  • Chaque publicité a position, libraryId, title, advertiserName (souvent null), format, ctrPercent (le taux de clics en pourcentage), costLevel, likes, industry (id, name), objectives, durationSeconds, width, height, voiceOver, images, videos et videoUrls (le fichier vidéo par résolution, comme 360p et 1080p).
  • Le Creative Center ne donne ni startDate, ni endDate, ni impressions, ni libraryUrl, qui valent donc null, et summary ne 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).
Un 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 son limit, 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.

Voir aussi