TikTok: Näin tarkistat, toimiiko hakuseuranta todella

HTTP 200 ei takaa, että TikTokin päivittäinen seuranta on kerännyt videoita. Hakutulokset voivat olla joko aweme_list-taulukossa tai kohdassa search_item_list[].aweme_info; skripti, joka lukee vain ensimmäistä taulukkoa, voi päättyä virheettä ja tallentaa tyhjän raportin. Luotettava tarkistus varmistaa erikseen siirtotason ja sovellustason tilan, poimii tiedot molemmista tuetuista rakenteista ja kirjaa, montako yksilöllistä videota suorituksella saatiin talteen.

Mitä kannattaa diagnosoida

Kuvitellaan tehtävä, jossa tiimi kerää joka aamu julkisia videoita useilla hakutermeillä löytääkseen uusia tuotetta koskevia julkaisuja. Prosessin tärkeä tulos on toistettava luettelo löydetyistä tietueista sekä niiden kuvauksista, tekijöistä, julkaisupäivistä ja saatavilla olevista mittareista. Jos raportti on yhtäkkiä tyhjä, syynä voi olla JSON-käsittely, muuttunut hakutulosjoukko, aiemmin tunnettujen videoiden toistuminen tai varsinainen pyyntövirhe. Yksi luku, kuten aweme_list-taulukon pituus, ei auta erottamaan näitä tilanteita.

jsonscraper TikTok Scraper API:n hakureitti /searchVideo edellyttää parametria keyword ja hyväksyy lisäksi parametrit count, cursor, date_posted, sort_by ja region. Reitin dokumentaatio kuvaa sivutuksen cursor-arvon avulla; välitä se läpinäkymättömänä arvona edellisestä vastauksesta. Parametri count määrittää halutun tulosten määrän, mutta ei takaa kaikkien julkaisujen kattavaa löytymistä.

Jaa tarkistus neljään signaaliin

Hyödyllinen diagnostiikka koostuu neljästä toisistaan riippumattomasta tarkistuksesta. Ensimmäinen: HTTP-pyyntö onnistui. Toinen: vastauksen ulompi status on ok ja sisempi tiktok.status_code vastaa onnistunutta vastausta. Kolmas: tiktok-objekti on mukana ja tietueet voidaan poimia vastauksen molemmista dokumentoiduista kohdista. Neljäs: deduplikoinnin jälkeen jäljelle jää tietueita, joilla on tallennukseen sopivat tunnisteet. Tallenna lokiin poimittujen kohteiden määrä sekä ennen deduplikointia että sen jälkeen: erotus kertoo, syntyikö toistoja normalisointivaiheessa.

Jos kenttä puuttuu, jätä se tyhjäksi äläkä korvaa sitä keksityllä arvolla. Esimerkiksi katselukertojen määrä voi puuttua yksittäisestä tietueesta. Alkuperäisen JSON-vastauksen tallentaminen normalisoidun rivin rinnalle auttaa myöhemmin tarkistamaan, katosiko tieto jäsennyksessä vai puuttuiko se jo alkuperäisestä vastauksesta.

Yksinkertainen pyyntö ja normalisointi Pythonilla

jsonscraperin määritys ilmoittaa perusosoitteeksi https://tiktok.evelode.com ja avaimen välitystavaksi kyselyparametrin license_key. Alla oleva esimerkki käyttää dokumentoituja parametreja; avain luetaan ympäristömuuttujasta eikä sitä tulosteta lokiin. Asenna riippuvuus komennolla python -m pip install requests ja määritä sitten JSONSCRAPER_TIKTOK_LICENSE_KEY ympäristöön.

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

import requests

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


def extract_videos(payload):
    """Kokoa videot hakuvastauksen molemmista tunnetuista rakenteista."""
    tiktok = payload.get("tiktok") or {}
    videos = []

    for item in tiktok.get("aweme_list") or []:
        if isinstance(item, dict):
            videos.append(item)

    for item in tiktok.get("search_item_list") or []:
        if isinstance(item, dict):
            aweme = item.get("aweme_info")
            if isinstance(aweme, dict):
                videos.append(aweme)

    return videos


