Jak hodnotit kvalitu leadů z veřejných videí na TikToku: podrobný postup v Pythonu

Obchodní tým dostává z různých kanálů stále stejnou otázku: jaké problémy se potenciální zákazníci už snaží řešit? Ruční vyhledávání na TikToku přináší spoustu videí, ale po týdnu je obtížné ho zopakovat, porovnat výsledky a vysvětlit, proč se konkrétní video dostalo do přehledu. Pro menší průzkum lze veřejné výsledky několika přesně formulovaných dotazů proměnit v reprodukovatelný datový tok: uložit původní odpověď, vybrat údaje o videu a autorovi, odstranit duplicity a samostatně vyhodnotit známky nákupního záměru nebo výběru produktu.

Níže najdete funkční postup v Pythonu s TikTok Scraper API od jsonscraper. Hodí se například službě pro střih videa, která chce zjistit, jak tvůrci popisují potíže s titulky, šablonami a exportem. Skript shromažďuje vrácené výsledky vyhledávání a analytik následně ověří klasifikaci a rozhodne, které formulace využít při průzkumu publika. Jde o způsob, jak organizovat sledování veřejného obsahu, nikoli o automatický výpočet všech uživatelů se záměrem nakoupit.

Problém: dotazy publika existují, ale průzkum se obtížně opakuje

Při ručním průzkumu se snadno ztratí kontext. Jeden pracovník hledá „jak přidat titulky“, druhý „automatické titulky pro Reels“ a třetí si ukládá jen videa, která se mu líbí. Výsledná tabulka směšuje různé dotazy, data, metriky a kritéria výběru. Když vedení požádá o zopakování analýzy nebo srovnání dvou týdnů, je nutné znovu sestavit nejen výsledky, ale i samotný postup vyhledávání.

Užitečnější je předem určit jednotku pozorování: nalezené video s textem popisku, identifikátorem, odkazem, autorem a dostupnými veřejnými metrikami. U každého videa se uloží původní vyhledávací dotaz a čas sběru. Pak lze samostatně odpovídat na otázky: jaké formulace se objevují, jaké problémy jsou zmiňovány, která videa získala více veřejných reakcí a co se změnilo mezi uloženými snímky.

Jako příklad si vezměme společnost, která vyvíjí nástroj na tvorbu titulků a krátkých videí. Potřebuje najít veřejná videa, v nichž tvůrci přímo mluví o ručním přepisu, chybách rozpoznávání řeči, časování titulků nebo přípravě obsahu pro více platforem. Samotná označení „lead“ a „zákazník“ by se neměla autorovi přisuzovat na základě jediného videa: výzkumník může obsah seřadit podle pozorovatelných znaků a závěry následně ručně ověřit.

Schéma řešení: vyhledávání, zaznamenání, čištění, vyhodnocení

Postup má čtyři kroky. Nejprve tým sestaví menší slovník vyhledávacích dotazů, z nichž každý odpovídá konkrétnímu úkolu publika. Pak skript vyhledá videa a uloží úplnou odpověď JSON. Ve třetím kroku normalizuje různé struktury odpovědi do jednotného záznamu pro každé video a odstraní duplicity podle identifikátoru. Nakonec pravidla nebo samostatný klasifikátor s umělou inteligencí přiřadí prioritu pro ruční kontrolu a zaznamená důvod hodnocení.

Rozdělení těchto kroků je důležité pro reprodukovatelnost. Surová odpověď pomáhá zkoumat změny polí nebo chyby normalizace. Normalizovaná tabulka se hodí k filtrování a vizualizaci. Samostatná tabulka hodnocení umožňuje měnit pravidla bez opakovaného volání API, pokud uložená data takové opětovné zpracování umožňují a odpovídá pravidlům uchovávání dat v týmu.

Jako základní dotazy lze použít „chyby automatických titulků“, „jak rychle přidat titulky“ a „střih krátkých videí pro firmy“. Jsou to pouze příklady slovníku: formulace je třeba přizpůsobit jazyku publika a produktu. Dotazy ukládejte spolu s výsledky, protože různá slova vytvářejí různé výběry.

