Jak porównywać kreacje konkurencji na TikToku na podstawie publicznych wskaźników: pipeline w Pythonie

Dwa zespoły publikują filmy o podobnym produkcie, ale oceniają je ręcznie według różnych kryteriów: jeden zapamiętuje wyświetlenia, drugi — komentarze, a trzeci zapisuje linki na czacie. Po tygodniu trudno stwierdzić, jakie formaty powtarzają się u konkurencji, które publikacje zbierają zauważalne reakcje i co zmieniło się od poprzedniego przeglądu.

Rozwiązaniem jest zebranie ograniczonej, możliwej do odtworzenia próbki publicznych filmów na podstawie wcześniej ustalonych słów kluczowych, zapisanie surowego JSON-a i utworzenie tabeli ze spójnymi polami. Dzięki temu można porównywać filmy w ramach jednego procesu pracy, zamiast mieszać przypadkowe obserwacje z wnioskami o rynku. Poniżej przedstawiamy schemat niewielkiego monitoringu konkurencji w Pythonie z wykorzystaniem TikTok Scraper API od jsonscraper.

Najpierw określ pytanie analityczne

Zbieranie danych jest przydatne, gdy z góry wiadomo, jaka decyzja zostanie podjęta na podstawie wyników. Na przykład zespół marketingowy producenta sportowych butelek chce sprawdzić, jak konkurenci pokazują produkt w krótkich filmach: poprzez demonstrację użycia, rozpakowywanie, porównanie czy reakcję użytkownika. Nie trzeba w tym celu kopiować całego TikToka. Wystarczy kilka ukierunkowanych zapytań i powtarzalne obserwowanie filmów zwracanych przez API dla tych zapytań.

Sformułuj pytanie tak, by można było je zweryfikować: „Jakie formaty opisów i demonstracji pojawiają się wśród opublikowanych filmów znalezionych za pomocą naszych pięciu kluczowych fraz i które z tych filmów mają obecnie najwięcej wyświetleń oraz reakcji?”. Takie ujęcie rozdziela dwa poziomy analizy. Tekst i opis pomagają pogrupować podejścia kreatywne, a liczniki wyświetleń, polubień, komentarzy i udostępnień pokazują publiczne reakcje w chwili zbierania danych.

Taka migawka pomaga ustalić priorytety ręcznego przeglądu i śledzić zmiany. Opisuje filmy zwrócone dla konkretnych zapytań, parametrów i czasu uruchomienia. Dlatego poprawny wniosek brzmi: „w naszej próbce często pojawiają się filmy z rozpakowywaniem” albo „ta grupa filmów ma obecnie wyższą medianę wyświetleń”. Taki zakres analizy pomaga zespołowi wybierać hipotezy do własnych treści.

Zap projektuj niewielki pipeline danych

Podziel pracę na cztery etapy: zbieranie, zapis surowej odpowiedzi, normalizację i analizę. Zbieranie odpytuje API dla każdego zatwierdzonego słowa kluczowego. Surowa odpowiedź jest zapisywana w całości, aby można ją było ponownie sprawdzić. Normalizacja przekształca zagnieżdżoną strukturę JSON w wiersze tabeli, a analityka oblicza wskaźniki i grupuje filmy według słów kluczowych lub ręcznie przypisanych formatów.

• Zbieranie. Pobierz określoną liczbę wyników dla każdego słowa kluczowego, stosując ten sam region i sortowanie.
• Archiwum. Zapisz surowy JSON i czas pobrania, aby można było zweryfikować wyodrębnione wartości.
• Normalizacja. Zachowaj identyfikator filmu, link, opis, autora, czas publikacji i dostępne liczniki.
• Kontrola jakości. Usuń duplikaty według ID, oznacz brakujące wartości i zachowaj słowo kluczowe, które doprowadziło do znalezienia filmu.
• Porównanie. Obliczaj własne wskaźniki wyłącznie na podstawie dostępnych pól źródłowych i porównuj grupy w ramach jednej migawki.

Takie podejście jest lepsze niż lista linków, ponieważ zachowuje pochodzenie każdego wiersza i pozwala odróżnić ponowne pojawienie się tego samego filmu od nowego materiału. Zapisuj także datę pobrania: publiczne liczniki mogą się zmieniać, więc wartości z dzisiejszej odpowiedzi nie należy traktować jako stałej cechy filmu.

Co obsługuje TikTok Scraper API

