Monitorování hashtagů na TikToku v Pythonu: funkční požadavek API

Marketingový tým si všímá, že se na TikToku objevují videa o novém produktu, ale každý den ručně kontrolovat několik hashtagů je obtížné. Aby bylo možné porovnávat příspěvky a jejich viditelné ukazatele v čase, je potřeba opakovatelný sběr s časovým razítkem, archivem původních odpovědí a kontrolou změn.

Pro takový prototyp se hodí TikTok Scraper API od jsonscraper: stránka produktu uvádí endpointy pro hashtagy, uživatele, videa a vyhledávání. Prvním krokem je ověřit požadovaný endpoint a formát odpovědi v Postmanu a pak přenést potvrzenou konfiguraci do Pythonu. Tak lze vytvořit opakovatelný proces, který získává pouze pole skutečně přítomná v odpovědi.

Cíl: sledovat vývoj, ne jen jeden populární příspěvek

Jeden příspěvek s vysokým počtem zhlédnutí může upoutat pozornost, ale pro plánování kampaně je užitečnější vědět, kolik nových videí se k tématu podaří najít a jak se mění veřejné ukazatele již objevených příspěvků. Internetový obchod se sportovním zbožím může například chtít před přípravou souvisejících kreativ odhadnout množství videí o určitém typu cvičení.

Ruční kontrola ztěžuje porovnávání: soubor výsledků se mění, ukazatele narůstají a zaměstnanci je mohou zapisovat v různých formátech. Pokud se uloží snímek každého spuštění spolu s časem sběru a původním JSON, tým získá historii vlastních pozorování a bude moci data znovu zpracovat při změně analytického schématu.

Automatizace se skládá z několika kroků: ověřit endpoint a parametry, podle plánu vyžádat data, uložit odpověď, potvrdit její strukturu a poté získat potřebná pole. Výslednou tabulku lze využít pro grafy, tematickou klasifikaci nebo report.

Co potvrzuje dokumentace API

Na stránce TikTok Scraper API je uvedena základní adresa https://tiktok.evelode.com a endpointy třídy Hashtag: GET /getHashtagInfo, GET /getHashtagFeed a GET /getHashtagFeedByID. Stránka také uvádí příklad požadavku na jiný endpoint s parametrem license_key a popisuje nastavení klíče v kolekci Postman.

Pro GET /getHashtagFeed oficiální specifikace endpointů uvádí povinný parametr query (URL hashtagu nebo název tagu) a nepovinné parametry cursor, count, region a cache_timeout. Odpověď feedu má obsahovat pole tiktok.aweme_list; mezi uvedená pole jednotlivých položek patří aweme_id, desc, create_time, share_url, údaje o autorovi a statistics. Některá pole mohou chybět, proto před zpracováním ověřte skutečný JSON.

V kolekci jsonscraper v Postmanu lze pohodlně provést zkušební požadavek, zkontrolovat skutečnou odpověď a získat testovací příklad pro následné ověření kódu. Pro autorizaci se předává license_key; klíč uchovávejte v proměnné prostředí a nevypisujte jej do logů.

Nejprve ověřte požadavek v Postmanu

Začněte jedním testovacím hashtagem. V kolekci vyberte endpoint hashtagového feedu, nastavte license_key způsobem uvedeným v dokumentaci a do parametru query zadejte název tagu. Podle potřeby přidejte count a kód země v parametru region. Odešlete požadavek a zkontrolujte stav HTTP, pole nejvyšší úrovně status a obsah tiktok.aweme_list.

Úspěšnou odpověď uložte jako testovací soubor JSON. Ověřte v něm přítomnost identifikátoru příspěvku, popisu, času zveřejnění, odkazu a statistik. Pole zahrňte do analytického schématu až poté, co potvrdíte, že se vrací v požadovaném typu.

Klíč API uchovávejte v proměnné prostředí, nikoli ve zdrojovém souboru. Pokud se klíč předává v URL, při zaznamenávání požadavku jej maskujte, aby se celá adresa nedostala do logů.

Klient v Pythonu pro požadavek a archivaci

Endpoint a názvy parametrů níže odpovídají zveřejněné specifikaci: pro hashtag se používá query a autorizace se předává prostřednictvím license_key. Příklad je kompatibilní s Pythonem 3.8+ a ukládá původní odpověď spolu s metadaty spuštění.

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

import requests

BASE_URL = "https://tiktok.evelode.com"
API_KEY = os.environ["JSONSCRAPER_TIKTOK_LICENSE_KEY"]


def fetch_hashtag_feed(hashtag: str) -> dict:
    params = {
        "license_key": API_KEY,
        "query": hashtag,
        "count": 20,
    }
    response = requests.get(
        f"{BASE_URL}/getHashtagFeed",
        params=params,
        timeout=45,
    )
    response.raise_for_status()
    payload = response.json()
    if payload.get("status") != "ok":
        raise RuntimeError("API vrátilo jiný stav než ok")
    return payload


def archive_response(hashtag: str, payload: dict) -> Path:
    collected_at = datetime.now(timezone.utc).isoformat()
    safe_tag = hashtag.lstrip("#").replace("/", "_")
    output_dir = Path("data/raw") / safe_tag
    output_dir.mkdir(parents=True, exist_ok=True)

    filename = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ.json")
    file_path = output_dir / filename
    file_path.write_text(
        json.dumps(
            {
                "hashtag": hashtag,
                "collected_at": collected_at,
                "response": payload,
            },
            ensure_ascii=False,
            indent=2,
        ),
        encoding="utf-8",
    )
    return file_path


