Zum Hauptinhalt springen
Lesen Sie die Werbequellen von TikTok über die asynchrone Task-API als JSON. ADS ist eine eigene Engine: Senden Sie taskType ADS mit einer von zwei Plattformen, und action wählt, was gelesen wird. Zur Auswahl zwischen den Werbebibliotheken siehe Werbebibliotheken im Vergleich.
  • tiktok_ad_library liest die TikTok-Werbebibliothek (die Commercial Content Library). Sie listet die Anzeigen auf, die in 34 Regionen ausgespielt wurden: den EU- und EWR-Ländern, dem Vereinigten Königreich, der Schweiz, Türkiye und Brasilien. Jede Anzeige enthält ihren ersten und letzten Ausspielungstag und eine Impressionen-Spanne, und ad ergänzt die Zielseite, den Zahler, das Targeting und die Impressionen nach Land, Alter und Geschlecht. Nutzen Sie sie, um alle Anzeigen eines Wettbewerbers zu sehen.
  • tiktok_creative_center liest die Top-Anzeigen des TikTok Creative Center. Es listet die Anzeigen auf, die in einem Land in den letzten 7, 30 oder 180 Tagen am besten abgeschnitten haben, mit Klickrate, Likes und Branche, für 28 Länder, darunter die USA, Korea und Japan. Nutzen Sie es, um zu sehen, welche Creatives in einem Markt funktionieren.
Eine Suche kostet 0.5 Credits je 30 Anzeigen, die sie auf beiden Plattformen liefert. advertisers und ad kosten je 0.5 Credits.

TikTok-Werbebibliothek

Anfrage

Senden Sie den Task ab und fragen Sie dann GET /v1/async/task/{id} ab oder empfangen Sie den Webhook. Siehe Asynchrone Tasks. Eine Suche nach 300 Anzeigen dauert etwa eine Minute.

Anzeigen eines Wettbewerbers analysieren

Drei Anfragen decken eine Wettbewerbsanalyse ab:
  1. advertisers mit dem Anfang des Namens des Wettbewerbers liefert die genauen Namen und IDs, die die Bibliothek kennt.
  2. search mit diesem Namen in advertiserName listet die Anzeigen des Werbetreibenden auf. sortBy ordnet sie nach Veröffentlichungsdatum, Datum der letzten Ausspielung oder Impressionen, activeStatus behält die laufenden oder die beendeten Anzeigen, und summary zählt die Formate und die Anzeigen, die in jeder Woche gestartet sind.
  3. ad mit der libraryId einer Anzeige liefert die Zielseite, wer bezahlt hat, das Targeting, die Zielgruppengröße und die Impressionen nach Land, Alter und Geschlecht.
Um Anzeigen nach ihrem Inhalt zu finden, nutzen Sie query statt advertiserName: Es durchsucht den Text, die Hashtags und die Namen der Werbetreibenden.

Parameter

  • action: search (Standard), advertisers oder ad.
  • country: Bei jeder Aktion erforderlich. Eines von 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 und TR. ALL und Länder außerhalb der Liste, etwa US, KR und JP, werden mit 400 VALIDATION_ERROR abgelehnt, weil die Bibliothek nur diese Regionen abdeckt.
  • query: Ein Stichwort. Bei search passt es nach Relevanz auf Text, Hashtags und Werbetreibende, und die Bibliothek zählt höchstens 5,000 Anzeigen. Bei advertisers ist es der Anfang des Namens eines Werbetreibenden und erforderlich. search braucht query oder advertiserName, aber nicht beides.
  • advertiserName: Der genaue Name eines Werbetreibenden, etwa NIKE Retail B.V.. Die Bibliothek zählt alle seine Anzeigen.
  • libraryId: Die numerische ID einer Anzeige, etwa 1879578148398450. ad verlangt sie.
  • activeStatus: all (Standard), active oder inactive.
  • mediaType: all (Standard), video oder image.
  • startDate, endDate: YYYY-MM-DD. Behält die Anzeigen, die zwischen den beiden Tagen ausgespielt wurden. Standard sind die letzten 365 Tage.
  • sortBy: published_desc (Standard), published_asc, last_shown_desc, last_shown_asc, impressions_desc oder impressions_asc. Es gilt für eine Suche mit advertiserName, und eine Suche mit query folgt immer der Relevanz.
  • limit: 1 bis 300 Anzeigen. Standard 30.
  • cursor: Der nextCursor einer früheren Antwort, um die darauffolgenden Anzeigen zu lesen.