Co nabízí TikTok Scraper API

Ve zveřejněné dokumentaci jsonscraper je pro vyhledávání videí uvedena metoda GET na cestě /searchVideo se základní adresou https://tiktok.evelode.com. Povinným parametrem je keyword; mezi dokumentované doplňkové parametry patří count, cursor, region, date_posted, sort_by a cache_timeout. Například parametr sort_by přijímá dokumentované hodnoty most-liked, relevance a date-posted, zatímco date_posted hodnoty jako this-week nebo all-time. Přesný seznam parametrů a účel této cesty uvádí přehled koncových bodů TikTok API.

Klíč se předává jako parametr dotazu license_key. V následujícím příkladu se načítá z proměnné prostředí JSONSCRAPER_TIKTOK_LICENSE_KEY, aby tajný údaj nebyl uložen v kódu ani vypisován do protokolu. Při ověřování a výběru parametrů se řiďte aktuálními podmínkami svého přístupu; stránka TikTok Scraper API popisuje produkt a obsahuje odkazy na ukázku a dokumentaci.

Odpověď vyhledávání je nutné zpracovávat s ohledem na její strukturu, nikoli předpokládat jedinou možnou podobu pole. V ověřeném příkladu API vracelo stav na nejvyšší úrovni a objekt tiktok; videa se mohou nacházet v tiktok.aweme_list a u výsledků vyhledávání se objevuje také tiktok.search_item_list[].aweme_info. Ověřujte obě podoby. V nalezených objektech jsou podle dostupnosti uvedeny identifikátor videa, popisek, odkaz, čas zveřejnění, informace o autorovi a statistiky, například počet zhlédnutí, lajků, komentářů a sdílení. S metrikami a poli počítejte jako s nepovinnými: kód nesmí doplňovat smyšlené nuly, pokud hodnota chybí.

Stránkování vyhledávání využívá cursor. Pokud skript pokračuje ve výpisu, musí získanou hodnotu předat jako neprůhledný token dalšího požadavku, nikoli ji sám vypočítat. Pro první prototyp je rozumné omezit sběr na jednu stránku pro každý dotaz: usnadní to kontrolu a zajistí předvídatelnou zátěž. Později lze přidat stránkování s limitem počtu stránek a ochranou před opakovaným kurzorem.

Příprava prostředí

Příklad používá Python 3.8 nebo novější a standardní knihovnu. Nastavte klíč v prostředí, například v shellu macOS nebo Linuxu:

export JSONSCRAPER_TIKTOK_LICENSE_KEY="váš_klíč"
python tiktok_demand.py

Ve Windows PowerShell lze proměnnou nastavit takto:

$env:JSONSCRAPER_TIKTOK_LICENSE_KEY="váš_klíč"
python .\tiktok_demand.py

Skript odešle samostatný požadavek pro každé klíčové slovo. Ověří chyby HTTP, odpověď JSON a vnější stav, poté načte objekty z obou potvrzených variant pole. Surové odpovědi zapisuje po jednotlivých řádcích do souboru JSONL: každý záznam obsahuje dotaz, čas pozorování a původní odpověď. Druhá část vytvoří CSV s jednotnými poli. Soubor s klíčem není součástí kódu a obsah tajného údaje se nevypisuje.

Příklad: sběr a normalizace výsledků vyhledávání

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

BASE_URL = "https://tiktok.evelode.com/searchVideo"
QUERIES = [
    "chyby automatických titulků",
    "jak rychle přidat titulky",
    "střih krátkých videí pro firmy",
]


def extract_videos(payload):
    """Podporuje obě pozorované struktury odpovědi vyhledávání."""
    tiktok = payload.get("tiktok") or {}
    videos = []

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

    search_items = tiktok.get("search_item_list") or []
    if isinstance(search_items, list):
        for item in search_items:
            if not isinstance(item, dict):
                continue
            video = item.get("aweme_info")
            if isinstance(video, dict):
                videos.append(video)

    return videos