if __name__ == "__main__":
    tag = "#prikladtematu"
    payload = fetch_hashtag_feed(tag)
    saved_path = archive_response(tag, payload)
    print(f"Archiv uložen: {saved_path}")

Před spuštěním nastavte proměnnou prostředí JSONSCRAPER_TIKTOK_LICENSE_KEY. Požadavek používá potvrzený parametr query a pomocí count omezuje počet požadovaných položek. V odpovědi se ověřuje stav HTTP i stav v JSON; archiv uchovává skutečná data pro pozdější zpracování. Než přidáte plánování a analytiku, vyzkoušejte spuštění s jedním hashtagem.

Jak přidat normalizaci bez křehkých předpokladů

Dokumentace uvádí, že feed obsahuje pole tiktok.aweme_list. Před převodem ověřte, že tiktok je objekt a aweme_list seznam. U každé položky získávejte pouze potvrzená pole, například aweme_id, desc, create_time, share_url a hodnoty z statistics, pokud jsou přítomné.

Interní tabulka může obsahovat hashtag dotazu, čas sběru, ID videa a vybrané metriky. U nepovinného nebo chybějícího ukazatele ukládejte prázdnou hodnotu: chybějící metrika se liší od naměřené nuly. Původní odpovědi ukládejte odděleně, abyste mohli tabulku vytvořit znovu bez dalšího požadavku.

Pokud se formát odpovědi změní, kontrola typů by měla zastavit nesprávné zpracování a vytvořit diagnostickou zprávu. Uložte testovací JSON vedle testu parseru: pomůže ověřit, že nová verze kódu stále zpracovává známé schéma.

Metriky založené na opakovaných pozorováních

Pokud odpověď poskytuje čítače, ukládejte každé pozorování s časovým razítkem. U jednoho příspěvku porovnejte hodnoty ze dvou spuštění a vypočítejte pozorovanou změnu za daný interval. K párování použijte aweme_id uvedené ve specifikaci a ověřte jeho přítomnost v každé položce.

Počet příspěvků poprvé objevených za den lze vypočítat z výsledků vašich spuštění. Tato metrika popisuje tok vrácený konkrétními požadavky při daných parametrech a plánu. Umožňuje porovnávat vlastní snímky, pokud metoda sběru zůstává konzistentní.

Minimální report může zobrazovat počet nově objevených příspěvků za den, rozdělení dostupných čítačů a změny hodnot u opakovaně nalezených videí. Přidejte čas požadavku a název původního souboru, aby analytik mohl ověřit původ každého záznamu.

Plánování a zpracování chyb

Jakmile jsou požadavek a zpracování ověřené, spouštějte skript podle plánu — například prostřednictvím cron, GitHub Actions nebo datového orchestrátoru. Seznam hashtagů uložte do samostatné konfigurace, abyste mohli témata přidávat a odebírat bez úprav logiky klienta.

Pro automatické spouštění nastavte časový limit, omezený počet opakování při dočasných síťových chybách a zaznamenávání stavu HTTP a délky požadavku. Klíč do logu nezapisujte. Při chybě zpracování uchovávejte bezpečné diagnostické údaje a upozorněte odpovědnou osobu.

Specifikace podporuje stránkování prostřednictvím parametru cursor pro hashtagový feed. Pokud jej potřebujete, uložte kurzor z odpovědi a beze změny jej předejte v dalším požadavku; zpracovávejte pouze vrácené výsledky a sledujte has_more, pokud je přítomno. Pokud požadavky pro více hashtagů vrátí stejný příspěvek, zvolte deduplikační klíč podle cíle: buď počítat příspěvek samostatně pro každý hashtag, nebo evidovat pouze jedinečná videa.

Klasifikace a automatizace reportů

Po získání ověřených řádků lze přidat klasifikaci popisů videí podle zadaných témat: pole desc je uvedeno ve schématu položky. Model může příspěvky seskupovat podle formátu — například na návody, recenze nebo uživatelské zkušenosti. Uchovávejte původní text, štítek, verzi instrukcí a výsledek; sporné případy předejte ke kontrole člověku.

Číselné ukazatele počítejte běžným kódem, aby opakovaná spuštění poskytovala reprodukovatelný výsledek. Klasifikátor se hodí ke zpracování textu; závěrečný report by měl spojovat závěry s konkrétními řádky a daty pozorování.

V no-code scénáři lze stejné kroky propojit v automatizačním nástroji: plánování, HTTP požadavek podle ověřené konfigurace, kontrola odpovědi, uložení JSON, transformace potvrzených polí a upozornění na chybu. Nejprve ověřte kontrakt v Postmanu a poté jej přeneste do Pythonu, n8n nebo Make.

Očekávaný výsledek a další krok

Po nastavení bude mít tým archiv odpovědí API a tabulku pozorování pro vybrané hashtagy. Pomohou mu hledat nové příspěvky, porovnávat dostupné ukazatele v čase a vybírat materiály k podrobnější analýze. Aby byly výsledky srovnatelné, zachovávejte jednotný plán, parametry požadavků a pravidla normalizace.

Začněte jedním endpointem a jednou skutečnou odpovědí: odešlete požadavek na /getHashtagFeed s parametrem query, uložte JSON a teprve potom přidávejte zpracování polí a plánování. Stránka TikTok Scraper API uvádí základní adresu a přehled endpointů, zatímco specifikace endpointů obsahuje názvy parametrů pro implementaci klienta.