Michael JohnsonPo uvedení aplikace nebo nové funkce se zpětná vazba rychle rozptýlí mezi krátká videa. Marketér ručně najde několik videí a pošle jejich odkazy do chatu, ale analytik později nedokáže zjistit, které příspěvky už byly započítány a jak se měnil počet zhlédnutí. Praktickým řešením je pravidelně shromažďovat výsledky vyhledávání pomocí několika stabilních dotazů, ukládat původní odpovědi a sestavovat report z ověřených polí.
V tomto návodu nastavíme sběr pro konkrétní případ: tým vydal novou funkci a chce každý týden sledovat veřejná videa TikTok, jejichž popis obsahuje název produktu, klíčovou funkci nebo typický problém uživatele. Jde o monitoring výsledků vyhledávání: API vrací výsledky podle dotazu a parametrů, nikoli zaručený seznam všech příspěvků o uvedení produktu.
Nejprve určete, jaký signál tým potřebuje
Samotný vysoký počet zhlédnutí příliš neobjasňuje, co by měl tým udělat dál. Užitečnější je vědět, které otázky se opakují, jaké scénáře lidé ukazují a která videa získávají výrazné veřejné reakce. Nejdříve proto formulujte několik vyhledávacích frází a rozhodněte, která pole se objeví v reportu.
Například při uvedení nástroje na plánování příspěvků můžete zkusit dotazy „název produktu“, „plánovač obsahu“ a „jak naplánovat TikTok“. Fráze by měly zachycovat různé způsoby, jakými lidé mohou popisovat stejné téma. Zaznamenejte je spolu s datem zahájení monitoringu a regionem, aby bylo možné další výpisy porovnávat při stejném nastavení.
Minimální tabulka může obsahovat čas sběru, vyhledávací frázi, identifikátor videa, odkaz, popis, jméno autora, identifikátor autora a dostupné hodnoty zhlédnutí, lajků a komentářů. TikTok Scraper API v dokumentaci uvádí pro výsledky vyhledávání pole jako aweme_id, desc, share_url, údaje o autorovi a část statistik. Konkrétní pole je třeba ověřit v každém objektu: některé metriky mohou chybět.
Připojte dokumentované vyhledávání
K vyhledávání videí použijte metodu GET na trase /searchVideo na základní adrese https://tiktok.evelode.com. Dokumentace uvádí povinný parametr keyword a další parametry count, cursor, date_posted, sort_by, region a cache_timeout. Mezi povolené hodnoty filtru data patří this-week a mezi způsoby řazení relevance, most-liked a date-posted. Jejich účel a názvy si ověřte v referenční příručce tras TikTok API.
Licenční klíč se předává jako parametr dotazu license_key. V produkčním skriptu jej načítejte z proměnné prostředí JSONSCRAPER_TIKTOK_LICENSE_KEY, neukládejte tajný klíč do zdrojového kódu a nevypisujte jej do protokolů. Tento příklad vyžaduje Python 3.8+ a používá balíček requests:
import os
import requests
BASE_URL = "https://tiktok.evelode.com"
API_KEY = os.environ["JSONSCRAPER_TIKTOK_LICENSE_KEY"]
def search_videos(keyword, cursor=None):
params = {
"license_key": API_KEY,
"keyword": keyword,
"count": 20,
"date_posted": "this-week",
"sort_by": "date-posted",
"region": "US",
}
if cursor is not None:
params["cursor"] = cursor
response = requests.get(
f"{BASE_URL}/searchVideo",
params=params,
timeout=30,
)
response.raise_for_status()
payload = response.json()
if payload.get("status") != "ok":
raise RuntimeError("TikTok API vrátil jiný stav než ok")
return payload["tiktok"]
result = search_videos("content planning app")
print("Nalezené objekty:", len(result.get("aweme_list", [])))Skript kontroluje chyby HTTP a stav vnější odpovědi. Úspěšná odpověď HTTP sama o sobě nezaručuje, že vyhledávání obsahuje videa: při prázdném výsledku může být seznam prázdný. Při prvním spuštění je užitečné uložit celou odpověď do zabezpečeného úložiště a porovnat skutečné objekty s tabulkou normalizovaných polí.
Zpracujte obě varianty odpovědi vyhledávání
Výsledky vyhledávání mají důležitou zvláštnost ve své struktuře. Videa mohou být přímo v tiktok.aweme_list, případně mohou přijít uvnitř tiktok.search_item_list[].aweme_info. Pokud obslužný kód čte pouze první seznam, může přehlédnout výsledky dostupné ve druhé variantě.
Přidejte malý normalizátor, který podporuje obě struktury a bez problémů přeskočí položky bez vnořeného objektu videa:
def extract_awemes(tiktok):
items = list(tiktok.get("aweme_list") or [])
for item in tiktok.get("search_item_list") or []:
aweme = item.get("aweme_info")
if aweme:
items.append(aweme)
return items
def normalize(aweme, keyword, collected_at):
author = aweme.get("author") or {}
stats = aweme.get("statistics") or {}
return {
"collected_at": collected_at,
"keyword": keyword,
"video_id": aweme.get("aweme_id"),
"posted_at": aweme.get("create_time"),
"description": aweme.get("desc"),
"share_url": aweme.get("share_url"),
"author_id": author.get("uid"),
"author_name": author.get("nickname"),
"views": stats.get("play_count"),
"likes": stats.get("digg_count"),
"comments": stats.get("comment_count"),
"shares": stats.get("share_count"),
}Chybějící hodnota zůstane None. Nenahrazujte ji nulou: nula znamená naměřenou hodnotu, zatímco None zachovává informaci, že pole nebylo vráceno. Tento rozdíl ovlivňuje průměry, podíly i závěry pro tým.
Uchovávejte historii, nejen aktuální snímek
Chcete-li sledovat vývoj, ukládejte samostatné záznamy pozorování. Identifikátor videa se hodí k deduplikaci příspěvků, ale nikoli k mazání historie: když se stejné video objeví při dalším sběru, vznikne nový bod pozorování. Jedinečný klíč tabulky pozorování může například tvořit video_id a collected_at; odkaz a popis ukládejte do záznamu pro snadné ověření.
Prototypu poslouží minimální schéma SQLite:
import sqlite3
conn = sqlite3.connect("tiktok_observations.sqlite3")
conn.execute("""
CREATE TABLE IF NOT EXISTS observations (
video_id TEXT NOT NULL,
collected_at TEXT NOT NULL,
keyword TEXT NOT NULL,
posted_at INTEGER,
description TEXT,
share_url TEXT,
author_id TEXT,
author_name TEXT,
views INTEGER,
likes INTEGER,
comments INTEGER,
shares INTEGER,
PRIMARY KEY (video_id, collected_at, keyword)
)
""")
conn.commit()V praxi normalizujte čas sběru na UTC, původní JSON ukládejte odděleně a přidejte sloupec s verzí schématu. Původní odpověď pomůže znovu ověřit převod, pokud se struktura nových objektů liší od obvyklé. U příspěvků nalezených pomocí více dotazů uchovávejte odpovídající klíčové fráze v samostatné propojené tabulce nebo je slučte při sestavování reportu.
Stránkování: pokračujte pouze pomocí kurzoru z odpovědi
Parametr cursor slouží k pokračování ve vyhledávání. Jeho hodnotu převezměte z předchozí odpovědi a bez úprav ji předejte dál. Sběr ukončete, když has_more již neoznačuje další výsledky nebo když dosáhnete stanoveného limitu. Kurzorem zacházejte jako s neprůhlednou hodnotou: sami jej nevypočítávejte ani nenahrazujte počítadlem stránek.
def collect_pages(keyword, max_pages=3):
cursor = None
collected = []
for _ in range(max_pages):
page = search_videos(keyword, cursor)
collected.extend(extract_awemes(page))
if not page.get("has_more"):
break
cursor = page.get("cursor")
if cursor is None:
break
return collectedOmezení počtu stránek dělá pravidelnou úlohu předvídatelnou z hlediska počtu požadavků. Do protokolu ukládejte počet stránek a hodnotu has_more; poskytne to kontext pro report o výsledné sadě. I při stránkování výsledek popisuje získané odpovědi API a nastavený limit sběru; nepředstavuje odhad všech příspěvků na platformě.
Sestavte opakovatelný report
Spouštějte sběr podle plánu jednou týdně nebo častěji, pokud tým potřebuje častější signály. U každého běhu zaznamenejte seznam dotazů, parametry, čas, počet získaných objektů a počet jedinečných identifikátorů. Samostatně počítejte příspěvky, které byly v tomto běhu zaznamenány poprvé, a příspěvky, které se objevily už dříve.
V reportu se hodí čtyři jednoduché přehledy:
- Nová videa: odkazy, popisy, datum zveřejnění a vyhledávací fráze, pomocí které bylo video nalezeno.
- Opakující se témata: seskupení popisů do ručně definovaných kategorií, například „chyba při nastavení“, „požadavek na funkci“ a „přehled scénáře“.
- Veřejné reakce: dostupná zhlédnutí, lajky, komentáře a sdílení zobrazené spolu s časem pozorování.
- Signály k ověření: nové formulace, časté dotazy nebo videa, která stojí za to prozkoumat.
Rozdíl mezi dvěma snímky nenazývejte „novými lajky“, aniž byste ověřili význam a aktuálnost hodnot v odpovědi. Přesnější formulace je „hodnota metriky v poslední získané odpovědi“ a „rozdíl mezi uloženými snímky“. Tým tak uvidí, co přesně bylo vypočítáno, a před rozhodnutím si může otevřít původní příspěvek.
Zapojte AI do klasifikace, nikoli místo sběru
Po normalizaci můžete předat popisy videí modelu, který je roztřídí podle předem stanovených kategorií. Odesílejte pouze nezbytná textová pole a požadujte strukturovaný výstup: kategorii, stručné odůvodnění, míru jistoty a úryvek popisu, o který se štítek opírá. Původní příspěvek uchovávejte spolu se štítkem, aby analytik mohl prověřit sporné případy.
Pracovní postup zůstává jednoduchý: plánovač spustí sběr; Python ověří odpověď a uloží JSON; samostatná úloha normalizuje nové záznamy; klasifikátor zpracuje pouze nové popisy; report se sestaví z databáze a odešle do kanálu vybraného týmem. Samotné TikTok Scraper API poskytuje data z vyhledávání, zatímco klasifikace a doručení reportu jsou vaše integrační logika, kterou lze implementovat v Pythonu, n8n nebo Make.
Chcete-li omezit šum, stanovte slovník kategorií ještě před odesláním do modelu a pravidelně kontrolujte ručně označený vzorek. U krátkých nebo nejednoznačných popisů je užitečný stav „nedostatek kontextu“ namísto vynuceného výběru kategorie. Štítky AI pomáhají řadit příspěvky ke kontrole, ale závěry o problémech uživatelů ověřujte čtením příspěvků a porovnáním více pozorování.
Chyby, opakované pokusy a bezpečné zacházení s klíčem
Síťový požadavek může skončit vypršením časového limitu, dočasnou chybou nebo odpovědí, kterou nelze načíst jako JSON. Rozdělte zpracování na jednotlivé fáze: požadavek, kontrolu stavového kódu HTTP, načtení JSON, ověření vnějšího stavu, normalizaci a zápis. Při dočasných výpadcích použijte omezený počet opakování s postupně delší pauzou; trvalé chyby zaznamenejte k pozdějšímu prošetření a běh neoznačujte jako úspěšný.
Klíč ukládejte ve správci tajných údajů běhového prostředí nebo v proměnné prostředí. Protože API přijímá license_key v řetězci dotazu, nezaznamenávejte úplnou URL ani parametry požadavku: obsahovaly by tajný klíč. Pro diagnostiku zaznamenávejte trasu, kód odpovědi, dobu trvání, vyhledávací frázi a identifikátor úlohy, ale klíč z protokolů odstraňte.
Plán a rozsah sběru nastavte podle svých potřeb a podmínek používání platformy. Sběr veřejných dat omezte na to, co je pro analýzu skutečně potřebné; pravidla týmu by měla popisovat ukládání popisů, odkazů a identifikátorů autorů. Odpovědi API a metriky mohou být neúplné nebo se mezi pozorováními měnit, proto by report měl u každého řádku uchovávat čas sběru a jeho původ.
Výsledek: od ručně sdílených odkazů k ověřitelné historii
Po nastavení získá tým pravidelně aktualizovaný seznam nalezených videí, původní odpovědi pro audit, tabulku dostupných veřejných metrik a přehled opakujících se témat. To pomáhá rychleji zachytit dotazy k nové funkci, najít příklady uživatelských scénářů a vybrat příspěvky k ruční analýze. Porovnání snímků ukazuje, jak se mění uložené hodnoty u již nalezených videí, zatímco protokol dotazů vysvětluje, jakým způsobem byla výsledná sada sestavena.
Začněte jedním dotazem a malým limitem stránek, ověřte skutečnou strukturu odpovědi a potom přidejte další formulace a plán. Než prototyp nasadíte do produkčního prostředí, stanovte pravidla deduplikace, ukládání a zpracování chyb. Aktuální trasy a parametry najdete v oficiální dokumentaci API; přehled možností a přechod k testování nabízí stránka TikTok Scraper API.
