TikTok Scraper API: jak získat data o videu v JSON pomocí jsonscraper

Pokud aplikace potřebuje informace o konkrétním videu na TikToku, je nejjednodušší začít jedním požadavkem a ověřit, jaká data vrací. Poté lze odpověď ověřit a připravit k uložení nebo analýze.

Na stránce TikTok Scraper API od jsonscraper jsou uvedeny trasy pro videa, uživatele, vyhledávání, hashtagy, hudbu a další typy dat. Níže si ukážeme zdokumentovaný požadavek getVideoByID a způsoby, jak jeho odpověď bezpečně zpracovat. Příklady vycházejí z materiálů poskytovatele; před použitím je ověřte s platným klíčem a aktuální dokumentací.

První požadavek: získání informací o videu

V dokumentaci getVideoByID v Postmanu je uvedena metoda GET a parametr video_id. Příklad také ukazuje parametry region a cache_timeout. Základní adresa zveřejněná na stránce služby je https://tiktok.evelode.com.

Ukázkový požadavek přes cURL:

export JSONSCRAPER_LICENSE_KEY="váš_klíč"

curl --get "https://tiktok.evelode.com/getVideoByID" \
  --data-urlencode "video_id=7106855913906081070" \
  --data-urlencode "license_key=$JSONSCRAPER_LICENSE_KEY" \
  --data-urlencode "region=US"

ID v příkladu pochází ze zveřejněného požadavku. Nahraďte ho ID videa, které chcete ověřit. Klíč uchovávejte v proměnné prostředí nebo správci tajných údajů; nevkládejte ho do veřejného repozitáře, klientského JavaScriptu ani protokolů.

Postman popisuje region jako kód regionu a jako výchozí hodnotu uvádí US. U parametru cache_timeout dokumentace uvádí výchozí dobu ukládání do mezipaměti 3600 sekund; hodnota 0 ukládání do mezipaměti vypíná. Pokud tento parametr potřebujete, můžete ho předat výslovně:

curl --get "https://tiktok.evelode.com/getVideoByID" \
  --data-urlencode "video_id=7106855913906081070" \
  --data-urlencode "license_key=$JSONSCRAPER_LICENSE_KEY" \
  --data-urlencode "region=US" \
  --data-urlencode "cache_timeout=0"

Jde o úpravu parametrů zveřejněných pro tuto trasu, nikoli o záruku, že všechny odpovědi budou mít stejnou strukturu nebo že vypnutí ukládání do mezipaměti bude vhodné pro každý úkol. Před nasazením ověřte způsob autorizace a parametry v aktuální kolekci: Postman může předávat klíč prostřednictvím nakonfigurovaného API Key, zatímco výše uvedený příklad cURL ho ukazuje jako parametr URL.

Stejný požadavek v Pythonu

Níže je varianta využívající standardní knihovnu Pythonu. Vytvoří požadavek GET, předá parametry a ošetří síťovou chybu, chybu HTTP i neplatný JSON.

import json
import os
from urllib.error import HTTPError, URLError
from urllib.parse import urlencode
from urllib.request import Request, urlopen

base_url = "https://tiktok.evelode.com/getVideoByID"
license_key = os.environ.get("JSONSCRAPER_LICENSE_KEY")

if not license_key:
    raise RuntimeError("Nastavte proměnnou JSONSCRAPER_LICENSE_KEY")

params = {
    "video_id": "7106855913906081070",
    "license_key": license_key,
    "region": "US",
}

url = f"{base_url}?{urlencode(params)}"
request = Request(url, method="GET")

try:
    with urlopen(request, timeout=30) as response:
        status_code = response.status
        payload = json.loads(response.read().decode("utf-8"))
except HTTPError as error:
    print(f"Chyba HTTP: {error.code}")
    raise
except URLError as error:
    print(f"Síťová chyba: {error.reason}")
    raise
except json.JSONDecodeError:
    raise RuntimeError("Odpověď služby se nepodařilo zpracovat jako JSON")

print("Stav HTTP:", status_code)
print("Klíče nejvyšší úrovně:", list(payload.keys()))

Jde o úpravu zdokumentovaného požadavku, nikoli o příklad, který by poskytovatel samostatně testoval pro Python. Nezachycuje ani všechny možné odpovědi služby. Protože se klíč předává v URL, nevypisujte do protokolů celou URL: může obsahovat tajný údaj.

Jak kontrolovat odpověď JSON

Ve zveřejněné odpovědi v Postmanu je pole status a vnořený objekt tiktok.aweme_detail s údaji o videu a autorovi. Jde o ukázku struktury jedné odpovědi, nikoli o záruku neměnného schématu. Prohlédnout si ji můžete v ukázce odpovědi pro getVideoByID.

Při čtení vnořených polí kontrolujte každou úroveň:

def get_video_details(payload):
    tiktok = payload.get("tiktok")
    if not isinstance(tiktok, dict):
        return None

    details = tiktok.get("aweme_detail")
    if not isinstance(details, dict):
        return None

    return details

details = get_video_details(payload)

if details is None:
    print("Odpověď neobsahuje očekávaný objekt s údaji o videu")
else:
    video_id = details.get("id")
    description = details.get("desc")
    author = details.get("author")

    print("ID:", video_id)
    print("Popis:", description)
    print("Autor:", author)

