Jak wykrywać filmy TikToka ze wzrostem zaangażowania, nie porównując surowych wyświetleń

Aby sprawdzić, czy konkretne wideo na TikToku zyskuje reakcje, porównaj jego publiczne metryki z poprzednim odczytem. Jednorazowe wyszukiwanie pokazuje skumulowane wyświetlenia i reakcje; ponowne pobranie tych samych znalezionych filmów pozwala sprawdzić zmiany między dwoma uruchomieniami. Poniżej przedstawiono minimalny, działający potok w Pythonie: zapytanie wyszukujące, zapis metryk w pliku CSV i obliczenie różnicy.

Co mierzy taki monitoring?

Skrypt przyda się marketerowi, analitykowi lub programiście, który potrzebuje listy filmów znalezionych na dany temat oraz możliwej do zweryfikowania historii obserwacji. Na przykład zespół może regularnie monitorować filmy o premierze produktu lub określonym zapytaniu odbiorców i sprawdzać, które z nich zyskały więcej wyświetleń, polubień, komentarzy lub udostępnień od poprzedniej kontroli.

Podstawową jednostką porównania jest film identyfikowany przez aweme_id. Dla każdego wpisu zapisuje się czas pobrania, identyfikator, opis, URL, nazwę autora oraz dostępne liczniki. Następnie dwa odczyty są dopasowywane według identyfikatora. Dzięki temu przyrost wyświetleń jednego filmu nie miesza się ze skumulowaną liczbą wyświetleń innego.

Wynik opisuje wyłącznie filmy zwrócone przez konkretne zapytanie wyszukujące przy konkretnym uruchomieniu. Wyniki wyszukiwania mogą się zmieniać, a niektóre pola statystyk mogą być niedostępne. Dlatego warto przechowywać same odczyty wraz z czasem pobrania, a raport traktować jako obserwację już znalezionych filmów, a nie kompletny katalog publikacji na dany temat.

Jak działa pobieranie danych przez API?

W dokumentacji TikTok Scraper API opisano trasę GET /searchVideo. Wyszukiwanie wymaga parametru tekstowego keyword; do parametrów opcjonalnych należą count, region, sort_by i date_posted. Klucz API przekazuje się jako license_key. Dokumentacja podaje adres bazowy https://tiktok.evelode.com.

Odpowiedź zawiera zewnętrzny status oraz obiekt tiktok. W wynikach wyszukiwania filmy mogą znajdować się w tiktok.aweme_list lub wewnątrz tiktok.search_item_list[].aweme_info. Poniższy program obsługuje oba formaty. Metryki są pobierane z statistics, w tym play_count, digg_count, comment_count i share_count; brakującą wartość zapisuje się jako pustą, a nie zastępuje zerem.

Dokumentacja tras wymienia parametr cursor do przewijania wyników wyszukiwania oraz dopuszczalne warianty date_posted i sort_by. W prostym, powtarzalnym monitoringu wystarczy najpierw pobrać jedną stronę wyników i zapisać odpowiedź, a stronicowanie dodać tylko w razie potrzeby. Jeśli jest potrzebne, przekazuj otrzymany kursor bez przekształcania.

Przykład działającego programu w Pythonie

Zainstaluj bibliotekę requests poleceniem python -m pip install requests i ustaw klucz w zmiennej środowiskowej JSONSCRAPER_TIKTOK_LICENSE_KEY. Skrypt przyjmuje frazę wyszukiwania jako argument i dopisuje znalezione odczyty do jednego pliku CSV. Kod jest zgodny z Pythonem 3.8 lub nowszym.

import csv
import os
import sys
from datetime import datetime, timezone
from pathlib import Path

import requests

BASE_URL = "https://tiktok.evelode.com/searchVideo"
CSV_PATH = Path("tiktok_video_snapshots.csv")
FIELDS = [
    "collected_at", "aweme_id", "author", "description", "share_url",
    "play_count", "digg_count", "comment_count", "share_count",
]


def extract_items(payload):
    """Obsługa zaobserwowanych formatów odpowiedzi wyszukiwania."""
    data = payload.get("tiktok") or {}
    items = data.get("aweme_list") or []
    if items:
        return items

    found = []
    for result in data.get("search_item_list") or []:
        info = result.get("aweme_info")
        if info:
            found.append(info)
    return found


def main():
    key = os.environ.get("JSONSCRAPER_TIKTOK_LICENSE_KEY")
    if not key:
        raise SystemExit("Najpierw ustaw JSONSCRAPER_TIKTOK_LICENSE_KEY")
    if len(sys.argv) < 2:
        raise SystemExit('Użycie: python collect.py "fraza wyszukiwania"')

    params = {
        "license_key": key,
        "keyword": sys.argv[1],
        "count": 20,
        "region": "US",
        "sort_by": "relevance",
        "date_posted": "this-week",
    }
    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")
    data = payload.get("tiktok") or {}
    items = extract_items(payload)
    collected_at = datetime.now(timezone.utc).isoformat()

    rows = []
    for item in items:
        stats = item.get("statistics") or {}
        author = item.get("author") or {}
        rows.append({
            "collected_at": collected_at,
            "aweme_id": item.get("aweme_id"),
            "author": author.get("unique_id") or author.get("nickname"),
            "description": item.get("desc"),
            "share_url": item.get("share_url"),
            "play_count": stats.get("play_count"),
            "digg_count": stats.get("digg_count"),
            "comment_count": stats.get("comment_count"),
            "share_count": stats.get("share_count"),
        })

    write_header = not CSV_PATH.exists()
    with CSV_PATH.open("a", newline="", encoding="utf-8") as file:
        writer = csv.DictWriter(file, fieldnames=FIELDS)
        if write_header:
            writer.writeheader()
        writer.writerows(rows)

    print("Zapisano", len(rows), "zwróconych filmów")
    print("has_more:", data.get("has_more"), "cursor:", data.get("cursor"))