def fetch(query, license_key):
    params = {
        "keyword": query,
        "count": 20,
        "sort_by": "relevance",
        "date_posted": "this-month",
        "region": "US",
        "license_key": license_key,
    }
    url = BASE_URL + "?" + urlencode(params)
    request = Request(url, headers={"Accept": "application/json"})

    try:
        with urlopen(request, timeout=45) as response:
            payload = json.loads(response.read().decode("utf-8"))
    except HTTPError as exc:
        raise RuntimeError("API returned HTTP status {}".format(exc.code)) from exc
    except (URLError, TimeoutError, json.JSONDecodeError) as exc:
        raise RuntimeError("Could not complete or parse API request") from exc

    if payload.get("status") != "ok":
        raise RuntimeError("API response status was not ok")
    return payload


def metric(statistics, key):
    value = statistics.get(key)
    return value if isinstance(value, (int, float)) else ""


def main():
    license_key = os.environ.get("JSONSCRAPER_TIKTOK_LICENSE_KEY")
    if not license_key:
        raise SystemExit("Set JSONSCRAPER_TIKTOK_LICENSE_KEY in the environment")

    raw_path = Path("tiktok_raw.jsonl")
    csv_path = Path("tiktok_videos.csv")
    seen_ids = set()
    rows = []

    with raw_path.open("a", encoding="utf-8") as raw_file:
        for query in QUERIES:
            observed_at = datetime.now(timezone.utc).isoformat()
            payload = fetch(query, license_key)
            raw_file.write(json.dumps({
                "query": query,
                "observed_at": observed_at,
                "response": payload,
            }, ensure_ascii=False) + "\n")

            for video in extract_videos(payload):
                video_id = video.get("aweme_id")
                if not video_id or video_id in seen_ids:
                    continue
                seen_ids.add(video_id)

                author = video.get("author") or {}
                stats = video.get("statistics") or {}
                rows.append({
                    "query": query,
                    "observed_at": observed_at,
                    "video_id": video_id,
                    "created_at": video.get("create_time", ""),
                    "description": video.get("desc", ""),
                    "share_url": video.get("share_url", ""),
                    "author_username": author.get("unique_id", ""),
                    "author_nickname": author.get("nickname", ""),
                    "views": metric(stats, "play_count"),
                    "likes": metric(stats, "digg_count"),
                    "comments": metric(stats, "comment_count"),
                    "shares": metric(stats, "share_count"),
                })
            time.sleep(1)

    columns = [
        "query", "observed_at", "video_id", "created_at", "description",
        "share_url", "author_username", "author_nickname", "views",
        "likes", "comments", "shares",
    ]
    with csv_path.open("w", newline="", encoding="utf-8") as csv_file:
        writer = csv.DictWriter(csv_file, fieldnames=columns)
        writer.writeheader()
        writer.writerows(rows)

    print("Saved {} unique returned videos to {}".format(len(rows), csv_path))


if __name__ == "__main__":
    main()

Hodnota count zde označuje požadovanou velikost výběru pro jeden dotaz. Skript nepředpokládá, že API musí vrátit přesně tolik položek: skutečný počet řádků závisí na odpovědi. Pauza mezi požadavky je jednoduchým opatřením pro řízení tempa spouštění, nikoli tvrzením o limitu nebo požadavku služby. Při průmyslovém plánování přidejte omezený počet opakovaných pokusů, sledování chyb a pravidla pro přípustnou četnost požadavků podle podmínek svého tarifu.

Jak číst výslednou tabulku

V CSV představuje jeden řádek jedno jedinečné vrácené video nalezené pomocí některého z dotazů. Pole query ukazuje původ záznamu, observed_at čas snímku a video_id slouží jako klíč pro odstranění duplicit. Popisek a odkaz pomáhají analytikovi ověřit kontext, zatímco veřejné počitadla umožňují posoudit odezvu v době sběru. Pro dlouhodobé porovnávání používejte samostatná pozorování: pokud chcete sledovat změny metrik, nepřepisujte jejich historii.