Do wyszukiwania filmów na podstawie zapytania tekstowego dokumentacja jsonscraper opisuje trasę GET /searchVideo pod adresem bazowym https://tiktok.evelode.com. Wymaganym parametrem jest keyword; dostępne są też count, cursor, region, date_posted, sort_by i cache_timeout. Dokumentacja wymienia opcje sortowania most-liked, relevance i date-posted, a wśród okresów publikacji: yesterday, this-week, this-month, last-3-months, last-6-months i all-time. Nazwy parametrów i ich przeznaczenie sprawdź w dokumentacji tras TikToka.

Klucz przekazuje się w parametrze zapytania license_key. W skrypcie używanym do pracy umieść go w zmiennej środowiskowej JSONSCRAPER_TIKTOK_LICENSE_KEY, a nie w pliku źródłowym, arkuszu ani dzienniku uruchomień. W odpowiedzi sprawdź najwyższy poziom status, a następnie przetwórz obiekt tiktok. Struktura odpowiedzi wyszukiwania może zawierać listę aweme_list, a także search_item_list, w której informacje o filmie znajdują się w aweme_info. Poniższy kod obsługuje oba formaty.

W potwierdzonych obserwacjach odpowiedzi wyszukiwania występują ID filmu, opis, czas publikacji, link, informacje o autorze oraz wskaźniki, takie jak liczba wyświetleń, polubień, komentarzy, zapisów i udostępnień. W konkretnym rekordzie niektóre pola mogą nie występować. W tabeli pozostaw takie wartości puste, zamiast zastępować je zerem: zero oznacza zmierzoną wartość, a puste pole — brak wartości w otrzymanym obiekcie.

Minimalny przykład w Pythonie

Poniższy skrypt wykonuje jedno zapytanie dla każdego słowa kluczowego, zapisuje pełną odpowiedź w pliku JSON i tworzy plik CSV do arkusza kalkulacyjnego lub dalszego przetwarzania. Wymaga Pythona 3.8+ i korzysta wyłącznie z biblioteki standardowej. Przed uruchomieniem ustaw zmienną środowiskową z kluczem licencyjnym. Dostosuj listę słów kluczowych i liczbę wyników do swojego przypadku.

import csv
import json
import os
import time
from datetime import datetime, timezone
from pathlib import Path
from urllib.parse import urlencode
from urllib.request import urlopen

BASE_URL = "https://tiktok.evelode.com/searchVideo"
LICENSE_KEY = os.environ["JSONSCRAPER_TIKTOK_LICENSE_KEY"]
KEYWORDS = ["termos", "butelka sportowa", "rozpakowywanie butelki"]
REGION = "US"
COUNT = 20


def request_search(keyword):
    params = {
        "license_key": LICENSE_KEY,
        "keyword": keyword,
        "count": COUNT,
        "region": REGION,
        "sort_by": "relevance",
        "date_posted": "this-month",
    }
    url = BASE_URL + "?" + urlencode(params)
    with urlopen(url, timeout=60) as response:
        return json.loads(response.read().decode("utf-8"))


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

    tiktok = payload.get("tiktok") or {}
    rows = []

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

    for item in tiktok.get("search_item_list") or []:
        video = item.get("aweme_info") if isinstance(item, dict) else None
        if isinstance(video, dict):
            rows.append(video)

    return rows, tiktok


Path("raw").mkdir(exist_ok=True)
seen = set()
records = []

for keyword in KEYWORDS:
    payload = request_search(keyword)
    collected_at = datetime.now(timezone.utc).isoformat()
    safe_name = keyword.replace(" ", "_")
    raw_path = Path("raw") / (safe_name + ".json")
    raw_path.write_text(json.dumps(payload, ensure_ascii=False, indent=2), encoding="utf-8")

    videos, tiktok = extract_videos(payload)
    for video in videos:
        video_id = video.get("aweme_id")
        if not video_id:
            continue
        dedupe_key = (keyword, video_id)
        if dedupe_key in seen:
            continue
        seen.add(dedupe_key)

        stats = video.get("statistics") or {}
        author = video.get("author") or {}
        records.append({
            "collected_at": collected_at,
            "keyword": keyword,
            "video_id": video_id,
            "url": video.get("share_url"),
            "created_at_epoch": video.get("create_time"),
            "description": video.get("desc"),
            "author": author.get("nickname"),
            "username": author.get("unique_id"),
            "views": stats.get("play_count"),
            "likes": stats.get("digg_count"),
            "comments": stats.get("comment_count"),
            "shares": stats.get("share_count"),
            "saves": stats.get("collect_count"),
            "cursor": tiktok.get("cursor"),
        })

    time.sleep(1)

