Zeitfenster

Verschiedene Teile der API verwenden unterschiedliche Datumsfilter. Dieser Leitfaden dient als Übersicht – wähle den richtigen Filter für den Endpunkt, den du aufrufst, und verwechsle sie nicht.

Auf einen Blick#

Der häufigste Fehler überhaupt: das Versenden Startdatum / Enddatum neben Zeitraum auf TikTok-Shop-Endpunkten. Tun Sie das nicht – diese Felder kollidieren mit der vorangehenden, auf Punktzeichen achtenden Umsatzzuordnung und filtern die meisten Daten stillschweigend heraus. Pass nur Zeitraum sofern in der Dokumentation zu einem bestimmten Endpunkt nichts anderes angegeben ist.

TikTok Shop Zeitraum#

Verwendet von entdecken, Zahl, Detailaggregate, Geschichteund die meisten Endpunkte mit metrischen Werten unter /api/v1/tiktok-shop/.

curl -sS \
  -H "X-API-Key: $WH_API_KEY" \
  "{origin}/api/v1/tiktok-shop/products/explore?country=US&period=30d&limit=20"

• Leckerli Zeitraum als undurchsichtige Schnur das die Benutzeroberfläche des In-App-Filters widerspiegelt (7d, 30d, 90d, …). Das Backend ordnet diese Daten periodenspezifischen Feldern zu wie Umsatz_30d, Umsatzwachstumsrate_7dusw.
• Tun nicht sowie Startdatum / Enddatum. Die TikTok Shop-API ordnet diese nicht dem Explore-Ablauf zu – ihr Versand kann vorgelagert ein eingeschränktes „Zuletzt in den letzten N Tagen gesehen“-Verhalten auslösen und nur einen winzigen Ausschnitt des Katalogs zurückgeben.
• Sortierschlüssel (sort=) folgen demselben Zeitraum – vergehen sort=Umsatz mit Zeitraum=7 Tage wird Umsatz_7d vorgelagert.
• Bei Gesamtumsatzzahlen (z. B. Shop-Gesamtumsätze) bestimmt der Zeitraum, welche Umsatz.{key} Feld, das Sie in der Antwort lesen sollten.

Endpunkte für Visit-Ereignisse (Produkt – Sonstiges – Besuche, Kategorie: Veranstaltungen besuchen, Veranstaltungen im Detail)#

Diese akzeptieren einen begrenzteren Satz:

Die Antwort umfasst Zeitraumbezeichnung (z. B. „Letzte 30 Tage“), damit du es ohne weitere Auswertung anzeigen kannst.

Marken-Tracker Datum#

Wird von Dashboard-Routen wie /api/brands/ads, /api/brands/ad-copies, /api/brands/ad-headlines, /api/brands/ad-hooks, /api/brands/personas, /api/brands/themesund die anderen Registerkarten mit Markendetails (Sitzung).

GET /api/brands/ads?id={page_id}&date_range=30d
GET /api/brands/ad-copies?id={page_id}&date_range=custom&date_from=2026-01-01&date_to=2026-03-31

Zulässige Werte (gleiche Funktionsweise wie die Datumsauswahl im Brand Tracker der App):

Ein paar Tipps:

• Die gleichen drei Parameter (Datum, Beginn, bis) über alle Registerkarten mit Markendetails hinweg übernehmen. Sobald Sie einen Datumsfilter für den Benutzer eingerichtet haben, verwenden Sie diesen bei jedem Aufruf für diese Markensitzung erneut.
• live ist das nur Der Wert basiert auf „zuletzt gesehen“, nicht auf „gestartet“. Verwechsle dies nicht mit 7d.
• benutzerdefiniert ohne beides Beginn und bis fällt auf „kein Datumsfilter“ zurück.

Die Oberfläche mit den Markendetails ist nur für die Sitzung (angemeldeter Browser), daher gilt dieser Abschnitt, wenn Sie das Dashboard spiegeln, nicht jedoch, wenn Sie GET /api/v1/brands allein. Vollständige Quellenangabe: Marken & Marken-Tracker.

GET /api/v1/tiktok-shop/products#

Diese Route ist ein flacher Endpunkt, der eine kleine Anzahl von GET-Parametern akzeptiert, darunter auch explizite Datumsangaben:

GET /api/v1/tiktok-shop/products
  ?country=US
  &date_from=2026-03-01
  &date_to=2026-03-31
  &search=mascara
  &min_price=10&max_price=50
  &min_sales=100
  &min_rating=4

• Beide Beginn und bis sind J-M-T Zeichenfolgen.
• Beides kann weggelassen werden; in diesem Fall wendet der vorgelagerte Prozess eine sinnvolle Standardeinstellung an.
• Dies ist die nur Der Pfad für die einfache Produktliste im TikTok Shop, wo Beginn / bis sind erstklassige Parameter. Auf allen anderen Pfaden ist Zeitraum.

Warum das Mischen von Zeitparametern schiefgeht#

Ein häufiger Fehler: eine Anfrage vom Typ „products explore“ zu kopieren und hinzuzufügen start_date=2026-01-01 in der Annahme, dass sich dadurch der Spielraum verringert. Was tatsächlich passiert:

1. Der Explore-Handler behält Zeitraum=30 Tage (Standard).
2. Außerdem leitet es Ihre Startdatum / Enddatum.
3. Upstream interpretiert dies als „erstmals zwischen diesen Daten gesehen“.
4. Du erhältst etwa 5 % des Katalogs zurück – und zwar nur Artikel, die genau in diesem Zeitraum zum ersten Mal gecrawlt wurden.

Lösung: Wählen Sie eins Mechanismus pro Anfrage. Wenn Zeitraum Wenn dies Ihren Anforderungen entspricht, verwenden Sie es einfach so. Wenn Sie wirklich einen benutzerdefinierten Bereich benötigen, nutzen Sie die in der Dokumentation beschriebenen Möglichkeiten. Beginn / bis (der Marken-Tracker, die Wohnung Produkte Eintrag, die Anzeigenbibliothek).

Kurzer Entscheidungsbaum#

• Anruf /api/v1/tiktok-shop/... Entdecken / Zählen / Details / Geschichte? → Zeitraum=7 Tage|30 Tage|90 Tage.
• Anruf /api/v1/tiktok-shop/products (Wohnungsanzeige)? → Beginn, bis.
• Anruf /api/v1/tiktok-shop/...visit-events* oder Produkt – Sonstiges – Besuche? → Zeitraum=7 Tage|30 Tage|alle.
• Anruf /api/brands/* (Dashboard-Sitzung)? → Datum, sowie Beginn + bis falls date_range=benutzerdefiniert. (Verfolgungsliste mit einem API-Schlüssel: GET /api/v1/brands — nein Datum auf dieser Strecke.)
• Anruf /api/v1/adlibrary oder /api/adlibrary (Meta-Anzeigen)? → siehe Meta-Anzeigenbibliothek.