Počty zhlédnutí, lajků, komentářů a sdílení představují snímek veřejných statistik, které API vrátilo v okamžiku požadavku. U jednotlivých objektů mohou chybět, proto prázdná hodnota v CSV označuje chybějící číselné pole v odpovědi. Liší se od nuly a při výpočtu souhrnů by se s ní mělo zacházet samostatně. Nalezené výsledky navíc představují výběr pro konkrétní slova, region, časový filtr a parametry požadavku. Popisují právě získaná videa, nikoli veškerý obsah nebo publikum platformy.

Pro předběžné posouzení potenciální relevance lze sestavit přehledné schéma pravidel: shody s formulacemi problémů, zmínky o používaném nástroji, dotazy na cenu nebo srovnání a konkrétní pracovní scénář. Je lepší ukládat samostatné znaky a vysvětlení hodnocení než jen neprůhledné skóre. Video s dotazem na přesnost automatického přepisu lze například označit „ověřit: řeší se kvalita“, zatímco video s obecnými radami k obsahu jako „nízká tematická relevance“.

Zapojení AI bez toho, aby rozhodovala za vás

Jakmile se shromáždí dostatečný výběr, může model pomoci označit popisky podle předem stanoveného schématu: problém, zmíněný nástroj, tón dotazu a přítomnost signálu výběru produktu. Modelu předávejte jen potřebná pole, například text popisku a identifikátor záznamu, a požadujte pevně definovaný JSON se štítky a stručným zdůvodněním. Vedle původního řádku uchovávejte verzi instrukcí, model a výsledek, abyste mohli označování zopakovat nebo namátkově zkontrolovat člověkem.

Užitečný pokyn pro klasifikátor by měl omezovat závěry na pozorovatelné znaky. Požádejte ho, aby určil, zda text obsahuje konkrétní problém s titulky, žádost o doporučení nástroje nebo popis pracovního postupu. Pokud je údajů málo, nabídněte kategorii „nedostatek kontextu“. Model by z jediného veřejného videa neměl odvozovat totožnost autora, jeho nákupní záměry ani demografické charakteristiky. Výsledkem má být seznam témat k analýze, nikoli seznam lidí pro automatické kontaktování.

Chcete-li posoudit kvalitu označování, vyberte náhodný podvzorek a stejné kategorie označte ručně. Porovnejte shodu u jednotlivých štítků a prozkoumejte chyby: model může například zaměnit sarkasmus za stížnost nebo vzdělávací radu za osobní zkušenost. Úprava slovníku dotazů a instrukcí bývá často přínosnější než okamžité zvyšování složitosti modelu. V přehledu uchovávejte původní texty a odkazy v souladu se stanovenými pravidly uchovávání dat a přístupu.

Automatizace podle plánu a kontrola kvality

Po úspěšném ručním spuštění lze skript plánovat pomocí cron, plánovače úloh cloudové platformy nebo orchestrátoru, jako je n8n. Praktická posloupnost kroků zůstává stejná: načíst seznam dotazů, zavolat API, ověřit stav, uložit surovou odpověď, normalizovat videa, zapsat nové snímky a vytvořit přehled. Klíč předávejte prostřednictvím mechanismu pro správu tajných údajů v běhovém prostředí, nikoli v tabulce, textu workflow nebo chybové zprávě.

U automatizované úlohy se hodí čtyři kontroly. První ověřuje, že požadavek proběhl úspěšně a odpověď je ve formátu JSON. Druhá ověřuje, že vnější stav odpovídá očekávané hodnotě. Třetí kontroluje, že zpracování rozumí oběma variantám struktury vyhledávání a správně zvládá chybějící pole. Čtvrtá zaznamenává do protokolu počet nových jedinečných videí a počet chyb. Pokud se výsledky náhle neobjeví, přehled má ukázat nulový výběr jako stav běhu, nikoli jej bez vysvětlení směšovat s běžným úspěšným přehledem.