fieldnames = [
    "collected_at", "keyword", "video_id", "url", "created_at_epoch",
    "description", "author", "username", "views", "likes", "comments",
    "shares", "saves", "cursor",
]
with open("tiktok_creatives.csv", "w", newline="", encoding="utf-8") as output:
    writer = csv.DictWriter(output, fieldnames=fieldnames)
    writer.writeheader()
    writer.writerows(records)

print("Zapisano", len(records), "wierszy filmów do tiktok_creatives.csv")

Skrypt zapisuje słowo kluczowe przy filmie — to ważne, jeśli ten sam materiał został znaleziony za pomocą kilku zapytań. W tym przykładzie deduplikacja odbywa się w obrębie każdego słowa kluczowego, więc to samo ID może wystąpić w osobnym wierszu dla różnych zapytań. Aby uzyskać jedną tabelę bez powtórzeń, zastąp klucz (keyword, video_id) przez video_id, a słowa kluczowe gromadź na liście lub w osobnej tabeli powiązań.

Kod celowo wykonuje jedno zapytanie dla każdego słowa i nie przegląda automatycznie kolejnych stron. Jeśli potrzebna jest następna strona, dokumentacja definiuje cursor jako wartość służącą do przewijania wyników, pobieraną z poprzedniej odpowiedzi. Przekazuj ją jako nieprzejrzystą wartość i nie obliczaj samodzielnie. W danym procesie sprawdź schemat stronicowania na testowej odpowiedzi i zakończ, gdy zabraknie nowych wyników lub kolejnego kursora.

Jak uzyskać tabelę umożliwiającą porównania

Plik CSV można otworzyć w arkuszu kalkulacyjnym, wczytać do bazy danych lub wykorzystać w Pythonie do obliczania agregatów. W pierwszym raporcie grupuj wiersze według daty pobrania, słowa kluczowego i formatu filmu. Format najlepiej oznaczać po obejrzeniu opisu i samego filmu, na przykład: „demonstracja”, „rozpakowywanie”, „opinia”, „porównanie”. Na niewielkiej próbce klasyfikację można przeprowadzić ręcznie lub poprosić model o wstępne oznaczenie, które następnie sprawdzi człowiek.

Jeśli automatycznie oznaczasz teksty, przekazuj modelowi tylko potrzebne pola — na przykład opis i identyfikator — i poproś o zwrócenie jednej etykiety z wcześniej zatwierdzonej listy. Zapisuj opis źródłowy oddzielnie od wyniku klasyfikacji. Dzięki temu analityk będzie mógł sprawdzić sporną etykietę i ponownie obliczyć raport po zmianie taksonomii, bez ponownego wysyłania zapytania do API.

Do porównań wykorzystuj wartości zebrane w tym samym czasie. Na przykład stosunek polubień do wyświetleń można obliczyć jako likes / views, jeśli oba pola są dostępne, a liczba wyświetleń jest większa od zera. Podobnie można obliczyć udział komentarzy lub udostępnień. Te stosunki opisują bieżące publiczne liczniki danego filmu; nie mierzą zasięgu konkretnej publiczności, obejrzeń do końca ani konwersji. Podejmując decyzje biznesowe, zestawiaj je z własną kampanią i traktuj jako wskazówkę przy wyborze pomysłów, a nie obietnicę efektu po powtórzeniu cudzego formatu.

Mediana bywa przydatniejsza od średniej, gdy w próbce jest kilka wyjątkowo popularnych filmów. Porównuj medianę wyświetleń i medianę reakcji w grupach tylko przy zastosowaniu tych samych zasad zbierania danych: tego samego zestawu zapytań, regionu, filtra czasu i zbliżonej pory wykonania migawki. Zapisuj parametry uruchomienia wraz z datą. Jeśli zmiana wyszukiwania lub próbki wpływa na skład wierszy, różnica między dwoma raportami może wynikać również ze zmiany metody.

Ponowne uruchamianie i kontrola zmian

Aby przekształcić jednorazową analizę w monitoring, uruchamiaj skrypt według harmonogramu — na przykład codziennie lub raz w tygodniu — i dodawaj datę pobrania do każdego rekordu. Dla każdego filmu przechowuj pary „czas migawki — wartość licznika”. Wtedy można obserwować zmiany publicznych wskaźników między kolejnymi pomiarami, zachowując osobno każdy punkt pomiarowy. Nie nadpisuj starych liczników bieżącymi, bo utracisz historię zmian.

