TikTok: zamień wyniki wyszukiwania w cotygodniową listę tematów dla wsparcia

Zespół wsparcia potrzebuje listy publicznych filmów z TikToka, w których użytkownicy rozmawiają o niezrozumiałej funkcji lub zadają pytania dotyczące produktu. Ręczne wyszukiwanie trudno powtarzać w ten sam sposób, a odpowiedzi API wyszukiwania mogą przechowywać filmy w różnych miejscach JSON. Poniżej znajduje się prosty skrypt w Pythonie, który pobiera wyniki dla słów kluczowych, łączy obie struktury, usuwa duplikaty na podstawie identyfikatora i zapisuje znalezione rekordy w pliku CSV.

Jaki wynik zapewnia skrypt

Otrzymasz tabelę z identyfikatorem filmu, linkiem, opisem, czasem publikacji, autorem i dostępnymi licznikami reakcji. Zespół wsparcia lub marketingu może ręcznie oznaczyć tematy, które wymagają odpowiedzi, aktualizacji instrukcji lub sprawdzenia we własnym systemie CRM. Tabela odzwierciedla wyłącznie wyniki zwrócone przez API dla podanych zapytań; traktuj ją jako roboczą próbkę do analizy, a nie wyczerpujący katalog wszystkich dyskusji.

Skrypt służy do zbierania i wstępnego porządkowania danych. Nie określa automatycznie, czy opis zawiera pytanie, skargę czy żart: taką etykietę najlepiej dodać po ręcznej weryfikacji albo za pomocą osobnego klasyfikatora, zapisując tekst źródłowy i uzasadnienie decyzji.

Co wysyłać i jak zbudowana jest odpowiedź

Do wyszukiwania filmów jsonscraper dokumentuje trasę GET /searchVideo na hoście https://tiktok.evelode.com. Wymaganym parametrem jest keyword; można też przekazać count, region, sortowanie, okres publikacji i kursor następnej strony. Można na przykład powtarzać wyszukiwanie dla kilku wcześniej ustalonych fraz: nazwy funkcji, popularnego sformułowania błędu i krótkiego pytania o konfigurację. Parametry i ich dopuszczalne wartości wymieniono w dokumentacji TikTok API.

Wyszukiwanie ma istotną cechę, którą musi uwzględniać parser: tablica aweme_list może być pusta, a znalezione obiekty mogą znajdować się w search_item_list, z polem aweme_info wewnątrz każdego z nich. Dlatego poniższy program obsługuje obie formy. Przykładową odpowiedź i pola zaobserwowane podczas weryfikacji 25 października 2026 roku przedstawiono w specyfikacji źródłowej jsonscraper; pola statystyk mogą nie występować, więc kod nie wstawia zmyślonych wartości.

Przygotuj klucz i listę zapytań

Zapisz klucz w zmiennej środowiskowej JSONSCRAPER_TIKTOK_LICENSE_KEY, a nie w pliku źródłowym. W powłoce systemu Linux lub macOS zrobisz to tak:

export JSONSCRAPER_TIKTOK_LICENSE_KEY="twój_klucz"

Zainstaluj bibliotekę do wysyłania zapytań i przygotuj plik queries.txt, zawierający po jednym wyrażeniu wyszukiwania w każdym wierszu, na przykład nazwa produktu konfiguracja i nazwa funkcji nie działa. Wybieraj sformułowania odpowiednie dla języka odbiorców i przechowuj je na osobnej liście, aby w cotygodniowych zestawieniach porównywać te same zapytania.

python -m pip install requests

Zbierz i ujednolić znalezione filmy

Przykład działa z Pythonem 3.8 lub nowszym. Wysyła jedno zapytanie dla każdej frazy z limitem wyników, sprawdza błędy HTTP oraz status w odpowiedzi, a następnie zapisuje wyłącznie pola faktycznie obecne w danych. Powtarzające się wyniki są łączone według aweme_id, a wszystkie zapytania, dla których znaleziono dany film, zapisywane są w polu keywords. Osobne pole collected_at_utc zapisuje czas pobrania danych, co ułatwia porównywanie kolejnych uruchomień.

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

import requests

BASE_URL = "https://tiktok.evelode.com/searchVideo"
API_KEY = os.environ.get("JSONSCRAPER_TIKTOK_LICENSE_KEY")

if not API_KEY:
    raise SystemExit("Ustaw zmienną JSONSCRAPER_TIKTOK_LICENSE_KEY")


def get_items(tiktok):
    """Wyodrębnia filmy z obu udokumentowanych struktur odpowiedzi wyszukiwania."""
    items = list(tiktok.get("aweme_list") or [])
    for entry in tiktok.get("search_item_list") or []:
        info = entry.get("aweme_info") if isinstance(entry, dict) else None
        if info:
            items.append(info)
    return items


with open("queries.txt", encoding="utf-8") as query_file:
    queries = [line.strip() for line in query_file if line.strip()]

collected_at = datetime.now(timezone.utc).isoformat()
videos = {}