Stránkování přidávejte až po ověření první stránky. Dokumentace uvádí pro cestu vyhledávání parametr cursor; získaný token uchovejte a v dalším požadavku jej předávejte beze změny. Omezte maximální počet stránek pro jeden hledaný výraz a cyklus zastavte, pokud nepřibývají nové položky, chybí další kurzor nebo se opakuje již zpracovaný kurzor. Díky tomuto limitu lze řídit dobu běhu i objem sběru. Přítomnost kurzoru umožňuje pokračovat ve výpisu, ale nezaručuje úplnost výsledků ve vztahu ke všem zveřejněným příspěvkům.

Opakované spuštění v tentýž den může vrátit překrývající se videa. Klíčem pro odstranění duplicit by proto měl být stabilní identifikátor videa, zatímco historie snímků se ukládá jako samostatný záznam s datem pozorování. Pokud potřebujete souhrnný přehled, sestavujte jej nad snímky: můžete tak odlišit nově nalezené video od videa, které se objevilo v několika dotazech nebo bylo získáno znovu později.

Metriky: co lze správně porovnávat

Pro provozní sledování se hodí počet jedinečných nalezených videí podle dotazu, podíl videí s vyplněným popiskem, rozložení dostupných reakcí a četnost výskytu určitých témat. Při porovnávání dotazů používejte stejné parametry a období spuštění. Pokud jeden běh používá this-week a druhý this-month, rozdíl v objemu může být způsoben časovým oknem, a bez další analýzy jej proto nelze vykládat jako změnu zájmu.

Porovnání metrik jednoho videa v čase vyžaduje několik snímků a jednotné schéma ukládání. Pro každé datum uchovejte původní hodnoty tak, jak byly získány, a poté vypočítejte rozdíl mezi pozorováními. Nenazývejte rozdíl denním nárůstem, pokud se intervaly mezi skutečnými spuštěními lišily. Podobně řazení podle počtu lajků pomáhá najít výrazná videa ve shromážděném výběru, ale neměří obchodní efektivitu autora ani produktu.

Závěrečný přehled pro marketingový tým může spojit tři úrovně: příklady formulací publika s odkazy, tematické skupiny problémů a kvantitativní popis získaného výběru. Každý závěr by měl uvádět počet pozorování, použité dotazy a období sběru. Vedení tak získá kontext a analytik bude moci zopakovat filtrování nad stejnými zdrojovými daty.

Typické chyby a jak se jim vyhnout

Považovat prázdné pole za nulovou hodnotu

Pokud statistiky nebo údaje o autorovi chybějí, kód výše ponechá buňku prázdnou. Zachovává tak rozdíl mezi neznámou hodnotou a naměřenou nulou. Při analýze výslovně určete, jak s chybějícími údaji zacházet, a uvádějte počet řádků vyřazených z konkrétního výpočtu.

Předpokládat, že vyhledávání vždy vrací jediné pole

V odpovědi vyhledávání se objevují aweme_list i vnořené položky search_item_list[].aweme_info. Zpracování ověřuje obě podoby a ignoruje položky nesprávného typu. Pokud se schéma změní, uložené surové odpovědi pomohou rychle odhalit nové umístění dat a testovací soubory JSON umožní ověřit opravu ještě před dalším spuštěním.

Započítat jedno video znovu jako samostatný signál

Jedno video může odpovídat několika vyhledávacím slovům. V příkladu se do výsledného CSV zařadí jednou a pole dotazu uvádí první shodu v aktuálním pořadí. Pokud potřebujete zachovat všechny vazby „video–dotaz“, ukládejte samostatnou spojovací tabulku nebo seznam dotazů pro každý identifikátor, místo abyste odstranili původ záznamu.

Porovnávat nesrovnatelné výběry

Na výběr mají vliv hledané slovo, region, časový filtr, řazení i datum spuštění. Parametry ukládejte spolu s odpovědí a při porovnávání variant měňte vždy jen jeden faktor. Snáze tak zjistíte, zda změnu výsledku způsobilo chování výpisu, nebo změna nastavení experimentu.

