TikTok: jak sprawdzić, czy monitoring wyszukiwania naprawdę działa

HTTP 200 nie gwarantuje, że codzienny monitoring TikToka zebrał filmy. Wyniki wyszukiwania mogą znajdować się w aweme_list lub w search_item_list[].aweme_info; skrypt odczytujący tylko pierwszą tablicę może zakończyć działanie bez błędu i zapisać pusty raport. Rzetelna kontrola osobno potwierdza status transportowy i aplikacyjny, pobiera dane z obu obsługiwanych wariantów struktury oraz odnotowuje, ile unikalnych filmów udało się wyodrębnić w danym uruchomieniu.

Co warto diagnozować

Wyobraźmy sobie zadanie: każdego ranka zespół zbiera publiczne filmy dla kilku zapytań, aby wychwytywać nowe publikacje o produkcie. Istotnym wynikiem takiego procesu jest powtarzalna lista znalezionych wpisów wraz z opisem, autorem, datą publikacji i dostępnymi wskaźnikami. Jeśli raport nagle jest pusty, przyczyną może być obsługa JSON, zmieniony zestaw wyników, ponowne pobranie znanych już filmów albo rzeczywista awaria zapytania. Jedna liczba — na przykład długość aweme_list — nie pozwala odróżnić tych przypadków.

W TikTok Scraper API jsonscraper trasa wyszukiwania /searchVideo przyjmuje wymagany parametr keyword oraz dodatkowe parametry count, cursor, date_posted, sort_by i region. Dokumentacja trasy opisuje stronicowanie za pomocą cursor; należy przekazywać go jako nieprzezroczystą wartość z poprzedniej odpowiedzi. Parametr count określa żądaną liczbę wyników, a nie gwarantuje pełnego zakresu publikacji.

Podziel kontrolę na cztery sygnały

Przydatna diagnostyka składa się z czterech niezależnych kontroli. Po pierwsze — żądanie HTTP zakończyło się powodzeniem. Po drugie — zewnętrzny status odpowiedzi ma wartość ok, a wewnętrzny tiktok.status_code wskazuje powodzenie. Po trzecie — obecny jest obiekt tiktok, a wpisy są pobierane z obu udokumentowanych miejsc odpowiedzi. Po czwarte — po usunięciu duplikatów pozostały wpisy z identyfikatorami nadającymi się do zapisania. W dzienniku zapisuj liczbę wyodrębnionych elementów przed usunięciem duplikatów i po nim: różnica pokazuje, czy powtórzenia pojawiły się na etapie normalizacji.

Brakujące pole należy pozostawić puste, a nie zastępować wymyśloną wartością. Na przykład liczba wyświetleń może nie występować w konkretnym wpisie. Zachowanie źródłowego JSON obok znormalizowanego rekordu ułatwia późniejsze sprawdzenie, czy informacja zaginęła podczas parsowania, czy nie było jej już w odpowiedzi źródłowej.

Minimalne żądanie i normalizacja w Pythonie

Specyfikacja jsonscraper określa adres bazowy https://tiktok.evelode.com oraz przekazywanie klucza w parametrze żądania license_key. Poniższy przykład używa udokumentowanych parametrów; klucz jest odczytywany ze zmiennej środowiskowej i nie trafia do dziennika. Zainstaluj zależność poleceniem python -m pip install requests, a następnie ustaw w środowisku zmienną JSONSCRAPER_TIKTOK_LICENSE_KEY.

import json
import os
from datetime import datetime, timezone
from pathlib import Path

import requests

BASE_URL = "https://tiktok.evelode.com/searchVideo"
KEY = os.environ["JSONSCRAPER_TIKTOK_LICENSE_KEY"]


def extract_videos(payload):
    """Zbierz filmy z obu znanych struktur odpowiedzi wyszukiwania."""
    tiktok = payload.get("tiktok") or {}
    videos = []

    for item in tiktok.get("aweme_list") or []:
        if isinstance(item, dict):
            videos.append(item)

    for item in tiktok.get("search_item_list") or []:
        if isinstance(item, dict):
            aweme = item.get("aweme_info")
            if isinstance(aweme, dict):
                videos.append(aweme)

    return videos