for keyword in queries:
    response = requests.get(
        BASE_URL,
        params={
            "license_key": API_KEY,
            "keyword": keyword,
            "count": 30,
            "region": "US",
            "sort_by": "relevance",
        },
        timeout=30,
    )
    response.raise_for_status()
    payload = response.json()

    if payload.get("status") != "ok":
        print("Nieprawidłowy status API dla zapytania:", keyword, file=sys.stderr)
        continue

    tiktok = payload.get("tiktok") or {}
    for item in get_items(tiktok):
        video_id = item.get("aweme_id")
        if not video_id:
            continue

        if video_id not in videos:
            author = item.get("author") or {}
            stats = item.get("statistics") or {}
            videos[video_id] = {
                "aweme_id": video_id,
                "keywords": [keyword],
                "description": item.get("desc"),
                "share_url": item.get("share_url"),
                "create_time": item.get("create_time"),
                "author": author.get("unique_id") or author.get("nickname"),
                "play_count": stats.get("play_count"),
                "digg_count": stats.get("digg_count"),
                "comment_count": stats.get("comment_count"),
                "share_count": stats.get("share_count"),
                "collected_at_utc": collected_at,
            }
        elif keyword not in videos[video_id]["keywords"]:
            videos[video_id]["keywords"].append(keyword)

columns = [
    "aweme_id", "keywords", "description", "share_url", "create_time",
    "author", "play_count", "digg_count", "comment_count", "share_count",
    "collected_at_utc",
]
with open("tiktok_support_review.csv", "w", newline="", encoding="utf-8-sig") as output:
    writer = csv.DictWriter(output, fieldnames=columns)
    writer.writeheader()
    for video in videos.values():
        row = dict(video)
        row["keywords"] = " | ".join(row["keywords"])
        writer.writerow(row)

print("Zapisano znalezione unikalne filmy:", len(videos))

Zapytanie jest wysyłane z użyciem parametru params, dzięki czemu biblioteka prawidłowo koduje tekstowe frazy w adresie URL. Klucz jest przekazywany jako parametr zapytania, zgodnie z dokumentacją; nie wypisuj pełnego adresu URL zapytania w dzienniku aplikacji. Na potrzeby diagnostyki zapisuj kod odpowiedzi HTTP, wyszukiwaną frazę i czas uruchomienia, ale pomijaj sekrety oraz dane osobowe, które nie są potrzebne do realizacji zadania.

Jak czytać CSV, by uniknąć błędnych wniosków

Kolumna keywords zawiera wszystkie frazy, dla których znaleziono film; collected_at_utc pozwala odróżnić czas publikacji od czasu pobrania. Identyfikator ułatwia usuwanie duplikatów, a link pozwala na weryfikację przez człowieka. Pusty licznik oznacza, że w danej odpowiedzi brakowało tego pola, a nie że jego wartość wynosiła zero.

Na potrzeby wstępnej selekcji dodaj do roboczej kopii pliku CSV kolumny temat, typ sygnału, wymagana odpowiedź i link do materiału wewnętrznego. Warianty tematów powinny odpowiadać Twojemu produktowi, na przykład instalacja, płatności, zgodność lub rozwiązywanie problemów. Taki układ zamienia zestawienie w kolejkę do analizy i pozwala zweryfikować decyzję na podstawie oryginalnego filmu.

Uruchom zbieranie danych według harmonogramu

Najpierw uruchom skrypt ręcznie i sprawdź kilka wierszy oraz linków. Następnie dodaj go do crona, zadania CI lub scenariusza automatyzacji, który potrafi uruchomić proces Pythona. W przypadku regularnych raportów zachowuj każdą wersję zestawienia albo dodawaj wiersze do magazynu danych z unikatowym kluczem filmu i datą migawki. Dzięki temu zespół odróżni nowe znalezione publikacje od ponownych obserwacji i prześledzi zmiany dostępnych liczników między kolejnymi uruchomieniami.

Parametr cursor służy do przewijania wyników; należy przekazać do niego wartość zwróconą przez poprzednie wywołanie. W powyższym minimalnym przykładzie celowo pominięto paginację: ograniczony zestaw zapytań łatwiej sprawdzić i odtworzyć. Jeśli dodasz kolejne strony, przechowuj kursor bez interpretowania jego zawartości, kończ działanie na podstawie flagi informującej o dostępności dalszych wyników i ustal górny limit wywołań na jedno uruchomienie. API zwraca próbkę wyników; nie traktuj liczby wierszy jako pełnego obrazu treści na TikToku.

Praktyczne ograniczenia zastosowania

Wyniki wyszukiwania nadają się do znajdowania filmów na podstawie sformułowań znanych już zespołowi. Pomagają zebrać materiał do klasyfikacji, ale nie zastępują zgłoszeń przychodzących, analityki własnej witryny ani weryfikacji kontekstu filmu. Opis może nie oddawać istoty nagrania, a dostępne wskaźniki odzwierciedlają stan danych w chwili ich pobrania. Oznaczenia tematów i wnioski zapisuj oddzielnie od pól źródłowych, aby pracownicy mogli ponownie ocenić klasyfikację.

Przed rozpoczęciem regularnego monitorowania ustal, kto ma dostęp do zestawienia, jak długo dane będą przechowywane i w jakim celu wykorzystuje się publiczne informacje. Przechowuj tylko pola potrzebne do analizy produktu i zamiast kopiować pliki multimedialne, preferuj linki do oryginalnych publikacji. Aby wysłać zapytanie i sprawdzić dostępne warianty integracji, zapoznaj się ze stroną TikTok Scraper API oraz dokumentacją trasy wyszukiwania.