Näin TikTok-haun tulokset eivät katoa JSONia käsiteltäessä

Kun TikTok-videoita haetaan API:n kautta, videot eivät välttämättä löydy siitä taulukosta, jota käsittelijä ensimmäiseksi odottaa. jsonscraperin testatussa `/searchVideo`-vastauksessa `aweme_list` oli tyhjä, ja videoiden tiedot löytyivät kohdasta `search_item_list[].aweme_info`. Jos koodi lukee vain `aweme_list`-taulukkoa, se tallentaa nolla videota, vaikka vastaus sisältää hakutuloksia. Kehittäjän kannalta kyse on konkreettisesta luotettavuusongelmasta: poimi tiedot molemmista rakenteista ja normalisoi ne yhdeksi listaksi ennen tietokantaan tallentamista tai raporttiin viemistä.

Esimerkkivastaukseen ja reitin kuvaukseen voi tutustua jsonscraperin API-määrityksessä ja TikTok-päätepisteen dokumentaatiossa. Määrityksessä oleva kaaviokuva on päivätty 25. lokakuuta 2026. Se havainnollistaa tietyn vastauksen rakennetta, mutta ei takaa, että kaikki kentät esiintyvät jokaisessa myöhemmässä pyynnössä.

Miksi jäsennin voi palauttaa tyhjän listan

Reitti `GET https://tiktok.evelode.com/searchVideo` etsii videoita pakollisen `keyword`-parametrin avulla. Dokumentaatiossa mainitaan myös parametrit `cursor`, `count`, `cache_timeout`, `date_posted`, `sort_by` ja `region`. Havaitun vastauksen skeemassa ylätason objekti sisältää kentät `status` ja sisäkkäisen `tiktok`-objektin. Sen sisällä ovat `cursor`, `has_more`, `status_code`, `aweme_list` ja `search_item_list`.

Yhdessä konkreettisessa havainnossa `aweme_list` oli tyhjä, kun pyyntö tehtiin avainsanalla ja parametrilla `count=3`. Samaan aikaan `search_item_list` sisälsi alkioita, joiden videotiedot olivat kentässä `aweme_info`. Näissä objekteissa saattoi olla videon tunniste, kuvateksti, julkaisun URL, tekijä ja tilastoja, kuten katselu-, tykkäys- tai kommenttimäärä. Kuvatut kentät perustuvat havaittuun skeemaan; käsittelijän on silti varauduttava puuttuviin arvoihin.

Käytännössä onnistunut HTTP-pyyntö ja tuloksen sisältävä arvo yhdessä odotetussa kentässä ovat kaksi eri asiaa. Tarkista ensin ulompi tila ja `tiktok`-objektin olemassaolo, ja kokoa sitten videot kaikista dokumentoiduista paikoista. Analytiikkaa varten tallenna tunnisteet ja alkuperäinen vastaus, jotta voit jäljittää, miten yksittäinen tietue poimittiin ja normalisoitiin.

Normalisoi vastaus ennen tallennusta

Sopiva rajapinta API:n ja oman järjestelmän välillä on funktio, joka ottaa sisäkkäisen `tiktok`-objektin ja palauttaa yhtenäiset alkiot. Sen pitää käsitellä molemmat taulukot, ohittaa muut kuin sanakirjamuotoiset tai tyhjät alkiot ja poistaa saman videon toistot `aweme_id`-kentän perusteella. Jätä laskurit tyhjiksi, jos palveluntarjoaja ei palauttanut niitä: nolla tarkoittaisi mitattua arvoa, kun taas `None` ilmaisee kentän puuttuvan.

Alla on pelkistetty esimerkki Python 3.8:lle ja uudemmille versioille. Se tekee yhden pyynnön, tarkistaa verkkopyynnön ja ylätason tilan, normalisoi tuloksen kaksi mahdollista rakennetta ja tulostaa valitut kentät. Avain luetaan ympäristömuuttujasta eikä sitä tulosteta lokiin.

import os
import requests

BASE_URL = "https://tiktok.evelode.com"


def extract_videos(tiktok):
    candidates = []
    aweme_list = tiktok.get("aweme_list") or []
    if isinstance(aweme_list, list):
        candidates.extend(aweme_list)

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

    unique = {}
    for video in candidates:
        if not isinstance(video, dict):
            continue
        video_id = video.get("aweme_id")
        if video_id:
            unique[video_id] = video
    return list(unique.values())


license_key = os.environ["JSONSCRAPER_TIKTOK_LICENSE_KEY"]
response = requests.get(
    BASE_URL + "/searchVideo",
    params={
        "license_key": license_key,
        "keyword": "python tutorial",
        "count": 10,
        "region": "US",
    },
    timeout=30,
)
response.raise_for_status()
payload = response.json()

if payload.get("status") != "ok":
    raise RuntimeError("TikTok API returned a non-ok status")

tiktok = payload.get("tiktok")
if not isinstance(tiktok, dict):
    raise RuntimeError("Response has no tiktok object")

for video in extract_videos(tiktok):
    stats = video.get("statistics") or {}
    author = video.get("author") or {}
    print({
        "aweme_id": video.get("aweme_id"),
        "desc": video.get("desc"),
        "share_url": video.get("share_url"),
        "author": author.get("unique_id"),
        "play_count": stats.get("play_count"),
        "digg_count": stats.get("digg_count"),
        "comment_count": stats.get("comment_count"),
    })

