TikTok: proměňte výsledky hledání v týdenní seznam témat pro podporu

Tým podpory potřebuje seznam veřejných videí TikTok, v nichž lidé diskutují o nejasné funkci nebo se ptají na produkt. Ruční hledání se obtížně opakuje stejným způsobem a odpovědi API pro vyhledávání mohou mít videa uložená v různých částech JSON. Níže je jednoduchý Pythonový skript, který vyhledá výsledky podle klíčových slov, sjednotí obě struktury, odstraní duplicity podle ID a uloží nalezené záznamy do CSV.

Jaký výsledek skript poskytne

Výstupem bude tabulka s ID videa, odkazem, popisem, časem zveřejnění, autorem a dostupnými počty reakcí. Podpora nebo marketing v ní mohou ručně označit témata, která vyžadují odpověď, aktualizaci návodu nebo ověření ve vlastní CRM. Tabulka zachycuje výsledky vrácené API pro zadané dotazy; považujte ji za pracovní vzorek k prozkoumání, nikoli za úplný katalog všech diskusí.

Skript řeší sběr a prvotní třídění. Automaticky nerozpozná, zda je popis dotaz, stížnost nebo vtip: takové označení je lepší přidat po ruční kontrole, případně pomocí samostatného klasifikátoru, přičemž se zachová původní text i důvod rozhodnutí.

Co požadovat a jak je odpověď strukturována

Pro vyhledávání videí jsonscraper dokumentuje GET trasu /searchVideo na hostiteli https://tiktok.evelode.com. Povinným parametrem je keyword; lze předat také count, region, řazení, období zveřejnění a kurzor další stránky. Vyhledávání lze například opakovat pro několik předem stanovených frází: název funkce, běžnou formulaci chybového hlášení a krátký dotaz na nastavení. Parametry a jejich povolené hodnoty uvádí příručka k TikTok API.

Vyhledávání má pro parser jednu důležitou zvláštnost: pole aweme_list může být prázdné, zatímco nalezené objekty jsou v search_item_list a každý z nich obsahuje aweme_info. Níže uvedený zpracovatel proto ověřuje obě podoby. Ukázková odpověď a pole zaznamenaná při kontrole 25. října 2026 jsou uvedena v primární specifikaci jsonscraper; statistická pole mohou chybět, proto kód nedoplňuje vymyšlené hodnoty.

Připravte klíč a seznam dotazů

Uložte klíč do proměnné prostředí JSONSCRAPER_TIKTOK_LICENSE_KEY, nikoli do zdrojového souboru. V příkazovém řádku Linuxu nebo macOS to lze provést takto:

export JSONSCRAPER_TIKTOK_LICENSE_KEY="váš_klíč"

Nainstalujte knihovnu pro práci s požadavky a vytvořte soubor queries.txt s jedním vyhledávacím výrazem na řádek, například název produktu nastavení a název funkce nefunguje. Výrazy vybírejte podle jazyka cílového publika a udržujte je v samostatném seznamu, aby bylo možné v týdenních výstupech porovnávat stejné dotazy.

python -m pip install requests

Shromážděte a sjednoťte nalezená videa

Příklad je kompatibilní s Pythonem 3.8+. Pro každou frázi odešle jeden požadavek s limitem výsledků, kontroluje chyby HTTP i stav v odpovědi a poté ukládá pouze skutečně přítomná pole. Duplicitní shody se slučují podle aweme_id a všechny dotazy, při nichž bylo video nalezeno, se zapisují do pole keywords. Samostatné pole collected_at_utc zaznamenává čas získání dat, aby bylo možné porovnávat další spuštění.

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("Nastavte JSONSCRAPER_TIKTOK_LICENSE_KEY")


def get_items(tiktok):
    """Extrahuje videa z obou dokumentovaných podob odpovědi vyhledávání."""
    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("Neúspěšný stav API pro dotaz:", 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("Uloženo jedinečných nalezených videí:", len(videos))

Požadavek se odesílá pomocí parametru params, takže knihovna správně zakóduje textové fráze v URL. Klíč je přitom v parametru query, jak je popsáno v dokumentaci; nevypisujte úplnou URL požadavku do aplikačního protokolu. Pro diagnostiku ukládejte stavový kód HTTP, vyhledávací frázi a čas spuštění, ale vynechte tajné údaje a osobní data, která nejsou pro daný úkol potřeba.

Jak číst CSV a nedělat unáhlené závěry

Sloupec keywords obsahuje všechny fráze, při nichž bylo video nalezeno; collected_at_utc umožňuje odlišit čas zveřejnění od času sběru. ID se hodí k odstranění duplicit a odkaz k ověření člověkem. Prázdné počítadlo znamená, že pole v konkrétní odpovědi chybělo, nikoli že jeho hodnota byla nula.

Pro první třídění přidejte do pracovní kopie CSV sloupce téma, typ signálu, vyžaduje odpověď a odkaz na interní materiál. Možnosti témat by měly odpovídat vašemu produktu, například instalace, platba, kompatibilita nebo řešení chyby. Takové uspořádání promění export ve frontu k posouzení a zároveň umožní ověřit rozhodnutí podle původního videa.

Spusťte sběr podle plánu

Nejprve skript spusťte ručně a zkontrolujte několik řádků a odkazů. Poté jej přidejte do cron, CI úlohy nebo automatizačního scénáře, který umí spustit proces Pythonu. Pro pravidelné přehledy ukládejte každý export nebo přidávejte řádky do úložiště s jedinečným klíčem videa a datem snímku. Tým tak rozliší nově nalezené příspěvky od opakovaných pozorování a může sledovat, jak se mezi jednotlivými spuštěními mění dostupné počty.

Parametr cursor slouží k procházení výsledků; je nutné ho předat z odpovědi předchozího volání. V této minimální variantě záměrně není stránkování zahrnuto: omezenou sadu dotazů lze snáze ověřit a zopakovat. Pokud stránky přidáte, ukládejte kurzor jako neprůhlednou hodnotu, zastavte se podle příznaku dostupnosti pokračování a stanovte maximální počet volání na jedno spuštění. Požadavek API vrací vzorek; počet řádků nevykládejte jako úplné pokrytí TikToku.

Praktické meze použití

Výsledky vyhledávání se hodí k objevování videí podle formulací, které tým už zná. Pomáhají shromáždit materiál pro klasifikaci, ale nenahrazují příchozí požadavky, analytiku vlastního webu ani kontrolu kontextu videa. Popis nemusí vystihovat obsah videa a dostupné metriky zachycují stav dat v okamžiku získání. Témata a závěry zaznamenávejte odděleně od původních polí, aby zaměstnanci mohli klasifikaci znovu posoudit.

Před zahájením pravidelného monitorování určete, kdo má k exportu přístup, jak dlouho se data uchovávají a k jakému účelu se veřejné informace používají. Uchovávejte pouze pole potřebná k posouzení produktu a upřednostňujte odkazy na původní příspěvky před kopírováním mediálních souborů. Informace o požadavcích a dostupných možnostech integrace najdete na stránce TikTok Scraper API a v dokumentaci vyhledávací trasy.