TikTok: maak van zoekresultaten een wekelijkse lijst met supportonderwerpen

Het supportteam heeft een lijst nodig met openbare TikTok-video’s waarin mensen een onduidelijke functie bespreken of vragen over een product stellen. Handmatig zoeken is lastig steeds op dezelfde manier te herhalen, en zoekresultaten van de API kunnen video’s op verschillende plekken in de JSON opslaan. Hieronder staat een minimaal Python-script dat resultaten opvraagt met zoekwoorden, beide structuren samenvoegt, duplicaten op basis van ID verwijdert en de gevonden items als CSV opslaat.

Wat het script oplevert

Het resultaat is een tabel met de video-ID, link, beschrijving, publicatietijd, auteur en beschikbare aantallen reacties. Support of marketing kan handmatig aangeven welke onderwerpen een antwoord, bijgewerkte instructie of controle in het eigen CRM vereisen. De tabel bevat uitsluitend de resultaten die de API voor de opgegeven zoekopdrachten heeft teruggegeven; beschouw deze als een werkselectie om te beoordelen, niet als een volledige catalogus van alle gesprekken.

Het script verzamelt en sorteert de resultaten op hoofdlijnen. Het bepaalt niet automatisch of een beschrijving een vraag, klacht of grap betreft: zo’n label voeg je het best na handmatige controle toe, of met een afzonderlijke classifier, waarbij je de oorspronkelijke tekst en de reden voor de beslissing vastlegt.

Wat je opvraagt en hoe het antwoord is opgebouwd

Voor het zoeken naar video’s documenteert jsonscraper de GET-route /searchVideo op de host https://tiktok.evelode.com. De verplichte parameter is keyword; je kunt ook count, een regio, sortering, publicatieperiode en een cursor voor de volgende pagina meegeven. Je kunt bijvoorbeeld herhaaldelijk zoeken met verschillende vooraf vastgelegde woordgroepen: de naam van een functie, een veelgebruikte formulering van een fout en een korte vraag over instellingen. De parameters en toegestane waarden staan in de TikTok API-handleiding.

De zoekfunctie heeft een belangrijk kenmerk waarmee de parser rekening moet houden: de array aweme_list kan leeg zijn, terwijl de gevonden objecten in search_item_list staan, elk met een aweme_info-object. Daarom controleert de onderstaande verwerking beide vormen. Een voorbeeldantwoord en velden die zijn waargenomen bij een controle op 25 oktober 2026 staan in de oorspronkelijke specificatie van jsonscraper; statistiekvelden kunnen ontbreken, dus de code vult geen waarden in die niet zijn teruggegeven.

Stel je sleutel en zoekopdrachten in

Sla de sleutel op in de omgevingsvariabele JSONSCRAPER_TIKTOK_LICENSE_KEY, niet in het bronbestand. In de shell van Linux of macOS kan dat als volgt:

export JSONSCRAPER_TIKTOK_LICENSE_KEY="uw_sleutel"

Installeer de requests-bibliotheek en maak een bestand queries.txt met één zoekterm per regel, bijvoorbeeld productnaam instellingen en functienaam werkt niet. Kies de formuleringen op basis van de taal van je publiek en beheer ze in een aparte lijst, zodat wekelijkse exports steeds dezelfde zoekopdrachten vergelijken.

python -m pip install requests

Verzamel en normaliseer de gevonden video’s

Het voorbeeld is compatibel met Python 3.8+. Het doet één aanvraag per zoekterm, met een limiet voor het aantal resultaten, controleert op HTTP-fouten en de status in het antwoord en slaat vervolgens alleen velden op die daadwerkelijk aanwezig zijn. Dubbele resultaten worden samengevoegd op basis van aweme_id, en alle zoekopdrachten waarmee een video is gevonden, worden opgeslagen in het veld keywords. Het aparte veld collected_at_utc legt het tijdstip van ophalen vast, zodat je volgende uitvoeringen kunt vergelijken.

import csv
import os
import sys
from datetime import datetime, timezone

import requests

BASE_URL = "https://tiktok.evelode.com/searchVideo"
API_KEY = os.environ.get("JSONSCRAPER_TIKTOK_LICENSE_KEY")

if not API_KEY:
    raise SystemExit("Stel JSONSCRAPER_TIKTOK_LICENSE_KEY in")


def get_items(tiktok):
    """Haalt video’s op uit beide gedocumenteerde vormen van het zoekantwoord."""
    items = list(tiktok.get("aweme_list") or [])
    for entry in tiktok.get("search_item_list") or []:
        info = entry.get("aweme_info") if isinstance(entry, dict) else None
        if info:
            items.append(info)
    return items


with open("queries.txt", encoding="utf-8") as query_file:
    queries = [line.strip() for line in query_file if line.strip()]

collected_at = datetime.now(timezone.utc).isoformat()
videos = {}