Asenna riippuvuus komennolla python -m pip install requests, aseta `JSONSCRAPER_TIKTOK_LICENSE_KEY` suoritusympäristöön ja tallenna tiedosto esimerkiksi nimellä `search_videos.py`. Pyynnön parametrit vastaavat dokumentoituja nimiä: `keyword`, `count` ja `region`; `license_key` välitetään kyselyparametrina. Koodi olettaa, että vastauksen tila on `status: "ok"`, kuten tallennetussa esimerkissä. Jos API palauttaa muun tilan, käsittely pysähtyy ennen epäilyttävän rakenteen välittämistä eteenpäin.

Tee esimerkistä toistettava tiedonkeruu

Kertavientiä varten normalisoidut alkiot voi tallentaa JSON Lines -tiedostoon tai taulukkoon. Jatkuvassa prosessissa tallenna alkuperäinen vastaus sekä hakuhetki ja hakulauseke. Normalisoitujen videoiden erillisessä taulukossa `aweme_id` voi toimia avaimena: toistuva tulos päivittää tietueen, eikä kahdessa taulukossa esiintyvä sama tunniste luo kaksoiskappaletta.

Seuraavan sivun hakemiseen dokumentaatio määrittää `cursor`-parametrin: välitä siinä edellisestä vastauksesta saatu arvo. Käsittele sitä läpinäkymättömänä tunnisteena ja tallenna sekä palauta se muuttamatta. Sivutuksen on loputtava, kun `has_more` ei ilmaise jatkumista tai API ei anna käyttökelpoista kursoria. Rajoita sivujen määrä yhtä suoritusta kohti, jotta virheellinen logiikka ei aiheuta päättymätöntä silmukkaa. Käytettävissä olevat lähteet vahvistavat parametrin nimen sekä `cursor`- ja `has_more`-kenttien esiintymisen havaitussa skeemassa, mutta eivät takaa tulosten kattavuutta.

Jos valvot useita hakulausekkeita, tallenna lauseke videon tunnisteen ja keruuajan rinnalle. Näin voit muodostaa hakukohtaisia näkymiä, vertailla tuloksia eri ajokerroilla ja lähettää uudet tunnisteet jatkoluokittelun jonoon. Järjestelmä kuvaa haussa saatuja tuloksia; tietoaineisto riippuu hakulausekkeesta, alueesta, ajankohdasta ja API:n tosiasiassa palauttamista alkioista.

Tarkista tiedon laatu, älä vain pyynnön onnistumista

Normalisoinnin jälkeen kannattaa seurata prosessin yksinkertaisia teknisiä mittareita: kunkin taulukon tietuemäärää, yksilöllisten tunnisteiden määrää sekä sitä, kuinka suuri osuus alkioista on ilman tunnistetta tai tilastoja. Nämä mittarit kuvaavat yksittäisen vastauksen käsittelyä, eivät videoiden suosiota. Jos esimerkiksi ilman `play_count`-kenttää olevien alkioiden määrä kasvaa, analytiikan kannattaa säilyttää arvo tuntemattomana ja merkitä kentän kattavuus sen sijaan, että tilalle asetetaan nolla.

Älä rakenna jatkolaskentaa sen varaan, että jokaisella videolla on aina samat tilastotiedot. Säilytä raakadataa varten koko JSON ja valitse analytiikkataulukkoon vain tarvittavat kentät; salli niiden arvoiksi myös `NULL`. Jos vastauksen rakenne muuttuu, alkuperäiseen arkistoon tallennetut tiedot mahdollistavat normalisoinnin suorittamisen uudelleen ilman uutta pyyntöä.

Välitä API-avain CI-järjestelmän salaisuuksien tai orkestroijan ympäristömuuttujien kautta. Älä lisää sitä lokiin tallennettaviin URL-osoitteisiin, tulosta pyynnön parametriobjektia tai tallenna avainta alkuperäisten vastausten yhteyteen. Jos suoritus on ajastettu, lisää aikaraja pyynnölle, HTTP-virheiden käsittely ja viiveellä tehtävät uudelleenyritykset. Tallenna kursori aina yhdessä tietyn hakulausekkeen kanssa, jotta eri hakujen sivut eivät sekoitu.

Tuloksena yksi yhtenäinen taulukko, ei ohitettuja videoita

Normalisoinnin jälkeen jatkokoodi saa yhden videolistan riippumatta siitä, tuliko alkio `aweme_list`-taulukosta vai kohdasta `search_item_list[].aweme_info`. Tunnisteen avulla toistot voidaan poistaa, ja valinnaiset kentät jäävät selvästi tyhjiksi. Tämä vähentää riskiä, että raportit jäävät tyhjiksi vain siksi, että koodi luki yhtä taulukkoa, ja tekee seuraavasta vaiheesta — viennistä, suodatuksesta tai luokittelusta — ennakoitavamman.

Aloita tarkistus TikTok Scraper API -sivulta, jolla kerrotaan API:n perusosoite ja josta pääsee demoon. Käytä integraatiossa virallista dokumentaatiota ja testaa käsittely ensin pienellä alkiomäärällä. Suurenna tarvittaessa `count`-arvoa ja jatka tulosten hakua dokumentoidulla kursorilla. Näin saat käyttötarkoituksiisi siistin tietokerroksen ilman oletusta siitä, että kaikki TikTokin sisältö olisi mukana.