def main():
    params = {
        "license_key": KEY,
        "keyword": "esimerkkihaku tuotteesta",
        "count": 20,
        "region": "US",
    }
    response = requests.get(BASE_URL, params=params, timeout=30)
    response.raise_for_status()
    payload = response.json()

    if payload.get("status") != "ok":
        raise RuntimeError("API palautti muun ulomman tilan kuin ok")

    tiktok = payload.get("tiktok")
    if not isinstance(tiktok, dict):
        raise RuntimeError("Vastauksesta puuttuu tiktok-objekti")

    if tiktok.get("status_code") != 0:
        raise RuntimeError("Sisempi status_code ei ole onnistumista vastaava arvo 0")

    raw_videos = extract_videos(payload)
    unique = {}
    for video in raw_videos:
        video_id = video.get("aweme_id")
        if video_id:
            unique.setdefault(str(video_id), video)

    snapshot = {
        "collected_at": datetime.now(timezone.utc).isoformat(),
        "keyword": params["keyword"],
        "status": payload.get("status"),
        "status_code": tiktok.get("status_code"),
        "raw_items": len(raw_videos),
        "unique_items": len(unique),
        "has_more": tiktok.get("has_more"),
        "cursor": tiktok.get("cursor"),
        "videos": list(unique.values()),
    }

    Path("snapshots").mkdir(exist_ok=True)
    stamp = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ")
    Path(f"snapshots/{stamp}.json").write_text(
        json.dumps(snapshot, ensure_ascii=False, indent=2),
        encoding="utf-8",
    )

    print({
        "status": snapshot["status"],
        "status_code": snapshot["status_code"],
        "raw_items": snapshot["raw_items"],
        "unique_items": snapshot["unique_items"],
        "has_more": snapshot["has_more"],
    })


if __name__ == "__main__":
    main()

Skripti tarkistaa siirtotason kutsumalla raise_for_status()-metodia ja varmistaa sen jälkeen ulomman tilan, tiktok-objektin olemassaolon sekä sisemmän status_code-arvon. Sitten se poimii tietueet kahdesta hakurakenteesta, deduplikoi ne aweme_id-tunnisteen perusteella ja tallentaa tilannekuvan keruuajankohtineen. Vaikka sopivia tietueita ei olisi, tiedostoon tallentuu silti suorituksen tiedot, jolloin tallennetun tyhjän tuloksen voi erottaa puuttuvasta raportista.

Muuta tilannekuvat tiimin signaaliksi

Aja skripti aikataulutetusti cronilla, CI:llä tai työnkulun ajastimella. Tallenna kunkin haun tilannekuvat erikseen tai lisää hakusana tiedostonimeen. Tilannetaulukkoon riittää käynnistysaika, tila, poimittujen ja yksilöllisten tietueiden määrä sekä has_more-lippu. Ilmoitus kannattaa lähettää, jos pyyntö aiheuttaa poikkeuksen, pakollisia vastausosia puuttuu tai poimittujen tietueiden määrä muuttuu jyrkästi suhteessa omaan historiaan.

Tällainen vertailu paljastaa putken poikkeaman, mutta ei yksin selitä sen syytä. Tulosten pienempi määrä voi johtua senhetkisestä hakutulosjoukosta eikä API:n tai jäsentimen rikkoutumisesta. Siksi alkuperäinen JSON kannattaa tallentaa, pyyntöparametrit pitää samoina ja löydetyt tunnisteet tarkistaa. Valitse ilmoituskynnys juuri oman hakusi havaintojen, älä yleispätevän lukuarvon perusteella.

Käytä sivutuksessa vastauksesta saatua cursor-arvoa ja lopeta haku, kun API ilmoittaa, ettei seuraavia tuloksia ole. Tallenna käytetyt kursorit ja pyyntöparametrit, jotta suoritus voidaan toistaa. Parametreilla date_posted ja sort_by voi määrittää aikarajauksen ja järjestyksen; jos tehtävä edellyttää toistettavia vertailuja, pidä ne samoina ajosta toiseen.

Näin tulkitset tuloksen

Käyttöönoton jälkeen tiimi saa tarkistettavan vastauksen kolmeen käytännön kysymykseen: onnistuiko pyyntö, missä tulokset sijaitsevat JSONissa ja montako yksilöllistä videota tallennettuun tilannekuvaan sisältyy. Näin tyhjän taulukon syyn selvittämiseen kuluu vähemmän aikaa: tarkista ensin tilat ja rakenne, sitten parametrit, toistot ja alkuperäisen vastauksen sisältö.

Vastauksen rakenne ja saatavilla olevat kentät voivat vaihdella tietueittain. jsonscraperin 25. lokakuuta 2026 tekemässä reaaliaikaisessa tarkistuksessa haku palautti tunnisteen, kuvauksen, tekijän ja tilastot sisältäviä kenttiä; yksittäisen tietueen arvoja on silti pidettävä valinnaisina. Toimiva raportti säilyttää tosiasiassa saadut tiedot eikä korvaa puuttuvia arvoja nollilla.

Aloita TikTok Scraper API -sivulta ja tarkista tarkat reitit ja parametrit API:n virallisesta dokumentaatiosta. Tällainen tarkistus kannattaa tehdä ennen seurannan käynnistämistä: raportista tulee havaittava tulos, jonka laatua voi diagnosoida.