Een wekelijks TikTok-rapport maken over reacties op een productlancering

Na de lancering van een app of nieuwe functie raakt feedback al snel verspreid over korte video’s. Een marketeer vindt handmatig enkele video’s en stuurt links door in een chat, waarna een analist later niet meer kan achterhalen welke berichten al zijn meegenomen en hoe het aantal weergaven veranderde. Een praktische oplossing is om regelmatig zoekresultaten voor een aantal vaste zoekopdrachten te verzamelen, de oorspronkelijke antwoorden op te slaan en een rapport op te stellen op basis van bevestigde velden.

In deze handleiding richten we zo’n verzameling in voor een concreet geval: een team heeft een nieuwe functie uitgebracht en wil wekelijks openbare TikTok-video’s volgen waarvan de beschrijving de productnaam, een belangrijke functie of een veelvoorkomend gebruikersprobleem bevat. Dit is monitoring van een gevonden zoeksteekproef: de API retourneert resultaten op basis van de zoekopdracht en parameters, geen gegarandeerde lijst van alle berichten over de lancering.

Bepaal eerst welk signaal het team nodig heeft

Een groot aantal weergaven verklaart op zichzelf niet goed wat het team vervolgens moet doen. Het is nuttiger om te weten welke vragen terugkeren, welke gebruiksscenario’s mensen laten zien en welke video’s opvallende openbare reacties krijgen. Formuleer daarom eerst enkele zoektermen en bepaal welke velden in het rapport komen.

Bij de lancering van een tool voor het plannen van berichten kun je bijvoorbeeld zoeken op ‘productnaam’, ‘contentplanner’ en ‘hoe plan ik een TikTok in’. De termen moeten verschillende manieren weerspiegelen waarop mensen hetzelfde onderwerp kunnen omschrijven. Noteer ze samen met de startdatum van de monitoring en de regio, zodat je latere exports onder dezelfde instellingen kunt vergelijken.

Een minimale tabel kan de verzameltijd, zoekterm, video-ID, link, beschrijving, auteursnaam, auteur-ID en beschikbare aantallen weergaven, vind-ik-leuks en reacties bevatten. De TikTok Scraper API documenteert voor zoekresultaten velden als aweme_id, desc, share_url, auteursgegevens en een deel van de statistieken. Controleer elk veld in ieder afzonderlijk object: sommige statistieken kunnen ontbreken.

Gebruik de gedocumenteerde zoekfunctie

Zoek video’s via de GET-route /searchVideo op het basisadres https://tiktok.evelode.com. De documentatie vermeldt de verplichte parameter keyword en de aanvullende parameters count, cursor, date_posted, sort_by, region en cache_timeout. Geldige waarden voor het datumfilter zijn onder meer this-week; sorteermogelijkheden zijn relevance, most-liked en date-posted. Raadpleeg de documentatie van de TikTok API-routes voor de betekenis en namen ervan.

Geef de licentiesleutel mee als queryparameter license_key. Lees deze in een productiescript uit de omgevingsvariabele JSONSCRAPER_TIKTOK_LICENSE_KEY, zet het geheim niet in de broncode en schrijf het niet naar logbestanden. Dit voorbeeld is bedoeld voor Python 3.8 of hoger en gebruikt het pakket requests:

import os
import requests

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


def search_videos(keyword, cursor=None):
    params = {
        "license_key": API_KEY,
        "keyword": keyword,
        "count": 20,
        "date_posted": "this-week",
        "sort_by": "date-posted",
        "region": "US",
    }
    if cursor is not None:
        params["cursor"] = cursor

    response = requests.get(
        f"{BASE_URL}/searchVideo",
        params=params,
        timeout=30,
    )
    response.raise_for_status()
    payload = response.json()

    if payload.get("status") != "ok":
        raise RuntimeError("De TikTok API gaf een andere status dan ok")

    return payload["tiktok"]


result = search_videos("content planning app")
print("Gevonden objecten:", len(result.get("aweme_list", [])))

Het script controleert op HTTP-fouten en de algemene status van het antwoord. Een geslaagd HTTP-antwoord garandeert op zichzelf niet dat de zoekopdracht video’s oplevert: bij een lege steekproef kan de lijst leeg zijn. Sla bij de eerste uitvoering het volledige antwoord op in beveiligde opslag, zodat je de feitelijke objecten kunt vergelijken met de tabel met genormaliseerde velden.

Verwerk beide structuren van zoekresultaten

De zoekresultaten hebben een belangrijke structurele eigenschap. Video’s kunnen rechtstreeks in tiktok.aweme_list staan, maar ook binnen tiktok.search_item_list[].aweme_info voorkomen. Als de verwerker alleen de eerste lijst uitleest, kan deze resultaten missen die in de tweede structuur staan.

Voeg een kleine normalisatiefunctie toe die beide structuren ondersteunt en items zonder een genest video-object overslaat:

def extract_awemes(tiktok):
    items = list(tiktok.get("aweme_list") or [])

    for item in tiktok.get("search_item_list") or []:
        aweme = item.get("aweme_info")
        if aweme:
            items.append(aweme)

    return items


def normalize(aweme, keyword, collected_at):
    author = aweme.get("author") or {}
    stats = aweme.get("statistics") or {}

    return {
        "collected_at": collected_at,
        "keyword": keyword,
        "video_id": aweme.get("aweme_id"),
        "posted_at": aweme.get("create_time"),
        "description": aweme.get("desc"),
        "share_url": aweme.get("share_url"),
        "author_id": author.get("uid"),
        "author_name": author.get("nickname"),
        "views": stats.get("play_count"),
        "likes": stats.get("digg_count"),
        "comments": stats.get("comment_count"),
        "shares": stats.get("share_count"),
    }

Een ontbrekende waarde blijft None. Vervang deze niet door nul: nul betekent een gemeten waarde, terwijl None vastlegt dat het veld niet is meegestuurd. Dat verschil is van invloed op gemiddelden, verhoudingen en alle conclusies voor het team.

Bewaar de geschiedenis, niet alleen de huidige momentopname

Bewaar afzonderlijke waarnemingen om veranderingen te kunnen zien. De video-ID is geschikt om berichten te ontdubbelen, maar niet om de geschiedenis te verwijderen: als dezelfde video bij de volgende verzameling opnieuw verschijnt, levert dat een nieuw waarnemingspunt op. Je kunt bijvoorbeeld een unieke sleutel voor de waarnemingentabel samenstellen uit video_id en collected_at, en de link en beschrijving in de record opslaan om de gegevens makkelijk te kunnen controleren.

Een minimale SQLite-structuur is handig voor een prototype:

import sqlite3

conn = sqlite3.connect("tiktok_observations.sqlite3")
conn.execute("""
CREATE TABLE IF NOT EXISTS observations (
    video_id TEXT NOT NULL,
    collected_at TEXT NOT NULL,
    keyword TEXT NOT NULL,
    posted_at INTEGER,
    description TEXT,
    share_url TEXT,
    author_id TEXT,
    author_name TEXT,
    views INTEGER,
    likes INTEGER,
    comments INTEGER,
    shares INTEGER,
    PRIMARY KEY (video_id, collected_at, keyword)
)
""")
conn.commit()

Normaliseer de verzameltijd in de praktijk naar UTC, bewaar de oorspronkelijke JSON afzonderlijk en voeg een kolom toe voor de schemaversie. Met het oorspronkelijke antwoord kun je de transformatie opnieuw controleren als de structuur van nieuwe objecten afwijkt van wat je gewend bent. Als een bericht via meerdere zoekopdrachten wordt gevonden, bewaar de overeenkomende zoektermen dan in een aparte gekoppelde tabel of voeg ze samen bij het samenstellen van het rapport.

Paginering: ga alleen verder met de cursor uit het antwoord

De parameter cursor is bedoeld om een zoekopdracht voort te zetten. Neem de waarde over uit het vorige antwoord en geef deze ongewijzigd mee. Stop wanneer has_more niet langer aangeeft dat er meer resultaten zijn of wanneer de ingestelde limiet is bereikt. Beschouw de cursor als ondoorzichtig: bereken hem niet zelf en vervang hem niet door een paginanummer.

def collect_pages(keyword, max_pages=3):
    cursor = None
    collected = []

    for _ in range(max_pages):
        page = search_videos(keyword, cursor)
        collected.extend(extract_awemes(page))

        if not page.get("has_more"):
            break
        cursor = page.get("cursor")
        if cursor is None:
            break

    return collected

Een maximumaantal pagina’s maakt een terugkerende taak voorspelbaar qua aantal verzoeken. Noteer het aantal pagina’s en de waarde van has_more in het uitvoeringslogboek: zo krijgt het rapport context over de steekproef. Ook met paginering beschrijft het resultaat alleen de ontvangen API-antwoorden en de ingestelde verzamelingslimiet; het is geen schatting van alle berichten op het platform.

Stel een herhaalbaar rapport samen

Voer de verzameling wekelijks uit volgens een schema, of vaker als het team frequenter signalen nodig heeft. Leg voor elke uitvoering de lijst met zoekopdrachten, parameters, tijd, het aantal ontvangen objecten en het aantal unieke ID’s vast. Tel daarnaast afzonderlijk de berichten die voor het eerst in deze uitvoering zijn waargenomen en de berichten die eerder al voorkwamen.

Vier eenvoudige weergaven zijn nuttig in het rapport:

• Nieuwe video’s: links, beschrijvingen, publicatiedatum en de zoekterm waarmee de video is gevonden.
• Terugkerende thema’s: groepeer beschrijvingen in handmatig vastgestelde categorieën, bijvoorbeeld ‘instellingsfout’, ‘functieverzoek’ en ‘overzicht van een gebruiksscenario’.
• Openbare reacties: beschikbare weergaven, vind-ik-leuks, reacties en deelacties, weergegeven naast het tijdstip van waarneming.
• Signalen om te controleren: nieuwe formuleringen, veelgestelde vragen of video’s die een medewerker nader moet bekijken.

Noem het verschil tussen twee momentopnamen niet ‘nieuwe likes’ zonder de betekenis en actualiteit van de waarden in het antwoord te controleren. Een correcte formulering is ‘waarde van de statistiek in het laatst ontvangen antwoord’ en ‘verschil tussen de opgeslagen momentopnamen’. Zo kan het team zien wat er precies is berekend en de oorspronkelijke video openen voordat het een beslissing neemt.

Zet AI in voor classificatie, niet als vervanging van de verzameling

Na normalisatie kun je videobeschrijvingen aan een model doorgeven om ze in vooraf vastgestelde categorieën in te delen. Stuur alleen de benodigde tekstvelden mee en vraag om een gestructureerd resultaat: categorie, korte onderbouwing, betrouwbaarheidsniveau en het fragment uit de beschrijving waarop het label is gebaseerd. Bewaar de oorspronkelijke publicatie bij het label, zodat een analist twijfelgevallen kan controleren.

De werkwijze blijft eenvoudig: een planner start de verzameling; Python controleert het antwoord en slaat de JSON op; een afzonderlijke taak normaliseert nieuwe records; een classificatiemodel verwerkt alleen nieuwe beschrijvingen; het rapport wordt uit de database samengesteld en naar een door het team gekozen kanaal gestuurd. De TikTok Scraper API levert zoekgegevens; de classificatie en bezorging van het rapport zijn integratielogica die je in Python, n8n of Make kunt bouwen.

Beperk ruis door vooraf een woordenlijst met categorieën vast te stellen en steekproefsgewijs handmatig gelabelde gegevens te controleren. Voor korte of dubbelzinnige beschrijvingen is de status ‘onvoldoende context’ nuttiger dan een gedwongen categoriekeuze. AI-labels helpen om de beoordelingswachtrij te sorteren, maar conclusies over gebruikersproblemen moeten worden bevestigd door de publicaties te lezen en meerdere waarnemingen met elkaar te vergelijken.

Fouten, herhalingen en veilig omgaan met de sleutel

Een netwerkverzoek kan eindigen met een time-out, tijdelijke fout of een antwoord dat niet als JSON kan worden verwerkt. Splits de verwerking op in stappen: verzoek, HTTP-statuscontrole, JSON-verwerking, controle van de algemene status, normalisatie en opslag. Gebruik bij tijdelijke storingen een beperkt aantal pogingen met een steeds langere pauze. Noteer permanente fouten voor later onderzoek en markeer de uitvoering niet als geslaagd.

Bewaar de sleutel in de geheimenbeheerder van de runtime-omgeving of in een omgevingsvariabele. Omdat de API license_key in de querystring accepteert, moet je voorkomen dat de volledige URL en verzoekparameters in logbestanden terechtkomen: daarin zou het geheim staan. Leg voor foutopsporing de route, antwoordcode, duur, zoekterm en taak-ID vast, maar verwijder de sleutel uit de logs.

Stel het schema en de omvang van de steekproef af op je taak en de gebruiksvoorwaarden van het platform. Beperk het verzamelen van openbare gegevens tot wat werkelijk nodig is voor de analyse; beschrijf in de interne regels van het team hoe beschrijvingen, links en auteurs-ID’s worden opgeslagen. API-antwoorden en statistieken kunnen onvolledig zijn of tussen waarnemingen veranderen, dus het rapport moet de verzameltijd en herkomst van elke rij vastleggen.

Resultaat: van handmatige links naar een controleerbare geschiedenis

Na de inrichting beschikt het team over een regelmatig bijgewerkte lijst met gevonden video’s, oorspronkelijke antwoorden voor audits, een tabel met beschikbare openbare statistieken en een overzicht van terugkerende thema’s. Zo kan het team vragen over een nieuwe functie sneller signaleren, voorbeelden van gebruiksscenario’s vinden en publicaties selecteren voor handmatige analyse. Vergelijking van momentopnamen toont hoe de opgeslagen waarden van eerder gevonden video’s veranderen; het logboek met zoekopdrachten maakt duidelijk hoe de steekproef is samengesteld.

Begin met één zoekopdracht en een klein maximumaantal pagina’s, controleer de feitelijke antwoordstructuur en voeg daarna extra formuleringen en een schema toe. Stel vóór de overgang van prototype naar productie regels op voor ontdubbeling, opslag en foutafhandeling. De actuele routes en parameters staan in de officiële API-documentatie; een beschrijving van de mogelijkheden en de mogelijkheid om te testen vind je op de pagina van de TikTok Scraper API.