def main():
    params = {
        "license_key": KEY,
        "keyword": "przykładowe zapytanie o produkcie",
        "count": 20,
        "region": "US",
    }
    response = requests.get(BASE_URL, params=params, timeout=30)
    response.raise_for_status()
    payload = response.json()

    if payload.get("status") != "ok":
        raise RuntimeError("API zwróciło zewnętrzny status inny niż ok")

    tiktok = payload.get("tiktok")
    if not isinstance(tiktok, dict):
        raise RuntimeError("W odpowiedzi brakuje obiektu tiktok")

    if tiktok.get("status_code") != 0:
        raise RuntimeError("Wewnętrzny status_code nie jest równy pomyślnej wartości 0")

    raw_videos = extract_videos(payload)
    unique = {}
    for video in raw_videos:
        video_id = video.get("aweme_id")
        if video_id:
            unique.setdefault(str(video_id), video)

    snapshot = {
        "collected_at": datetime.now(timezone.utc).isoformat(),
        "keyword": params["keyword"],
        "status": payload.get("status"),
        "status_code": tiktok.get("status_code"),
        "raw_items": len(raw_videos),
        "unique_items": len(unique),
        "has_more": tiktok.get("has_more"),
        "cursor": tiktok.get("cursor"),
        "videos": list(unique.values()),
    }

    Path("snapshots").mkdir(exist_ok=True)
    stamp = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ")
    Path(f"snapshots/{stamp}.json").write_text(
        json.dumps(snapshot, ensure_ascii=False, indent=2),
        encoding="utf-8",
    )

    print({
        "status": snapshot["status"],
        "status_code": snapshot["status_code"],
        "raw_items": snapshot["raw_items"],
        "unique_items": snapshot["unique_items"],
        "has_more": snapshot["has_more"],
    })


if __name__ == "__main__":
    main()

Skrypt sprawdza warstwę transportową za pomocą raise_for_status(), a następnie weryfikuje status zewnętrzny, obecność obiektu tiktok i wewnętrzny status_code. Potem pobiera wpisy z dwóch struktur wyszukiwania, usuwa duplikaty według aweme_id i zapisuje migawkę z czasem zebrania danych. Jeśli nie ma pasujących wpisów, plik nadal zawiera informacje o uruchomieniu, co pozwala odróżnić zapisany pusty wynik od brakującego raportu.

Jak zamienić migawki w sygnał dla zespołu

Uruchamiaj skrypt według harmonogramu za pomocą cron, CI lub planisty przepływu pracy. Migawki dla poszczególnych zapytań przechowuj osobno albo dodawaj słowo kluczowe do nazwy pliku. W tabeli stanu wystarczy zapisywać czas uruchomienia, status, liczbę pobranych i unikalnych wpisów oraz flagę has_more. Warto wysyłać powiadomienie w razie wyjątku żądania, braku wymaganych części odpowiedzi albo gwałtownej zmiany liczby pobranych wpisów w porównaniu z własną historią.

Takie porównanie wykrywa anomalię w potoku, ale samo w sobie nie wyjaśnia jej przyczyny. Mniejsza liczba wyników może odzwierciedlać bieżący skład zestawu, a nie awarię API czy parsera. Dlatego warto zachowywać źródłowy JSON, porównywać identyczne parametry i sprawdzać znalezione identyfikatory. Próg powiadomienia dobierz na podstawie obserwacji dotyczących własnego zapytania, a nie uniwersalnej wartości.

Do stronicowania używaj cursor z odpowiedzi i zakończ przeglądanie, gdy API poinformuje, że nie ma kolejnych wyników. Zapisuj użyte kursory i parametry żądania, aby można było odtworzyć uruchomienie. Parametry date_posted i sort_by pozwalają ustawić filtr czasu i sortowanie; jeśli zadanie wymaga powtarzalnych porównań, zachowuj ich wartości między uruchomieniami.

Jak interpretować wynik

Po wdrożeniu zespół zyskuje weryfikowalną odpowiedź na trzy praktyczne pytania: czy żądanie się powiodło, gdzie w JSON znajdują się wyniki i ile unikalnych filmów trafiło do zapisanej migawki. Skraca to drogę od pustej tabeli do diagnozy: najpierw sprawdza się statusy i strukturę, a potem parametry, duplikaty i zawartość odpowiedzi źródłowej.

Schemat odpowiedzi i dostępne pola mogą różnić się między wpisami. W teście live jsonscraper z 25 października 2026 r. wyszukiwanie zwracało pola identyfikatora, opisu, autora i statystyk; wartości dla konkretnego wpisu należy traktować jako opcjonalne. Działający raport przechowuje faktycznie otrzymane dane i nie zastępuje braków zerami.

Można zacząć od strony TikTok Scraper API, a dokładne trasy i parametry sprawdzić w oficjalnej dokumentacji API. Taka kontrola przydaje się przed uruchomieniem monitoringu: raport staje się obserwowalnym wynikiem, którego jakość można diagnozować.