for keyword in queries:
    response = requests.get(
        BASE_URL,
        params={
            "license_key": API_KEY,
            "keyword": keyword,
            "count": 30,
            "region": "US",
            "sort_by": "relevance",
        },
        timeout=30,
    )
    response.raise_for_status()
    payload = response.json()

    if payload.get("status") != "ok":
        print("API-status niet succesvol voor zoekopdracht:", keyword, file=sys.stderr)
        continue

    tiktok = payload.get("tiktok") or {}
    for item in get_items(tiktok):
        video_id = item.get("aweme_id")
        if not video_id:
            continue

        if video_id not in videos:
            author = item.get("author") or {}
            stats = item.get("statistics") or {}
            videos[video_id] = {
                "aweme_id": video_id,
                "keywords": [keyword],
                "description": item.get("desc"),
                "share_url": item.get("share_url"),
                "create_time": item.get("create_time"),
                "author": author.get("unique_id") or author.get("nickname"),
                "play_count": stats.get("play_count"),
                "digg_count": stats.get("digg_count"),
                "comment_count": stats.get("comment_count"),
                "share_count": stats.get("share_count"),
                "collected_at_utc": collected_at,
            }
        elif keyword not in videos[video_id]["keywords"]:
            videos[video_id]["keywords"].append(keyword)

columns = [
    "aweme_id", "keywords", "description", "share_url", "create_time",
    "author", "play_count", "digg_count", "comment_count", "share_count",
    "collected_at_utc",
]
with open("tiktok_support_review.csv", "w", newline="", encoding="utf-8-sig") as output:
    writer = csv.DictWriter(output, fieldnames=columns)
    writer.writeheader()
    for video in videos.values():
        row = dict(video)
        row["keywords"] = " | ".join(row["keywords"])
        writer.writerow(row)

print("Aantal unieke gevonden video’s opgeslagen:", len(videos))

De aanvraag wordt verstuurd met de parameter params, zodat de bibliotheek de zoektermen correct codeert in de URL. De sleutel staat daarbij in een queryparameter, zoals beschreven in de documentatie; druk de volledige aanvraag-URL niet af in het toepassingslogboek. Sla voor diagnostiek de HTTP-statuscode, de zoekterm en de starttijd op, maar laat geheimen en persoonsgegevens die niet nodig zijn voor de taak weg.

De CSV lezen zonder verkeerde conclusies te trekken

De kolom keywords bevat alle zoektermen waarmee een video is gevonden; met collected_at_utc kun je de publicatietijd onderscheiden van het verzameltijdstip. De ID is handig om duplicaten te verwijderen en via de link kan iemand de video controleren. Een lege teller betekent dat het veld in het betreffende antwoord ontbrak, niet dat de waarde nul was.

Voeg voor een eerste sortering in een werkkopie van de CSV de kolommen onderwerp, signaaltype, antwoord nodig en link naar intern materiaal toe. Kies onderwerpen die aansluiten op je product, bijvoorbeeld installatie, betaling, compatibiliteit of probleemoplossing. Zo wordt de export een beoordelingswachtrij en blijft de oorspronkelijke video beschikbaar om de beslissing te controleren.

Plan de verzameling in

Voer het script eerst handmatig uit en controleer enkele rijen en links. Voeg het daarna toe aan cron, een CI-taak of een automatiseringsscenario dat een Python-proces kan starten. Bewaar voor periodieke rapporten elke export afzonderlijk, of voeg regels toe aan een gegevensopslag met een unieke videosleutel en de datum van de momentopname. Zo kan het team nieuwe gevonden publicaties onderscheiden van herhaalde waarnemingen en volgen hoe beschikbare tellers tussen uitvoeringen veranderen.

De parameter cursor is bedoeld om door de resultaten te bladeren; je moet de waarde ervan overnemen uit het antwoord van de vorige aanvraag. Paginering is bewust niet opgenomen in dit minimale voorbeeld: een beperkte reeks zoekopdrachten is eenvoudiger te controleren en te reproduceren. Als je pagina’s toevoegt, behandel de cursor dan als ondoorzichtige waarde, stop op basis van de indicator dat er geen vervolg is en stel een maximumaantal aanvragen per uitvoering in. De API-aanvraag geeft een selectie terug; interpreteer het aantal regels niet als volledige dekking van TikTok.

Praktische grenzen van het gebruik

Zoekresultaten zijn geschikt om video’s te ontdekken op basis van formuleringen die het team al kent. Ze helpen materiaal te verzamelen voor classificatie, maar vervangen geen inkomende klantvragen, analyses van de eigen website of controle van de videocontext. De beschrijving bevat mogelijk niet de kern van de video, en beschikbare statistieken geven de gegevens weer zoals die op het moment van ophalen waren. Houd onderwerpen en conclusies apart van de oorspronkelijke velden, zodat medewerkers de classificatie opnieuw kunnen beoordelen.

Bepaal voordat je met regelmatige monitoring begint wie toegang heeft tot de export, hoe lang gegevens worden bewaard en voor welk doel openbare gegevens worden gebruikt. Bewaar alleen velden die nodig zijn om productonderwerpen te beoordelen en geef de voorkeur aan links naar oorspronkelijke publicaties boven het kopiëren van mediabestanden. Raadpleeg voor aanvragen en controle van beschikbare integratiemogelijkheden de pagina van de TikTok Scraper API en de documentatie van de zoekroute.