Slik unngår du å miste TikTok-søkeresultater når du behandler JSON

Når du søker etter videoer på TikTok via et API, kan videoene ligge i en annen matrise enn den behandleren først forventer. I et kontrollert svar fra jsonscraper på et kall til `/searchVideo` var feltet `aweme_list` tomt, mens elementer med videodata lå i `search_item_list[].aweme_info`. Hvis koden bare leser `aweme_list`, lagrer den null videoer selv om svaret inneholder treff. For utviklere er dette en konkret pålitelighetsoppgave: Hent ut begge dataformene og normaliser dem til én liste før du skriver til en database eller sender dataene til en rapport.

Du finner en kontroll av et konkret eksempel og beskrivelsen av endepunktet i API-spesifikasjonen til jsonscraper og dokumentasjonen for TikTok-endepunktet. Skjemautsnittet i spesifikasjonen er datert 25. oktober 2026. Det viser strukturen i et bestemt svar, men garanterer ikke at alle felter finnes i senere forespørsler.

Hvorfor en parser kan returnere en tom liste

Endepunktet `GET https://tiktok.evelode.com/searchVideo` søker etter videoer med den obligatoriske parameteren `keyword`. Dokumentasjonen oppgir også `cursor`, `count`, `cache_timeout`, `date_posted`, `sort_by` og `region`. I skjemaet for det observerte svaret inneholder toppnivåobjektet `status` og et nestet objekt kalt `tiktok`. Inne i dette finner du `cursor`, `has_more`, `status_code`, `aweme_list` og `search_item_list`.

I det konkrete eksempelet med et søkeord og `count=3` var matrisen `aweme_list` tom. Samtidig inneholdt `search_item_list` elementer med videoinformasjon i `aweme_info`. Disse objektene kunne inneholde video-ID, bildetekst, publiserings-URL, forfatter og statistikk som antall visninger, likerklikk eller kommentarer. Feltene som er beskrevet, gjenspeiler det observerte skjemaet; behandleren bør likevel håndtere verdier som mangler.

Den praktiske lærdommen er at en vellykket HTTP-forespørsel og en ikke-tom matrise i ett forventet felt er to ulike kontroller. Kontroller først den ytre statusen og at `tiktok` finnes, og hent deretter videoer fra alle dokumenterte steder. For analyse bør du lagre ID-en og det opprinnelige svaret, slik at du kan spore hvordan en bestemt oppføring ble hentet ut og normalisert.

Normaliser svaret før du lagrer det

En praktisk grense mellom API-et og ditt eget system er en funksjon som tar imot det nestede `tiktok`-objektet og returnerer enhetlige elementer. Den bør håndtere begge matrisene, hoppe over elementer som ikke er ordbøker eller som er tomme, og fjerne gjentatte videoer basert på `aweme_id`. La tellere stå tomme når leverandøren ikke returnerte dem: Null ville tilsi en målt verdi, mens `None` angir at feltet mangler.

Her er et minimalt eksempel for Python 3.8+. Det sender én forespørsel, kontrollerer transportstatus og status på toppnivå, normaliserer de to resultatvariantene og skriver ut utvalgte felter. Nøkkelen leses fra en miljøvariabel og skrives ikke til loggen.

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"),
    })

Installer avhengigheten med kommandoen python -m pip install requests, angi `JSONSCRAPER_TIKTOK_LICENSE_KEY` i kjøremiljøet og lagre filen, for eksempel som `search_videos.py`. Forespørselsparametrene samsvarer med de dokumenterte navnene: `keyword`, `count` og `region`; `license_key` sendes som en query-parameter. Koden forutsetter at svaret inneholder `status: "ok"`, slik det gjorde i det registrerte eksempelet. Hvis API-et returnerer en annen status, stopper behandlingen før en tvilsom datastruktur sendes videre.

Slik gjør du eksempelet om til en repeterbar innsamling

For en engangseksport holder det å skrive de normaliserte elementene til JSON Lines eller en tabell. I en kontinuerlig prosess bør du også lagre det opprinnelige svaret sammen med hentetidspunktet og søket. En egen tabell for normaliserte videoer kan bruke `aweme_id` som nøkkel: Gjentatte treff oppdaterer oppføringen, mens samme ID i begge matrisene ikke oppretter en duplikat.

For å be om neste side oppgir dokumentasjonen parameteren `cursor`: Send videre verdien du mottok i forrige svar. Behandle den som et ugjennomsiktig token – lagre og send den tilbake uten endringer. Pagineringen bør avsluttes når `has_more` viser at det ikke finnes flere resultater, eller når API-et ikke gir en brukbar markør. Begrens antallet sider per kjøring, slik at feil i logikken ikke skaper en evig løkke. De registrerte kildene bekrefter parameternavnet og at feltene `cursor` og `has_more` finnes i det observerte skjemaet, men de garanterer ikke at resultatene er fullstendige.

Hvis du overvåker flere søkefraser, lagrer du frasen sammen med video-ID-en og innsamlingstidspunktet. Da kan du lage oversikter per søk, sammenligne treff mellom kjøringer og sende nye ID-er til en kø for videre klassifisering. Et slikt system beskriver søkeresultatene du har mottatt; datasettet avhenger av søket, regionen, tidspunktet og hvilke elementer API-et faktisk returnerte.

Kontroller datakvaliteten, ikke bare om forespørselen lykkes

Etter normalisering kan det være nyttig å føre enkle tekniske målinger for datapipelinen: antall oppføringer fra hver matrise, antall unike ID-er, andelen elementer uten ID og andelen uten statistikk. Dette er målinger av behandlingen av et konkret svar, ikke vurderinger av hvor populære videoene er. Hvis for eksempel andelen elementer uten `play_count` øker, bør analysen bevare den ukjente verdien og merke feltet som ufullstendig i stedet for å sette inn null.

Ikke bygg videre beregninger på en antakelse om at alle videoer har det samme settet med statistikk. Behold hele JSON-svaret for rådata, og velg bare feltene du trenger i analysetabellen. Tillat `NULL`. Hvis svarformatet endres, gjør et arkiv av rådata det mulig å kjøre normalisereren på nytt uten å sende en ny forespørsel.

Oppbevar API-nøkkelen i CI-hemmeligheter eller som en miljøvariabel i orkestratoren. Ikke ta den med i URL-er som lagres i logger, skriv ut objektet med forespørselsparametere eller lagre nøkkelen sammen med råsvarene. Hvis jobben kjøres etter en tidsplan, bør du sette en tidsbegrensning for forespørselen, håndtere HTTP-feil og prøve på nytt med en pause. Lagre markøren sammen med det bestemte søket, slik at du ikke blander sider fra ulike søk.

Resultatet: én samlet tabell i stedet for videoer som faller ut

Etter normalisering får nedstrømskoden én liste med videoer, uansett om elementet kom fra `aweme_list` eller `search_item_list[].aweme_info`. ID-en gjør det mulig å fjerne duplikater, mens valgfrie felter forblir tydelig tomme. Dette reduserer risikoen for tomme rapporter fordi bare én matrise ble lest, og gjør neste trinn – eksport, filtrering eller klassifisering – mer forutsigbart.

Du kan starte kontrollen på siden for TikTok Scraper API, som oppgir API-ets basisadresse og har en lenke til en demo. Bruk den offisielle dokumentasjonen for integrasjonen, og kontroller først behandlingen med et lite antall elementer. Øk `count` ved behov, og fortsett gjennom resultatene med den dokumenterte markøren. Da får du et ryddig datalag for oppgavene dine, ikke en antakelse om at du har fått med alle videoene på TikTok.