if __name__ == "__main__":
    main()

Uruchom program, na przykład poleceniem python collect.py "zapytanie o produkt". Biblioteka umieszcza klucz w parametrach URL; skrypt nie wyświetla go w terminalu. Nie zapisuj pełnego URL zapytania w publicznie dostępnych logach, ponieważ zawiera klucz. W systemie produkcyjnym korzystaj z magazynu sekretów i ogranicz dostęp do pliku z odczytami.

Jak obliczyć przyrost między uruchomieniami?

Skrypt celowo zapisuje wszystkie obserwacje, zamiast nadpisywać wcześniejsze wartości. Poniższy krótki analizator dopasowuje dwie ostatnie obserwacje każdego filmu i wyświetla różnice w licznikach. Jeśli wartość którejś metryki jest niedostępna w jednym z dwóch wpisów, wynik jest oznaczany jako niedostępny.

import csv
from collections import defaultdict
from pathlib import Path

rows_by_video = defaultdict(list)
with Path("tiktok_video_snapshots.csv").open(encoding="utf-8", newline="") as file:
    for row in csv.DictReader(file):
        if row["aweme_id"]:
            rows_by_video[row["aweme_id"]].append(row)

metrics = ("play_count", "digg_count", "comment_count", "share_count")
for video_id, snapshots in rows_by_video.items():
    snapshots.sort(key=lambda row: row["collected_at"])
    if len(snapshots) < 2:
        continue
    previous, latest = snapshots[-2], snapshots[-1]
    changes = {}
    for metric in metrics:
        old, new = previous[metric], latest[metric]
        changes[metric] = int(new) - int(old) if old and new else None
    print(video_id, changes, latest["share_url"])

Różnica to wynik odejmowania dwóch zapisanych wartości, a nie tempo wzrostu w gwarantowanym przedziale. Jeśli uruchomienia odbywają się w różnych odstępach, dodaj obliczanie czasu między wartościami collected_at i porównuj przyrost z uwzględnieniem faktycznego okresu. Liczniki mogą zmieniać się między obserwacjami; zapisane znaczniki czasu pokazują, kiedy pobrano użyte wartości.

Jak zautomatyzować i interpretować raport?

Aby przygotowywać codzienny raport, uruchamiaj pobieranie za pomocą harmonogramu zadań na serwerze lub w CI, określ stałą listę fraz wyszukiwania i zapisuj dane w pliku CSV albo przesyłaj wiersze do bazy danych. Przy kolejnym uruchomieniu usuń duplikaty w obrębie jednego odczytu według aweme_id, jeśli wyniki zawierają powtórzenia. Przechowuj surowy JSON razem ze znormalizowanymi kolumnami, by ułatwić ponowne przetwarzanie po zmianie schematu raportu.

W tabeli warto umieścić identyfikator i URL filmu, autora, opis, czas pobrania oraz różnice dla poszczególnych metryk. Sortowanie według przyrostu wyświetleń odpowiada na pytanie o zasięg, a przyrost komentarzy lub udostępnień pomaga wychwycić inny rodzaj reakcji. Nie sprowadzaj tych wskaźników do jednego rankingu bez określenia jasnej reguły: każdy licznik oznacza coś innego.

Harmonogram może wysyłać raport e-mailem, do arkusza lub kanału wewnętrznego, ale ten krok wykonuje Twoja infrastruktura — powyższy przykład jedynie pobiera i analizuje dane. Aby pobrać więcej wyników, możesz przechodzić przez kolejne strony, zapisując kursor i kończąc pętlę, gdy API poinformuje o braku następnych stron. Kursor wyszukiwania jest nieprzezroczystą wartością zwróconą w odpowiedzi; nie obliczaj go samodzielnie. Nawet przejście przez wszystkie strony opisuje zwrócone wyniki, ale nie gwarantuje kompletnej listy wszystkich pasujących publikacji.

Oczekiwanym praktycznym rezultatem jest odtwarzalny dziennik obserwacji i tabela zmian dla znalezionych filmów. Ułatwia to zauważenie, które publikacje zmieniły publiczne liczniki między kontrolami, oraz przekazanie konkretnych linków specjaliście do analizy treści. Szczegóły produktu i dostęp do API można znaleźć na stronie TikTok Scraper API.

Co sprawdzić przed uruchomieniem harmonogramu?

• Przed przetwarzaniem obiektu tiktok upewnij się, że zewnętrzny status odpowiedzi to ok.
• Sprawdź oba warianty struktury elementów wyników wyszukiwania; brak listy powinien skutkować pustym zbiorem, a nie błędem.
• Zapisuj pierwotne wartości i znaczniki czasu. Brakująca metryka ma pozostać pusta.
• Używaj tych samych zapytań i parametrów, aby ułatwić porównanie odczytów; zmiany tych ustawień odnotowuj przy raporcie.
• Kontroluj częstotliwość uruchomień, błędy HTTP i rozmiar historii, a także przestrzegaj obowiązujących zasad platformy i wymogów dotyczących przetwarzania danych.

Podsumowując, aby uzyskać obserwowalny wynik, wystarczy powtarzać to samo wyszukiwanie, identyfikować filmy za pomocą aweme_id i porównywać zapisane metryki w czasie. To podejście odpowiada na konkretne, praktyczne pytanie — które z już znalezionych filmów zmieniły publiczne liczniki między dwiema kontrolami — a zarazem zachowuje dane źródłowe do audytu i dalszego przetwarzania.