Vydávat korelaci za nákupní záměr

Popis videa a veřejná počitadla poskytují indicie o obsahu a reakcích publika. Samy o sobě neukazují, kdo je připraven nakoupit, zda dotyčný viděl reklamu ani jaká je konverze. Používejte je při tvorbě hypotéz, ověřování témat a přípravě obsahu. Prodejní účinnost vyhodnocujte z vlastních údajů o kampaních, časově a z hlediska publika sladěných s tímto průzkumem.

Jak postup rozšířit

Jakmile základní verze stabilně funguje, lze přidat konfigurační soubor se seznamem dotazů a parametry spuštění, abyste mohli měnit slovník bez úprav Pythonu. Dalším krokem je tabulka vazeb mezi dotazy a tematickými skupinami, například „kvalita rozpoznávání“, „rychlost střihu“ a „export“. Kategorie musí definovat tým a ověřit je na příkladech; API vrací data vyhledávání, zatímco významové schéma určuje výzkumník.

Namísto CSV lze použít relační databázi se samostatnými tabulkami pro běhy, videa a snímky metrik. Jedinečný index podle identifikátoru videa chrání katalog před duplicitami a snímky umožňují sledovat změny dostupných počitadel. Uchovávejte datum pozorování v UTC a verzi normalizátoru. Při změně logiky extrakce lze znovu zpracovat archivní JSONL a výsledky porovnat.

V n8n lze sběr spouštět podle plánu a normalizační kód spouštět jako samostatnou službu v Pythonu nebo jako uzel, pokud zvolené prostředí podporuje potřebné operace. V první fázi není nutné zapojovat model: nejprve zajistěte stabilní sběr, poté změřte čas potřebný k ruční klasifikaci a zjistěte, které kategorie se opakují. AI má smysl tehdy, když zkrátí konkrétní opakovanou práci a její štítky lze ověřovat.

Pokud se pracovní otázka netýká vyhledávání podle formulací, ale pravidelného sledování konkrétního účtu, oficiální přehled obsahuje samostatnou cestu /getUserFeed s parametry query, max_cursor a count. Pro hashtag je určena cesta /getHashtagFeed s parametrem cursor. Jde o různé scénáře sběru: výběr koncového bodu by měl vycházet z výzkumné otázky, nikoli záměnou jednoho typu výběru za jiný.

Výsledek: opakovatelný výběr místo sbírky záložek

Po spuštění získá tým dva užitečné výstupy: archiv původních odpovědí a tabulku jedinečných videí s vyhledávaným výrazem, datem pozorování, odkazem, popiskem a dostupnými metrikami. Na jejich základě lze ručně seskupovat dotazy publika, předávat texty ke kontrolované klasifikaci, připravovat týdenní přehled a porovnávat opakované snímky. Kód výslovně zpracovává chyby požadavků, ověřuje vnější stav, rozlišuje dvě varianty struktury vyhledávání a chybějící metriky ukládá jako prázdné hodnoty.

Praktickým přínosem pro tým je transparentnější rozhodování o tom, které problémy stojí za ověření při rozhovorech, na vstupní stránce nebo v reklamním sdělení. Pokud průzkum vyžaduje jiný typ dat, změňte dotazy nebo použijte odpovídající dokumentovanou cestu. Před úpravou postupu si ověřte parametry v dokumentaci TikTok API; informace o produktu a přístup k ukázce najdete na stránce TikTok Scraper API.

Tento přístup řeší původní úkol: proměňuje vyhledávání na TikToku v reprodukovatelný výzkumný proces. Skript shromažďuje konkrétní vrácená videa, uchovává jejich původ a snímky a člověk nebo ověřitelný klasifikátor převádí jejich obsah na hypotézy o poptávce. Tým získá základ pro další rozhodování a zároveň zachová hranici mezi veřejnými znaky obsahu a potvrzenými prodejními výsledky.