Názvy polí pocházejí ze zveřejněného příkladu. Kontrola pomocí .get() neznamená, že jsou pole povinná: umožňuje zpracovat odpověď, ve které očekávané hodnoty chybí. Pokud logika aplikace závisí na konkrétním poli, ověřte jeho přítomnost v odpovědích pro svůj scénář a počítejte s tím, že může chybět.

Užitečné je rozlišovat tři kontroly:

1. Přenos: zda byla přijata odpověď HTTP a jaký má stav.
2. Formát: zda se tělo podařilo zpracovat jako JSON.
3. Obsah: zda jsou k dispozici údaje, které aplikace potřebuje.

Úspěšné zpracování JSON ještě neznamená, že odpověď obsahuje požadovaný objekt. Pro diagnostiku zaznamenávejte technické chyby a výsledky kontrol, ale klíče maskujte.

Od jednoho požadavku k funkčnímu procesu

Pro prototyp stačí odeslat požadavek a vypsat několik hodnot. Při pravidelném zpracování rozdělte práci do jednotlivých kroků:

Požadavek → kontrola → normalizace → deduplikace → uložení.

• Požadavek. Získejte odpověď prostřednictvím zdokumentované trasy a technický stav uložte zvlášť.
• Kontrola. Ověřte, že lze tělo zpracovat jako JSON a že obsahuje údaje potřebné pro konkrétní úkol.
• Normalizace. Přeneste potřebné hodnoty do vlastního datového modelu. Nekopírujte do databáze celou vnořenou strukturu, pokud aplikace potřebuje jen několik polí.
• Deduplikace. Zvolte identifikátor až poté, co ověříte, že je přítomen a pro váš úkol vhodný. Nepředpokládejte, že bude vždy dostupný ve všech odpovědích.
• Uložení. V případě potřeby ukládejte čas požadavku a původní odpověď odděleně od normalizovaného záznamu. Pomůže vám to zjistit, jaké změny provedla aplikace.

Jde o doporučení pro návrh aplikace, nikoli o funkce, které by se měly připisovat službě. Oddělení externí odpovědi od interního modelu také usnadňuje řešení změn: problémy lze hledat ve fázi kontroly nebo normalizace, nikoli v celém kódu.

U opakovaných požadavků předem určete, kdy data aktualizovat a které chyby má smysl zkusit znovu. Omezte počet opakovaných pokusů: nekonečná smyčka nepomůže napravit chybný parametr ani problém s autorizací.

Ukládání do mezipaměti a region

V popisu trasy getVideoByID parametr cache_timeout určuje dobu ukládání do mezipaměti v sekundách: jako výchozí hodnota je uvedeno 3600 sekund a hodnota 0 ukládání do mezipaměti vypíná. Parametr region je popsán jako kód země; v dokumentaci je uveden příklad US. Před nasazením si tyto informace ověřte v aktuální dokumentaci požadavku v Postmanu.

Samotná možnost nastavit mezipaměť nepotvrzuje aktuálnost konkrétní odpovědi. Pokud je aktuálnost důležitá, ověřte výsledky opakovaných požadavků na datech svého scénáře a zvolte vhodné chování.

Jaké úkoly prozkoumat dál

Na stránce produktu jsou uvedeny trasy pro vyhledávání videí a uživatelů, hashtagů, míst, hudby a trendů. Mezi příklady patří searchVideo, searchHashtag, getUserFeed a getTrendingFeed. Jde o mapu tras zveřejněnou poskytovatelem, nikoli o nezávislé ověření každé z nich. Parametry a strukturu odpovědi si prostudujte v dokumentaci konkrétní trasy: nelze je automaticky převzít z příkladu getVideoByID.

jsonscraper doporučuje použít kolekci Postman k nastavení klíče a spouštění požadavků. Může to být pohodlný způsob, jak ověřit konkrétní trasu před napsáním integrace. Služba uvádí také scénáře automatizace, kompatibilitu konkrétního procesu však ověřte samostatně ve vlastní konfiguraci. Při exportu kolekce nebo jejím sdílení se ujistěte, že v ní nezůstal aktivní klíč.

Co ověřit před použitím v aplikaci

Než požadavek zařadíte do pravidelného procesu, otestujte ho s videem a parametry, které projekt potřebuje:

• Zda požadavek funguje s platným klíčem a správným ID.
• Jak aplikace zpracovává nesprávný nebo chybějící parametr.
• Co se stane, pokud je JSON platný, ale požadované pole chybí.
• Jak se zpracuje chyba HTTP, výpadek sítě a vypršení časového limitu.
• Která pole jsou vhodná k identifikaci a deduplikaci právě ve vašem úkolu.
• Jak se změní výsledek opakovaného požadavku při různých hodnotách cache_timeout, pokud tento parametr používáte.

Zaznamenejte datum kontroly, parametry bez tajných údajů a anonymizovaný příklad odpovědi. Jeden úspěšný požadavek potvrzuje pouze fungování konkrétního scénáře za konkrétních podmínek; nedokazuje stabilitu všech tras a odpovědí.

Začněte jedním reprodukovatelným scénářem

Ověřte getVideoByID u požadovaného videa, prohlédněte si skutečný JSON a napište obsluhu, která počítá s chybějícími poli a chybami. Poté podle potřeby rozšiřte proces o normalizaci, deduplikaci a ukládání.

Dokumentace jsonscraper poskytuje výchozí bod – základní adresu a přehled tras. V produkčním kódu je přesto nutné ověřovat konkrétní odpověď, chránit klíč a počítat s případy, kdy se data liší od očekávané struktury.