W środowisku produkcyjnym przenieś surowy JSON z lokalnego folderu do magazynu obiektowego lub innego systemu archiwizacji, a znormalizowane wiersze — do bazy z unikalnym kluczem, na przykład złożonym z ID filmu i czasu pobrania. Dodaj dziennik błędów, który nie zawiera tajnego klucza, ograniczenie liczby ponowień oraz powiadomienie o nieudanym żądaniu. Po błędzie tymczasowym można powtórzyć żądanie z opóźnieniem; w razie błędu strukturalnego lepiej zachować odpowiedź i oznaczyć uruchomienie jako wymagające weryfikacji, aby awaria nie doprowadziła do cichego wygenerowania pustego raportu.

Nie traktuj wartości cursor jako stałego identyfikatora badania: to znacznik kontynuacji wyników. Zapisuj go wraz z parametrami odpowiedniego zapytania, używaj wyłącznie do kontynuowania tych wyników i nie mieszaj stron z różnych słów kluczowych. Zapisuj także faktyczną liczbę przetworzonych wyników: żądana wartość count określa oczekiwany rozmiar odpowiedzi, ale nie gwarantuje pełnego pokrycia wszystkich pasujących publikacji.

Jak rozszerzyć proces pracy

Jeśli próbka z wyszukiwania jest zbyt zaszumiona, można osobno monitorować konkretne publiczne profile lub hashtagi. Dokumentacja opisuje trasy /getUserFeed i /getHashtagFeed z parametrami zapytania i stronicowania. Są to odrębne próbki z własnymi zasadami kontynuacji: w przypadku kanału profilu używa się max_cursor, a w przypadku hashtagu — cursor. Podłączaj je jako oddzielne źródła i zapisuj typ źródła oraz parametry, aby nie mieszać wyników wyszukiwania według słowa kluczowego z publikacjami profilu lub hashtagu.

Zespół bez własnej infrastruktury może przesyłać pliki CSV do Arkuszy Google za pomocą API: dokumentacja Google Sheets API opisuje odczyt i zapis wartości komórek. Dodaj osobne arkusze na surowe uruchomienia, znormalizowane filmy i podsumowanie. To wygodne rozwiązanie do wspólnego oznaczania danych; gdy historia stanie się zbyt obszerna dla arkusza, przenieś wiersze do magazynu SQL, zachowując te same pola i informacje o pochodzeniu danych.

W przypadku agenta AI rozsądnym zadaniem jest przygotowanie krótkiego podsumowania zebranych i znormalizowanych rekordów: pogrupowanie opisów, zaproponowanie formatów i wskazanie nietypowych wartości. Nie należy zlecać agentowi formułowania twierdzeń o całej platformie na podstawie niewielkiego zestawu wyników. Przekaż mu okres, listę zapytań i liczbę wierszy, poproś o odwoływanie się do ID filmów oraz zwracanie niepewnych lub brakujących pól jako pustych. Następnie analityk sprawdza przykłady na podstawie zapisanych linków.

Co otrzymasz na koniec

Po skonfigurowaniu procesu zespół otrzymuje możliwy do odtworzenia rejestr znalezionych filmów z identyfikatorami, linkami, opisami, autorami, czasem publikacji i dostępnymi publicznymi licznikami. Zapisana surowa odpowiedź umożliwia weryfikację przekształceń, a plik CSV pozwala szybko sortować filmy, filtrować je według słów kluczowych i porównywać migawki z różnych dat. Można na tej podstawie przygotować cotygodniowe podsumowanie: jakie formaty się powtarzały, które publikacje warto obejrzeć i jakie hipotezy kreatywne przetestować we własnych treściach.

Praktycznym rezultatem nie jest uniwersalny ranking konkurencji, lecz uporządkowana próbka o jasno określonym pochodzeniu. Jej jakość zależy od wybranych zapytań, filtrów i okresu obserwacji. Dlatego zapisuj parametry zbierania danych, ręcznie sprawdzaj poszczególne filmy i odróżniaj dostępne wskaźniki od ich interpretacji. Taki proces pozwala zastąpić rozproszone zakładki porównywalnymi danymi i omawiać kreacje na konkretnych przykładach.

Trasę wyszukiwania i parametry można sprawdzić w oficjalnej dokumentacji jsonscraper, a opis usługi i dostęp do niej znajdują się na stronie TikTok Scraper API. Zacznij od kilku fraz wyszukiwania, zapisz jedną testową odpowiedź i sprawdź jej strukturę przed skonfigurowaniem harmonogramu.