Týdenní přehled vyhledávání na TikToku se hodí, když ukazuje, která videa se v novém výběru objevila od posledního spuštění. Stačí ukládat identifikátory již zaznamenaných videí a do CSV přidávat nové výsledky. Níže najdete reprodukovatelný scénář v Pythonu s TikTok Scraper API: vyhledá videa podle klíčového slova, zpracuje obě dokumentované podoby odpovědi a vede místní databázi ID.
Úkol: zaznamenat nové příspěvky, neprocházet znovu celý výpis
Tým podpory, průzkumník trhu nebo obsahový analytik může potřebovat pravidelný výběr veřejných videí podle dotazu na produkt. Když pokaždé stáhnete celý výsledek, opakující se videa znesnadňují kontrolu a nové příspěvky se ztrácejí mezi těmi již zpracovanými. Protokol identifikátorů umožňuje porovnávat výsledky jednotlivých spuštění: CSV obsahuje pouze videa nová pro tento proces a základní pole vrácená v odpovědi.
Takový protokol odpovídá na omezenou, ale praktickou otázku: které položky se objevily v odpovědi při aktuálním spuštění, ale chyběly v uložené sadě ID? Hodí se jako fronta pro ruční kontrolu i k předání dat do tabulky nebo k další analýze. Výběr odráží výsledky API pro zadaný dotaz; sám o sobě nepopisuje všechny příspěvky na TikToku.
Co si připravit
- Python 3.8 nebo novější.
- Přístup k TikTok Scraper API a licenční klíč.
- Dotaz, který lze opakovat bez změny významu, například název produktu nebo konkrétní frázi.
Uložte klíč do proměnné prostředí JSONSCRAPER_TIKTOK_LICENSE_KEY, nikoli do souboru se skriptem. V níže uvedeném příkladu se klíč předává jako parametr dotazu license_key, podle schématu API. Nezapisujte jej do protokolu běhu.
export JSONSCRAPER_TIKTOK_LICENSE_KEY="váš_klíč"
python -m pip install requests
Ve Windows PowerShellu lze proměnnou nastavit pro aktuální relaci takto: $env:JSONSCRAPER_TIKTOK_LICENSE_KEY="váš_klíč". Skutečné tajné údaje nepřidávejte do Gitu ani sdíleného CSV.
Integrace: vyžádat výsledky vyhledávání a normalizovat JSON
Dokumentace pro vyhledávání videí popisuje metodu GET na cestě \/searchVideo s povinným parametrem keyword. V požadavku lze nastavit také count, oblast, řazení, časový filtr a kurzor pro procházení výsledků. Tento minimální příklad používá pouze klíčové slovo, počet požadovaných položek a oblast USA. Přehled cest TikTok API uvádí přesné názvy parametrů.
Struktura odpovědi na vyhledávání vyžaduje zvláštní pozornost: pole aweme_list může být prázdné a položky videí se mohou nacházet v search_item_list, kde jsou údaje vnořené v aweme_info. Kód proto zkontroluje obě cesty, spojí položky a odstraní duplicity podle aweme_id. Tím se zabrání tomu, aby se správně zpracovaný JSON omylem změnil v prázdný přehled.
import csv
import json
import os
from pathlib import Path
from datetime import datetime, timezone
import requests
BASE_URL = "https:\/\/tiktok.evelode.com\/searchVideo"
KEYWORD = "název produktu"
REGION = "US"
COUNT = 30
STATE_FILE = Path("seen_video_ids.json")
OUTPUT_FILE = Path("new_tiktok_videos.csv")
license_key = os.environ.get("JSONSCRAPER_TIKTOK_LICENSE_KEY")
if not license_key:
raise RuntimeError("Nastavte JSONSCRAPER_TIKTOK_LICENSE_KEY")
response = requests.get(
BASE_URL,
params={
"license_key": license_key,
"keyword": KEYWORD,
"count": COUNT,
"region": REGION,
},
timeout=60,
)
response.raise_for_status()
data = response.json()
# Ukázková odpověď obsahuje vnější status a vnořený objekt tiktok.
if "status" in data and data["status"] != "ok":
raise RuntimeError("API vrátilo jiný status než ok")
tiktok = data.get("tiktok") or {}
items = list(tiktok.get("aweme_list") or [])
for entry in tiktok.get("search_item_list") or []:
info = entry.get("aweme_info")
if isinstance(info, dict):
items.append(info)
# Jedinečné položky aktuální odpovědi při zachování pořadí.
current = {}
for item in items:
video_id = item.get("aweme_id")
if video_id:
current[str(video_id)] = item
if STATE_FILE.exists():
seen = set(json.loads(STATE_FILE.read_text(encoding="utf-8")))
else:
seen = set()
new_items = [(video_id, item) for video_id, item in current.items()
if video_id not in seen]
run_time = datetime.now(timezone.utc).isoformat()
fields = ["collected_at_utc", "query", "aweme_id", "created_at",
"author", "description", "share_url", "play_count",
"digg_count", "comment_count", "share_count"]
write_header = not OUTPUT_FILE.exists() or OUTPUT_FILE.stat().st_size == 0
with OUTPUT_FILE.open("a", newline="", encoding="utf-8") as f:
writer = csv.DictWriter(f, fieldnames=fields)
if write_header:
writer.writeheader()
for video_id, item in new_items:
author = item.get("author") or {}
stats = item.get("statistics") or {}
writer.writerow({
"collected_at_utc": run_time,
"query": KEYWORD,
"aweme_id": video_id,
"created_at": item.get("create_time"),
"author": author.get("unique_id") or author.get("nickname"),
"description": item.get("desc"),
"share_url": item.get("share_url"),
"play_count": stats.get("play_count"),
"digg_count": stats.get("digg_count"),
"comment_count": stats.get("comment_count"),
"share_count": stats.get("share_count"),
})
seen.update(current.keys())
STATE_FILE.write_text(json.dumps(sorted(seen)), encoding="utf-8")
print(f"V odpovědi: {len(current)} jedinečných videí; nových: {len(new_items)}")
Skript zapisuje chybějící hodnoty v JSON jako prázdné buňky: jednotlivé záznamy nemusí obsahovat některá pole či metriky. Kód nenahrazuje chybějící hodnotu nulou ani nepovažuje nulu za chybějící údaj. Čas sběru se zaznamenává odděleně od času zveřejnění, který API vrací v poli create_time.
Jak funguje kontrola změn
- Požadavek vrátí stránku výsledků vyhledávání pro zadané klíčové slovo.
- Normalizátor shromáždí záznamy z
aweme_listasearch_item_list[].aweme_info. - Skript odstraní duplicity v rámci odpovědi podle ID videa.
- Identifikátory se porovnají s místním protokolem JSON.
- Nová ID se přidají do CSV a poté se celá dosud zaznamenaná sada uloží pro příští spuštění.


