Jak archivovat výsledky vyhledávání TikToku v Pythonu

Po spuštění kampaně se týmu může hodit ověřit, jaká veřejná videa se zobrazují ve výsledcích vyhledávání pro vybraná slova. Ruční vyhledávání se obtížně opakuje a porovnává po několika dnech. Jednoduchý skript může podle plánu spouštět stejné dotazy a archivovat odpovědi s datem a vyhledávací frází, aby analytik mohl záznamy ověřit a připravit vlastní souhrn.

Tento návod představuje archivní datový postup v Pythonu pro ukládání výsledků vyhledávání podle pevných frází. Na rozdíl od sledování jednotlivých hashtagů nebo účtů je zde klíčem ke srovnání opakovat stejné vyhledávací fráze a uložit samostatný snímek každé odpovědi. Stránka TikTok Scraper API jsonscraper uvádí základní adresu a endpoint GET /searchVideo; podle dokumentace tohoto endpointu se vyhledávací fráze předává v povinném parametru keyword.

Úkol a hranice měření

Představme si, že chce marketér každý den sbírat výsledky pro několik pevných frází: název produktu, kategorii a formulaci zákaznického problému. Systém pro každý dotaz uloží čas sběru a odpověď API. Po kontrole ukázkové odpovědi lze doplnit normalizaci polí, která se v JSON skutečně vyskytují, například identifikátoru videa nebo veřejných počítadel, pokud jsou k dispozici.

Archiv odpovídá na konkrétní otázku: jaké záznamy vrátilo vyhledávání podle uložené fráze při tomto spuštění? Pokud odpověď obsahuje metriky, opakovaná pozorování mohou ukázat rozdíl mezi hodnotami zaznamenanými v různých okamžicích. Tento rozdíl se vztahuje k pozorovaným snímkům a intervalu mezi nimi; pro srovnání ukládejte oba časy sběru a stejné pole.

Ukládejte dotaz společně s odpovědí. Složení výsledků se vztahuje ke konkrétní vyhledávací frázi a okamžiku sběru. Archiv se proto hodí ke sledování výsledků pro vybrané dotazy, nikoli jako úplný přehled veškerého obsahu TikToku. Identifikátory, původní odpovědi a časová razítka pomáhají ověřit, odkud pochází každý řádek následné tabulky.

Ověřte endpoint a jeho parametry

Přehled endpointů TikTok API uvádí základní adresu https://tiktok.evelode.com a GET /searchVideo. Aktuální specifikace API označuje keyword za povinný parametr vyhledávání; mezi volitelné parametry patří cursor, count, cache_timeout, date_posted, sort_by a region. Pro autorizaci se předává license_key. Informace o endpointu jsou dostupné také v dokumentaci Python SDK.

Parametry count a date_posted pomáhají nastavit velikost odpovědi a časový filtr; sort_by přijímá dokumentované hodnoty most-liked, relevance nebo date-posted. Pokud používáte stránkování, předávejte cursor získaný v předchozí odpovědi jako neprůhlednou hodnotu, kterou sami nevypočítáváte. Pro srovnatelný denní archiv ukládejte parametry dotazu a verzi vlastního kódu společně s daty.

Následující příklad používá pro testovací spuštění nízkou hodnotu count a pevně nastavený region US. Před každodenním sběrem ověřte jeden dotaz, jeho stavový kód HTTP a strukturu JSON. Schéma odpovědi může obsahovat nalezená videa v tiktok.aweme_list nebo v tiktok.search_item_list, kde je objekt videa uložen v aweme_info; kód podporuje obě pozorované podoby.

Připravte projekt

Vytvořte virtuální prostředí a nainstalujte knihovnu requests:

python -m venv .venv
source .venv/bin/activate
pip install requests

V PowerShellu aktivujete prostředí příkazem .venv\Scripts\Activate.ps1. Nastavte klíč a seznam vyhledávacích frází pomocí proměnných prostředí. Pro TikTok API použijte dokumentovaný název proměnné JSONSCRAPER_TIKTOK_LICENSE_KEY:

export JSONSCRAPER_TIKTOK_LICENSE_KEY="váš_klíč"
export TIKTOK_QUERIES="název produktu,kategorie produktu,zákaznický problém"

Sběr a ukládání snímků

Příklad odešle jednu žádost pro každou frázi na dokumentovaný endpoint a poté uloží původní JSON, čas sběru a použité parametry. Název souboru obsahuje datum a vyhledávací frázi. Klíč se uchovává v prostředí a do archivu se neukládá.