search liest alle Felder oben außer libraryId. advertisers liest query und country, und ad liest libraryId und country. Ein Wert, den die Bibliothek nicht durchsuchen kann, oder ein Feld, das die Aktion nicht liest, wird mit 400 VALIDATION_ERROR abgelehnt, und details nennt das Feld.

Weitere Anzeigen lesen

Eine Antwort mit weiteren zu lesenden Anzeigen enthält nextCursor. Senden Sie ihn mit derselben Suche als cursor, um die nächsten Anzeigen zu erhalten, wieder bis zu limit. nextCursor ist null, sobald die Bibliothek keine weiteren hat. Ein Cursor funktioniert nur mit der Suche, die ihn geliefert hat: Eine andere query, advertiserName, country, activeStatus, mediaType, ein anderer Datumsbereich oder sortBy wird mit 400 VALIDATION_ERROR abgelehnt, während sich limit ändern darf. Bei einer query-Suche, die die Bibliothek nach Relevanz ordnet, können einige Anzeigen an der Grenze zweier Seiten doppelt vorkommen oder fehlen; libraryId unterscheidet die Duplikate.

Werbetreibenden finden

action advertisers liefert bis zu 20 Werbetreibende, deren Namen mit query beginnen. Senden Sie den genauen Namen als advertiserName, um die Anzeigen dieses Werbetreibenden zu suchen.
Jeder Werbetreibende hat advertiserId und advertiserName. country, adCount und verified sind null, weil die Vorschläge der Bibliothek nicht mehr liefern. Eine Werbetreibenden-Suche kostet 0.5 Credits.

Such-Antwort

  • Die Antwort gibt platform, action, country, query oder advertiserName, activeStatus, mediaType und sortBy zurück. totalCount ist die Zählung der Bibliothek für die passenden Anzeigen, die bei einer query-Suche bei 5,000 endet. returnedCount zählt die Anzeigen in ads, hasMore ist true, wenn die Bibliothek mehr hat, die nextCursor liest, und libraryUrl öffnet dieselbe Suche in der Werbebibliothek.
  • Jede Anzeige hat position, libraryId, libraryUrl, advertiserName, title, format (VIDEO, IMAGE oder TEXT), images, videos (url, previewUrl), startDate, endDate, activeDays, impressions (min, max), estimatedAudience (die Spanne der Bibliothek, etwa 400K-500K) und platforms (TIKTOK).
  • startDate und endDate sind der erste und der letzte Tag, an dem die Bibliothek die Anzeige zeigt (Tage in UTC). activeDays zählt die Tage von startDate bis endDate, beide mitgezählt. Die Bibliothek liefert keine Ausgaben.
  • isActive ist true oder false, wenn activeStatus active oder inactive ist, und null, wenn es all ist.
  • advertiserId, payer, linkUrl, landingDomain, utm und targeting sind in einer Suche null. ad füllt sie.
  • summary zählt die Anzeigen dieser Antwort: ads, activeAds, advertisers (die 10 mit den meisten Anzeigen), formats, platforms, oldestStartDate, newestStartDate und medianActiveDays, mit launchesByWeek (die Anzeigen, die in jeder ISO-Woche starteten) und longestRunning (die 5 Anzeigen mit den meisten activeDays). Es enthält weder landingDomains noch utmCampaigns, weil eine Suche keine Zielseiten enthält.
  • Bild- und Video-URLs sind signiert und laufen etwa 5 bis 6 Stunden nach dem Lesen ab. Speichern Sie die Dateien, die Sie brauchen.
  • Eine Suche ohne passende Anzeigen endet mit leerem ads und einer summary mit 0 Anzeigen.

Was die Bibliothek aufbewahrt

Die Bibliothek zeigt in ihren 34 Regionen ausgespielte Anzeigen und bewahrt sie etwa 13 Monate auf. Sie liefert zu jeder Anzeige den ersten und letzten Ausspielungstag und eine Impressionen-Spanne. Ausgaben veröffentlicht sie nicht.

Eine Anzeige öffnen