Vizualizace tohoto procesu se hodí při předávání skriptu kolegům: CSV je průběžný protokol a JSON uchovává stav deduplikace. Oba soubory lze ukládat odděleně od kódu a zálohovat společně. Při týmovém nebo cloudovém spouštění nahraďte místní soubor JSON vhodným trvalým úložištěm a zajistěte atomickou aktualizaci stavu, aby se při souběžných spuštěních navzájem nepřepisovala.
Opakované spouštění a stránkování
Spouštění opakujte podle plánu pomocí plánovače operačního systému, úlohy CI nebo automatizovaného pracovního postupu. Neměňte klíčové slovo, aniž byste zaznamenali jeho verzi: různé dotazy vytvářejí různé výběry a jejich smíchání v jednom protokolu ztěžuje interpretaci. Uvedený skript pro jednoduchost používá jeden dotaz; seznam dotazů lze zpracovat ve smyčce a u každého řádku zachovat pole query.
API podporuje cursor pro procházení výsledků vyhledávání. Pokud přidáte stránkování, předávejte kurzor z předchozí odpovědi, ukládejte jej jako neprůhlednou hodnotu a procházení ukončete, až další stránky nebudou potřeba. Omezení count určuje počet požadovaných položek, ale skutečný počet záznamů je třeba zjistit z odpovědi. I několik stránek představuje pouze získané stránky výsledků vyhledávání, nikoli záruku úplného pokrytí platformy.
V tomto scénáři záměrně není automatická klasifikace textu ani vyvozování „trendu“. CSV pomáhá rychle vyčlenit nově nalezené záznamy; analytik je pak může označit podle tématu, záměru nebo typu otázky a ručně ověřit příklady. Pokud zapojíte jazykový model, předávejte mu jen potřebná textová pole a požadujte, aby vracel kategorie spolu s původním ID, aby bylo možné výsledek ověřit a propojit se záznamem.
Kontroly a časté chyby
- Chyba HTTP.
raise_for_status()zastaví běh při kódu HTTP mimo úspěšný rozsah. Než aktualizujete soubor stavu, ověřte dostupnost API, parametry a účet. - Stav API se liší od
ok. Pokud odpověď obsahuje pole nejvyšší úrovněstatuss jinou hodnotou, skript se zastaví před zapsáním výsledků. Tím se zachová předchozí protokol a sníží riziko, že bude chybná odpověď považována za prázdný výpis. - Prázdný seznam v
aweme_list. Zkontrolujte takésearch_item_list; kód zohledňuje obě struktury. - Videa se opakují mezi spuštěními. U překrývajících se stránek výsledků vyhledávání se to očekává: pokud je ID již uložené, do přehledu se znovu nepřidá.
- Metrika chybí. Buňka zůstane prázdná. Při výpočtech odlišujte chybějící hodnoty od skutečných nul.
- Stav se ztratil. Skript bude všechna vrácená ID považovat za nová. Zálohujte
seen_video_ids.jsonspolu s CSV nebo použijte trvalou databázi.
Při automatizaci ukládejte diagnostické údaje bez klíče: čas spuštění, kód HTTP, stav API, počet zpracovaných záznamů a počet nových ID. Pomůže to odlišit situaci, kdy nejsou žádná nová videa, od neúspěšného požadavku. Pokud potřebujete později znovu ověřit schéma, můžete původní úplnou odpověď archivovat odděleně; omezte přístup i dobu uchovávání podle potřeb týmu.
Výsledek
Po spuštění máte CSV s videi, jejichž ID jsou v protokolu nová, popisy, odkazy a dostupná veřejná pole, a také stav JSON pro porovnání při příštím spuštění. Tento výsledek poslouží jako kompaktní vstupní fronta pro podporu, analytiku nebo obsahový tým. Popis API a možnosti přístupu najdete na stránce TikTok Scraper API; přesné parametry vyhledávání ověřte v oficiálním přehledu cest.