import json
import os
import re
import time
from datetime import datetime, timezone
from pathlib import Path

import requests

BASE_URL = "https://tiktok.evelode.com"
ENDPOINT = "/searchVideo"
LICENSE_KEY = os.environ["JSONSCRAPER_TIKTOK_LICENSE_KEY"]
QUERIES = [
    item.strip()
    for item in os.environ["TIKTOK_QUERIES"].split(",")
    if item.strip()
]
OUT = Path("data")
OUT.mkdir(exist_ok=True)


def safe_name(text):
    cleaned = re.sub(r"[^a-zA-Z0-9_-]+", "_", text).strip("_")
    return cleaned[:80] or "query"


def fetch(query):
    params = {
        "license_key": LICENSE_KEY,
        "keyword": query,
        "count": 10,
        "region": "US",
    }
    response = requests.get(
        BASE_URL + ENDPOINT,
        params=params,
        timeout=60,
    )
    response.raise_for_status()
    payload = response.json()

    if payload.get("status") != "ok":
        raise RuntimeError("API vrátil jiný stav než ok")

    return payload


def extract_videos(payload):
    tiktok = payload.get("tiktok") or {}
    videos = list(tiktok.get("aweme_list") or [])
    for item in tiktok.get("search_item_list") or []:
        video = item.get("aweme_info") or {}
        if video:
            videos.append(video)
    return videos


for query in QUERIES:
    collected_at = datetime.now(timezone.utc).isoformat()
    payload = fetch(query)
    record = {
        "collected_at": collected_at,
        "query": query,
        "request": {
            "endpoint": ENDPOINT,
            "keyword": query,
            "count": 10,
            "region": "US",
        },
        "videos_found": len(extract_videos(payload)),
        "payload": payload,
    }
    filename = OUT / f"{collected_at[:10]}_{safe_name(query)}.json"
    filename.write_text(
        json.dumps(record, ensure_ascii=False, indent=2),
        encoding="utf-8",
    )
    print(f"Uložena odpověď pro dotaz: {query}")
    time.sleep(1)

print(f"Uloženo odpovědí: {len(QUERIES)}")

Tento jednoduchý skript odešle jeden dotaz pro každou frázi s parametrem count=10. Pro rozsáhlejší sběr doplňte stránkování pomocí cursor: pokračujte v dotazech, předávejte hodnotu kurzoru z odpovědi, dokud API uvádí, že existují další výsledky, a každou odpověď ukládejte zvlášť. Kurzor a počet výsledků určují konkrétní průchod; uložený JSON umožňuje později ověřit, co přesně každý dotaz vrátil.

Příklad kontroluje vnější status a poté načte objekt tiktok. Sbírá položky z aweme_list i z search_item_list[].aweme_info, pokud je tato podoba přítomna. Možná pole záznamu videa zahrnují identifikátor, popis, autora, odkaz a statistiky; některá pole mohou chybět. Ukládejte proto úplnou odpověď a při normalizaci ověřujte přítomnost každého pole.

Jednosekundový interval je prodleva mezi dotazy odesílanými samotným skriptem, nikoli tvrzení o limitech služby. Frekvenci a opakování nastavte s ohledem na podmínky přístupu a dokumentaci. Parametr cache_timeout je pro vyhledávání dokumentován; umožňuje nastavit dobu ukládání do mezipaměti v sekundách a podle specifikace hodnota 0 ukládání do mezipaměti vypíná. Přidejte jej do dotazu, pokud takové chování vyhovuje vašemu scénáři.

Doplňte normalizaci podle skutečné odpovědi

Po prvním spuštění otevřete uložený soubor a prozkoumejte strukturu payload. Funkce extract_videos v příkladu sbírá položky ze dvou dokumentovaných umístění, kde se ve výsledku mohou nacházet výsledky vyhledávání. Najděte přesné klíče polí potřebných pro analýzu. Pokud pole v konkrétním záznamu chybí, uložte je jako chybějící hodnotu a nedoplňujte odhadované číslo.

Pro další zpracování je praktické vytvořit jeden řádek pro každý nalezený objekt a doplnit jej o collected_at a query. Ověřená pole lze ukládat do CSV nebo databáze a původní JSON ponechat v archivu. Tato kombinace umožňuje vytvářet přehledné tabulky a zároveň ověřit původ každého záznamu.

Pokud API vrací identifikátor videa, použijte jej k propojení pozorování stejného videa z různých spuštění. Každé pozorování uchovávejte samostatně a nepřepisujte minulá data. Pokud stabilní identifikátor chybí, nejprve ověřte, které atributy umožňují záznamy spárovat, a nepovažujte shodu textu popisu za zaručenou.