action ad öffnet die Anzeige mit der libraryId und dem country, die Sie senden.
  • ad enthält die Felder einer Suchanzeige sowie linkUrl, landingDomain, payer (wer die Anzeige bezahlt hat), category, objective, ctaText, advertiserId, reachedCountries und targeting.
  • targeting enthält byCountry (die ages und genders jedes Landes), provinces, cities, languages, interests, targetAudienceSize (die Spanne der Bibliothek, etwa 15.5M-18.9M), customAudience, excludesAudience, highSpendingPower, operatingSystems, deviceModels, videoInteractions und creatorInteractions. Ein Teil, den die Bibliothek für die Anzeige nicht veröffentlicht, ist null oder leer.
  • advertiser enthält advertiserId, advertiserName, payer, registryCountry und das TikTok-account hinter den Anzeigen (username, displayName, verified, followers, accountType, profileUrl, avatarUrl).
  • transparency enthält totalImpressions und byCountry: die impressions jedes Landes und ihre breakdowns nach age und gender.
  • Eine libraryId, zu der die Bibliothek keine Anzeige hat, schlägt mit PAGE_UNAVAILABLE fehl.

TikTok Creative Center

Das Creative Center listet die leistungsstärksten Anzeigen eines Landes auf, die Anzeigen, die TikTok für die letzten 7, 30 oder 180 Tage auswählt. Es ist eine gereihte Stichprobe, nicht die vollständige Anzeigenmenge eines Werbetreibenden: Der Name des Werbetreibenden ist oft leer, und die Bibliothek liefert weder Daten noch Ausgaben noch Impressionen. Sie liefert Klickrate, Likes, Kostenniveau, Branche und Ziele jeder Anzeige. Nutzen Sie es, um herauszufinden, welche Hooks, Formate und Produkte in einem Markt funktionieren.

Anfrage

Parameter

  • action: search (Standard) oder ad. advertisers wird mit 400 VALIDATION_ERROR abgelehnt, weil das Creative Center keine Suche nach Werbetreibenden bietet.
  • country: Bei search erforderlich. Eines von 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 und ZA. ALL wird abgelehnt.
  • query: Ein Stichwort.
  • period: 7, 30 (Standard) oder 180 Tage.
  • industry: Eine Branchen-ID, etwa 21103000000 (Hardware & Electrical), wie sie die industry.id einer Anzeige nennt.
  • objective: traffic, app_installs, conversions, video_views, reach, lead_generation, product_sales oder app_promotion.
  • adLanguage: Ein Sprachcode: en, es, ar, vi, th, de, id, pt, fr, ms, nl, ja, it, ro, zh-Hant oder ko.
  • adFormat: spark (Anzeigen, die den Beitrag eines Creators bewerben) oder non_spark.
  • sortBy: for_you (Standard), impression, ctr, play_2s_rate, play_6s_rate, cvr oder like.
  • limit: 1 bis 200 Anzeigen. Standard 30.
  • cursor: Der nextCursor einer früheren Antwort.
  • libraryId: Die numerische ID einer Top-Anzeige. ad verlangt sie.
search liest alle Felder oben außer libraryId, und ad liest nur libraryId. Das Creative Center listet für ein Land, einen Zeitraum und einen Filtersatz höchstens etwa 400 bis 500 Anzeigen auf (totalCount).

Such-Antwort

  • Die Antwort gibt platform, action, country, period, sortBy und die erhaltenen Filter zurück. totalCount ist die Zahl der Top-Anzeigen für diese Kombination.
  • Jede Anzeige hat position, libraryId, title, advertiserName (oft null), format, ctrPercent (die Klickrate in Prozent), costLevel, likes, industry (id, name), objectives, durationSeconds, width, height, voiceOver, images, videos und videoUrls (die Videodatei je Auflösung, etwa 360p und 1080p).
  • Das Creative Center liefert weder startDate noch endDate, impressions oder libraryUrl, daher sind diese null, und summary zählt nur die Formate, Werbetreibenden und Plattformen.
  • Video- und Bild-URLs sind signiert und laufen etwa 5 bis 6 Stunden nach dem Lesen ab.

Eine Anzeige öffnen

action ad öffnet eine Top-Anzeige über libraryId und ergänzt linkUrl, landingDomain, reachedCountries, comments, shares und source (wo die Anzeige erstellt wurde, etwa TikTok Ads Manager).
Eine libraryId, zu der das Creative Center keine Anzeige hat, schlägt mit PAGE_UNAVAILABLE fehl.

Preis

Eine Suche reserviert 0.5 Credits je 30 Anzeigen, die ihr limit verlangt, und berechnet 0.5 Credits je 30 gelieferte Anzeigen, mindestens 0.5 Credits. Die Standardsuche mit 30 Anzeigen kostet 0.5 Credits, und eine Suche mit limit 300 in der Werbebibliothek reserviert 5 Credits. advertisers und ad kosten je 0.5 Credits. Nur abgeschlossene Anfragen werden berechnet.

Siehe auch