Michael JohnsonNa de start van een campagne kan het nuttig zijn om te controleren welke openbare video’s verschijnen in de zoekresultaten voor geselecteerde termen. Handmatig zoeken is lastig te herhalen en een paar dagen later te vergelijken. Een kleine verzamelaar kan volgens een schema dezelfde zoekopdrachten uitvoeren en de antwoorden archiveren met de datum en zoekterm, zodat een analist de records kan controleren en een eigen overzicht kan maken.
Deze handleiding laat zien hoe je met Python een archiveringspijplijn opzet om zoekresultaten voor vaste zoektermen op te slaan. Anders dan bij het monitoren van afzonderlijke hashtags of accounts, draait vergelijken hier om het herhalen van dezelfde zoektermen en het opslaan van een afzonderlijke momentopname van elk antwoord. De pagina TikTok Scraper API van jsonscraper vermeldt het basisadres en de route GET /searchVideo; in de documentatie van deze route wordt de zoekterm doorgegeven via de verplichte parameter keyword.
Doel en meetgrenzen
Stel dat een marketeer dagelijks zoekresultaten wil verzamelen voor enkele vaste termen: een productnaam, een categorie en een omschrijving van een klantprobleem. Voor elke aanvraag bewaart het systeem de verzameltijd en het API-antwoord. Nadat je een voorbeeldantwoord hebt gecontroleerd, kun je velden normaliseren die daadwerkelijk in de JSON voorkomen, zoals een video-ID of openbare tellers, als die aanwezig zijn.
Het archief beantwoordt een concrete vraag: welke records leverde de zoekopdracht voor de opgeslagen term tijdens deze uitvoering op? Als het antwoord statistieken bevat, kunnen herhaalde waarnemingen verschillen laten zien tussen waarden die op verschillende momenten zijn vastgelegd. Zo’n verschil heeft betrekking op de waargenomen momentopnamen en de tijd ertussen; bewaar daarom beide verzameltijden en gebruik steeds hetzelfde veld.
Bewaar de aanvraag samen met het antwoord. De samenstelling van de resultaten hoort bij een specifieke zoekterm en een specifiek verzamelmoment. Het archief is daarom nuttig om de resultaten voor geselecteerde zoekopdrachten te volgen, maar vormt geen volledig overzicht van alle TikTok-content. ID’s, oorspronkelijke antwoorden en tijdstempels helpen te controleren waar elke rij in een latere tabel vandaan komt.
Controleer de route en de parameters
De routekaart van de TikTok API vermeldt het basisadres https://tiktok.evelode.com en GET /searchVideo. De actuele API-specificatie noemt keyword als verplichte zoekparameter; als optionele parameters worden cursor, count, cache_timeout, date_posted, sort_by en region genoemd. Voor authenticatie geef je license_key mee. Informatie over de route staat ook in de documentatie van de Python-SDK.
Met de parameters count en date_posted kun je de omvang van het antwoord en een tijdsfilter instellen; sort_by accepteert de gedocumenteerde waarden most-liked, relevance of date-posted. Gebruik je paginering, geef de cursor uit het vorige antwoord dan als een ondoorzichtige waarde door, zonder die zelf te berekenen. Bewaar voor een vergelijkbaar dagelijks archief de aanvraagparameters en de versie van je eigen code bij de gegevens.
Het voorbeeld hieronder gebruikt een lage waarde voor count tijdens een test en een vaste regio, US. Controleer vóór de dagelijkse verzameling één aanvraag, de HTTP-status en de JSON-structuur. Het antwoordschema kan gevonden video’s bevatten in tiktok.aweme_list of in tiktok.search_item_list, waar het video-object onder aweme_info staat; de code ondersteunt beide aangetroffen vormen.
Bereid het project voor
Maak een virtuele omgeving aan en installeer requests:
python -m venv .venv
source .venv/bin/activate
pip install requestsActiveer de omgeving in PowerShell met de opdracht .venv\Scripts\Activate.ps1. Stel de sleutel en de lijst met zoektermen in via omgevingsvariabelen. Gebruik voor de TikTok API de gedocumenteerde variabelenaam JSONSCRAPER_TIKTOK_LICENSE_KEY:
export JSONSCRAPER_TIKTOK_LICENSE_KEY="uw_sleutel"
export TIKTOK_QUERIES="productnaam,productcategorie,klantprobleem"Momentopnamen verzamelen en opslaan
Het voorbeeld stuurt voor elke term één aanvraag naar de gedocumenteerde route en slaat vervolgens de oorspronkelijke JSON, de verzameltijd en de gebruikte parameters op. De bestandsnaam bevat de datum en zoekterm. De sleutel blijft in de omgeving en wordt niet in het archief opgenomen.
import json
import os
import re
import time
from datetime import datetime, timezone
from pathlib import Path
import requests
BASE_URL = "https://tiktok.evelode.com"
ENDPOINT = "/searchVideo"
LICENSE_KEY = os.environ["JSONSCRAPER_TIKTOK_LICENSE_KEY"]
QUERIES = [
item.strip()
for item in os.environ["TIKTOK_QUERIES"].split(",")
if item.strip()
]
OUT = Path("data")
OUT.mkdir(exist_ok=True)
def safe_name(text):
cleaned = re.sub(r"[^a-zA-Z0-9_-]+", "_", text).strip("_")
return cleaned[:80] or "query"
def fetch(query):
params = {
"license_key": LICENSE_KEY,
"keyword": query,
"count": 10,
"region": "US",
}
response = requests.get(
BASE_URL + ENDPOINT,
params=params,
timeout=60,
)
response.raise_for_status()
payload = response.json()
if payload.get("status") != "ok":
raise RuntimeError("De API retourneerde een andere status dan ok")
return payload
def extract_videos(payload):
tiktok = payload.get("tiktok") or {}
videos = list(tiktok.get("aweme_list") or [])
for item in tiktok.get("search_item_list") or []:
video = item.get("aweme_info") or {}
if video:
videos.append(video)
return videos
for query in QUERIES:
collected_at = datetime.now(timezone.utc).isoformat()
payload = fetch(query)
record = {
"collected_at": collected_at,
"query": query,
"request": {
"endpoint": ENDPOINT,
"keyword": query,
"count": 10,
"region": "US",
},
"videos_found": len(extract_videos(payload)),
"payload": payload,
}
filename = OUT / f"{collected_at[:10]}_{safe_name(query)}.json"
filename.write_text(
json.dumps(record, ensure_ascii=False, indent=2),
encoding="utf-8",
)
print(f"Antwoord voor zoekopdracht opgeslagen: {query}")
time.sleep(1)
print(f"Aantal opgeslagen antwoorden: {len(QUERIES)}")Deze minimale verzamelaar stuurt één aanvraag per term met count=10. Voeg voor een uitgebreidere verzameling paginering met cursor toe: blijf aanvragen doen, geef de cursorwaarde uit het antwoord door zolang de API aangeeft dat er meer resultaten zijn, en leg elk antwoord afzonderlijk vast. De cursor en het aantal resultaten bepalen een specifieke ophaalronde; met de opgeslagen JSON kun je later controleren wat elke aanvraag precies opleverde.
Het voorbeeld controleert de buitenste status en leest vervolgens het object tiktok. Het verzamelt items uit aweme_list en ook uit search_item_list[].aweme_info, als die vorm aanwezig is. Mogelijke velden van een video-item zijn onder meer een ID, beschrijving, auteur, link en statistieken; afzonderlijke velden kunnen ontbreken. Bewaar daarom het volledige antwoord en controleer bij het normaliseren of elk veld aanwezig is.
Het interval van één seconde is een pauze tussen aanvragen van het script zelf, geen bewering over de limieten van de dienst. Stem de frequentie en het aantal nieuwe pogingen af op de toegangsvoorwaarden en documentatie. De parameter cache_timeout is gedocumenteerd voor zoeken; hiermee kun je de cacheduur in seconden instellen. Volgens de specificatie schakelt de waarde 0 caching uit. Voeg deze parameter toe wanneer dat gedrag bij je toepassing past.
Voeg normalisatie toe op basis van het werkelijke antwoord
Open na de eerste uitvoering het opgeslagen bestand en bekijk de structuur van payload. De functie extract_videos in het voorbeeld verzamelt items uit twee antwoordlocaties die voor zoekresultaten zijn gedocumenteerd. Zoek de exacte veldnamen die je voor je analyse nodig hebt. Ontbreekt een veld in een record, bewaar het dan als ontbrekende waarde in plaats van een getal te veronderstellen.
Voor verdere verwerking kun je één rij maken voor elk gevonden object en daar collected_at en query aan toevoegen. Bevestigde velden kun je opslaan in CSV of een database, terwijl je de oorspronkelijke JSON in het archief laat staan. Met deze combinatie kun je overzichtelijke tabellen maken én de herkomst van elk record controleren.
Als de API een video-ID retourneert, gebruik die dan om waarnemingen van dezelfde video uit verschillende uitvoeringen aan elkaar te koppelen. Bewaar elke waarneming afzonderlijk en overschrijf geen eerdere gegevens. Ontbreekt een stabiele ID, controleer dan eerst welke kenmerken je kunt gebruiken om records te koppelen; ga er niet van uit dat overeenkomende beschrijvingstekst een betrouwbare koppeling garandeert.
Vergelijk momentopnamen en maak een rapport
Groepeer de records na normalisatie op een gecontroleerde ID en sorteer ze op verzameltijd. Voor tellervelden kun je het verschil tussen twee opeenvolgende waarden met gewone code berekenen. Een verandering van 12 400 naar 18 900 betekent bijvoorbeeld dat de tellerwaarde tussen deze momentopnamen met 6 500 is veranderd. Vermeld in het rapport de waarnemingsdatums en het oorspronkelijke veld, zodat lezers de berekening kunnen controleren.
Een nuttige eindtabel bevat de zoekterm, de publicatie-ID, de verzameltijd en geselecteerde velden uit het antwoord. Je kunt het overzicht per zoekopdracht groeperen en sorteren op een bevestigde teller. Zo krijgt het team een controleerbare lijst met geretourneerde records om verder te bekijken; maak de tabel of het bericht als afzonderlijke stap nadat je het werkelijke schema hebt onderzocht.
Sla de JSON-bestanden in eerste instantie lokaal op. Wanneer de verzameling regelmatig wordt, kun je de genormaliseerde rijen naar PostgreSQL of een datawarehouse verplaatsen en de oorspronkelijke antwoorden opslaan in objectopslag, met de datum en zoekterm in de naam. Het bewaren van het origineel is vooral handig wanneer je de parser verfijnt: je kunt die opnieuw uitvoeren op historische gegevens zonder de API opnieuw te raadplegen.
Plan de verzameling in
Roep het script voor een dagelijks archief aan via cron of een andere planner die in jouw omgeving beschikbaar is. Een taak kan bijvoorbeeld eenmaal per dag een Python-bestand uitvoeren en de sleutel en zoektermen via omgevingsvariabelen doorgeven. Controleer vóór regelmatig gebruik eerst één aanvraag, daarna de volledige lijst en koppel pas vervolgens de planning.
Registreer voor een betrouwbare uitvoering de status van elke aanvraag, beperk het aantal nieuwe pogingen bij tijdelijke fouten en markeer de verzameling als onvolledig wanneer één term mislukt. Neem de sleutel niet op in foutmeldingen. Het is ook nuttig bestanden per datum en zoekterm te scheiden, zodat een nieuwe uitvoering geen eerdere momentopname overschrijft.
Kies de frequentie op basis van de taak en het aantal aanvragen. Voor een dagelijks overzicht volstaat één uitvoering per dag; vaker verzamelen heeft alleen zin als het team veranderingen binnen de dag wil volgen. Begin met een kleine lijst zoektermen, controleer of de resultaten bruikbaar zijn en breid de verzameling daarna uit binnen de toegangsvoorwaarden en regels voor gegevensgebruik.
Gebruik AI om onderwerpen te groeperen
Zodra het antwoordschema is bevestigd, kun je geselecteerde tekstvelden aan een model doorgeven om beschrijvingen volgens vooraf bepaalde thema’s te groeperen of een beknopt conceptoverzicht te maken. Bewaar bij de classificatie de oorspronkelijke publicatie-ID, zoekterm en tekstpassage waarop de categorie is gebaseerd. Zo kan een analist vanuit de modeluitkomst teruggaan naar het oorspronkelijke record.
Bereken numerieke verschillen, sortering en ontdubbeling met gewone code. Een model is geschikt voor tekstverwerking en het formuleren van een rapport; haal tellers en tijdstempels uit de opgeslagen antwoorden. Door deze bewerkingen te scheiden blijft de herkomst van elke uitkomst duidelijk.
Controleer een deel van de automatische categorieën handmatig en bewaar correcties als testvoorbeelden. Als verschillende soorten publicaties regelmatig in dezelfde groep terechtkomen, verfijn dan de categoriedefinities en controleer opnieuw. Zo kun je de kwaliteit van de classificatie beoordelen aan de hand van gegevens uit je eigen toepassing.
Conclusie: een herhaalbaar archief en een controleerbaar overzicht
Na het uitvoeren van de gedocumenteerde aanvraag met de parameter keyword beschikt het team over een archief: welke zoektermen zijn gebruikt, wanneer dat gebeurde en welke gegevens de API voor elk daarvan retourneerde. Op basis daarvan kun je een resultatentabel maken, bevestigde velden tussen momentopnamen vergelijken en een lijst van gevonden publicaties voorbereiden voor handmatige analyse.
Begin met één testaanvraag en stel daarna de lijst met termen en de planning in. De beschrijving van de TikTok Scraper API bevat het basisadres en de routekaart; de parameters van /searchVideo en de antwoordstructuur staan in de API-specificatie. Door gecontroleerde antwoorden te archiveren, leg je de basis voor herhaalbare analyses met vaste zoektermen.