Porovnejte snímky a připravte zprávu

Po normalizaci seskupte záznamy podle ověřeného identifikátoru a seřaďte je podle času sběru. Rozdíl mezi dvěma po sobě jdoucími hodnotami v polích s počítadly lze vypočítat běžným kódem. Například přechod z 12 400 na 18 900 znamená, že se hodnota počítadla mezi těmito snímky změnila o 6 500. Ve zprávě uveďte data pozorování a původní pole, aby si čtenář mohl výpočet ověřit.

Užitečná struktura výsledné tabulky zahrnuje vyhledávací frázi, identifikátor příspěvku, čas sběru a vybraná pole z odpovědi. Souhrn lze seskupit podle dotazů a seřadit podle jednoho ověřeného počítadla. Tým tak získá ověřitelný seznam vrácených záznamů k dalšímu prohlédnutí; tabulku nebo zprávu vytvořte jako samostatný krok po prozkoumání skutečného schématu.

Nejprve ukládejte soubory JSON lokálně. Jakmile bude sběr pravidelný, přesuňte normalizované řádky do PostgreSQL nebo analytického úložiště a původní odpovědi do objektového úložiště, přičemž do názvu uveďte datum a dotaz. Uložení původního souboru je obzvlášť užitečné při úpravách parseru: lze jej znovu spustit nad historickými daty bez opětovného dotazování API.

Spouštějte sběr podle plánu

Pro každodenní archiv spouštějte skript prostřednictvím cronu nebo jiného plánovače dostupného ve vašem prostředí. Úloha může například jednou denně spustit soubor Pythonu a předat mu klíč a vyhledávací fráze prostřednictvím proměnných prostředí. Před pravidelným používáním ověřte jeden dotaz, poté celý seznam a teprve potom nastavte plánované spouštění.

Pro spolehlivý běh ukládejte stav každého dotazu, omezte počet opakování při dočasných chybách a označte sběr jako neúplný, pokud některá fráze skončí neúspěchem. Neuvádějte klíč v chybových zprávách. Je také užitečné rozdělovat soubory podle data a názvu dotazu, aby opakované spuštění nepřepsalo předchozí snímek.

Frekvenci vybírejte podle úkolu a objemu dotazů. Pro každodenní přehled stačí jedno spuštění denně; častější sběr má smysl, když tým potřebuje sledovat změny během dne. Začněte s malým seznamem frází, ověřte užitečnost vrácených výsledků a poté sběr rozšiřujte v souladu s podmínkami přístupu a pravidly pro používání dat.

Využijte AI k tematickému seskupování

Po ověření schématu odpovědi lze vybraná textová pole předat modelu, který seskupí popisy podle předem stanovených témat nebo připraví stručný návrh souhrnu. Vedle klasifikace uchovávejte původní identifikátor příspěvku, vyhledávací frázi a textový úryvek, na jehož základě byla kategorie určena. Analytik tak může přejít od výstupu modelu k původnímu záznamu.

Číselné rozdíly, řazení a deduplikaci počítejte běžným kódem. Model se hodí ke zpracování textu a formulaci návrhu zprávy; počítadla a časová razítka přebírejte z uložených odpovědí. Rozdělení těchto operací zpřehledňuje původ každého závěru.

Část automatických kategorií kontrolujte ručně a opravy ukládejte jako testovací příklady. Pokud různé typy příspěvků pravidelně končí ve stejné skupině, upřesněte definice kategorií a kontrolu zopakujte. Tento postup pomáhá vyhodnocovat kvalitu klasifikace na datech z vašeho úkolu.

Shrnutí: opakovatelný archiv a ověřitelný přehled

Po spuštění dokumentovaného dotazu s parametrem keyword bude mít tým k dispozici archiv, který ukáže, jaké fráze se použily, kdy se tak stalo a jaká data API pro každou z nich vrátilo. Na jeho základě lze vytvořit tabulku výsledků, porovnat ověřená pole mezi snímky a připravit seznam nalezených příspěvků k ruční analýze.

Začněte jedním testovacím dotazem a poté nastavte seznam frází a plán spouštění. Popis TikTok Scraper API uvádí základní adresu a přehled endpointů; parametry /searchVideo a podobu odpovědi popisuje specifikace API. Archivace ověřených odpovědí vytváří základ pro opakovatelnou analýzu pevných vyhledávacích frází.