Så förlorar du inte TikToks sökresultat när du tolkar JSON

När du söker efter videor på TikTok via ett API kan videorna ligga i en annan array än den som din hanterare först förväntar sig. I ett verifierat svar från jsonscraper på en begäran till `/searchVideo` var fältet `aweme_list` tomt, medan videoobjekten låg i `search_item_list[].aweme_info`. Om koden bara läser `aweme_list` sparas noll videor, trots att svaret innehåller träffar. För utvecklaren är detta en konkret tillförlitlighetsfråga: hämta data från båda strukturerna och normalisera dem till en enda lista innan de skrivs till en databas eller skickas till en rapport.

Du kan granska ett liveexempel och beskrivningen av endpointen i jsonscrapers API-specifikation och dokumentationen för TikTok-endpointen. Ögonblicksbilden av schemat i specifikationen är daterad 25 oktober 2026. Den visar strukturen hos ett specifikt svar, men garanterar inte att varje fält finns med i alla framtida anrop.

Därför kan en parser returnera en tom lista

Endpointen `GET https://tiktok.evelode.com/searchVideo` söker efter videor med den obligatoriska parametern `keyword`. Dokumentationen listar även `cursor`, `count`, `cache_timeout`, `date_posted`, `sort_by` och `region`. I det observerade svarets schema innehåller det överordnade objektet `status` och ett nästlat objekt, `tiktok`. Det senare innehåller `cursor`, `has_more`, `status_code`, `aweme_list` och `search_item_list`.

I den specifika observationen av en begäran med ett sökord och `count=3` var arrayen `aweme_list` tom. Samtidigt innehöll `search_item_list` element med videoinformation i `aweme_info`. Dessa objekt kunde innehålla video-ID, bildtext, publicerings-URL, skapare och statistik, till exempel antal visningar, gilla-markeringar eller kommentarer. Fälten som beskrivs återspeglar det observerade schemat; hanteraren bör ändå klara av att värden saknas.

Den praktiska slutsatsen är att en lyckad HTTP-begäran och en icke-tom array i ett förväntat fält är två olika kontroller. Kontrollera först den yttre statusen och att `tiktok` finns, och hämta sedan videor från alla dokumenterade platser. Spara ID:n och det ursprungliga svaret för analys, så att du kan spåra hur en viss post hämtades och normaliserades.

Normalisera svaret innan du sparar det

En bra gräns mellan API:t och ditt eget system är en funktion som tar emot det nästlade objektet `tiktok` och returnerar enhetliga element. Den ska hantera båda arrayerna, hoppa över element som inte är dictionary-objekt eller är tomma och eliminera dubbletter av samma video baserat på `aweme_id`. Lämna räknare tomma när leverantören inte returnerar dem: noll skulle betyda ett uppmätt värde, medan `None` anger att fältet saknas.

Nedan följer ett minimalt exempel för Python 3.8+. Det gör ett anrop, kontrollerar transport- och toppnivåstatus, normaliserar de två resultatformaten och skriver ut utvalda fält. Nyckeln läses från en miljövariabel och skrivs inte ut i 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"),
    })

Installera beroendet med kommandot python -m pip install requests, ange `JSONSCRAPER_TIKTOK_LICENSE_KEY` i körmiljön och spara filen, till exempel som `search_videos.py`. Begäransparametrar följer de dokumenterade namnen: `keyword`, `count` och `region`; `license_key` skickas som en queryparameter. Koden förutsätter att svaret innehåller `status: "ok"`, som i det dokumenterade exemplet. Om API:t returnerar en annan status avbryts körningen innan en osäker struktur skickas vidare.

Gör exemplet till en återkommande insamling

För en engångsexport räcker det att skriva de normaliserade elementen till JSON Lines eller en tabell. I en löpande process bör du även spara originalsvaret tillsammans med insamlingstid och sökfråga. En separat tabell med normaliserade videor kan använda `aweme_id` som nyckel: en upprepad träff uppdaterar posten, och samma ID i båda arrayerna skapar ingen dubblett.

För att hämta nästa sida anger dokumentationen parametern `cursor`: skicka vidare värdet från föregående svar. Behandla det som en ogenomskinlig token – spara och returnera den utan att ändra den. Pagineringen ska avslutas när `has_more` visar att det inte finns fler resultat eller när API:t inte tillhandahåller en användbar markör. Begränsa antalet sidor per körning så att felaktig logik inte skapar en oändlig loop. De tillgängliga källorna bekräftar parameternamnet och att fälten `cursor` och `has_more` förekommer i det observerade schemat, men de garanterar inte att resultaten är fullständiga.

Om du övervakar flera sökfraser ska du spara frasen tillsammans med videons ID och insamlingstid. Då kan du skapa sammanställningar per sökfråga, jämföra resultat mellan körningar och skicka nya ID:n till en kö för vidare klassificering. Ett sådant system beskriver de sökresultat som faktiskt hämtats; datamängden beror på sökfråga, region, tidpunkt och vilka element API:t returnerar.

Kontrollera datakvaliteten, inte bara om anropet lyckades

Efter normaliseringen är det bra att följa några enkla tekniska mått för din datapipeline: antal poster från respektive array, antal unika ID:n och andelen element utan ID respektive utan statistik. Det här är mått på hur ett visst svar har behandlats, inte uppskattningar av videornas popularitet. Om antalet element utan `play_count` exempelvis ökar bör analysen behålla värdet som okänt och markera att fältet är ofullständigt, i stället för att fylla i noll.

Utgå inte från att alla videor har samma uppsättning statistik när du gör efterföljande beräkningar. Spara hela JSON-svaret som rådata och välj bara de fält du behöver i analystabellen; tillåt `NULL`. Om svarsformatet ändras kan du köra normaliseraren på nytt med hjälp av arkivet, utan att göra en ny begäran.

Hantera API-nyckeln med CI-hemligheter eller orkestratorns miljövariabler. Ta inte med den i URL:er som sparas i loggar, skriv inte ut begäransparametrarna och spara inte nyckeln tillsammans med originalsvaret. Om körningen är schemalagd bör du lägga till en tidsgräns för anrop, hantering av HTTP-fel och återförsök med pauser. Spara markören tillsammans med den specifika sökfrågan så att sidor från olika sökningar inte blandas ihop.

Resultatet: en enhetlig tabell i stället för missade videor

Efter normaliseringen får efterföljande kod en enda lista med videor, oavsett om ett element kom från `aweme_list` eller `search_item_list[].aweme_info`. ID:t gör det möjligt att ta bort dubbletter, medan valfria fält förblir uttryckligen tomma. Det minskar risken för tomma rapporter som beror på att bara en array läses, och gör nästa steg – export, filtrering eller klassificering – mer förutsägbart.

Du kan börja med att granska sidan för TikTok Scraper API, där basadressen till API:t anges och du hittar en länk till en demo. Använd den officiella dokumentationen för integrationen och testa först hanteringen med ett litet antal element. Öka vid behov `count` och fortsätt genom resultaten med den dokumenterade markören. Då får du ett ordnat datalager för dina uppgifter, utan att förutsätta att resultaten täcker hela TikTok.