Overvåking av TikTok-hashtagger med Python: et fungerende API-kall

Markedsføringsteamet legger merke til at det dukker opp videoer om et nytt produkt på TikTok, men det er krevende å sjekke flere hashtagger manuelt hver dag. For å sammenligne innlegg og synlige måltall over tid trenger de en repeterbar innsamling med tidsstempel, et arkiv med de opprinnelige svarene og kontroll av endringer.

Til en slik prototype passer TikTok Scraper API fra jsonscraper: produktsiden lister opp endepunkter for hashtagger, brukere, videoer og søk. Først bør du teste riktig endepunkt og svarformat i Postman, og deretter overføre den bekreftede konfigurasjonen til Python. Slik kan du bygge en repeterbar prosess som bare henter ut feltene som faktisk finnes i svaret.

Oppgaven: se utviklingen, ikke bare én populær video

Ett innlegg med mange visninger kan vekke oppmerksomhet, men når en kampanje skal planlegges, er det mer nyttig å forstå hvor mange nye videoer som oppdages om et tema, og hvordan de offentlige måltallene for allerede funne innlegg endrer seg. En nettbutikk for sportsutstyr kan for eksempel ha behov for å anslå strømmen av videoer om en bestemt type trening før den lager tilhørende kreativt materiell.

Manuell kontroll gjør sammenligning vanskelig: resultatene endrer seg, måltallene øker, og medarbeidere kan registrere dem i ulike formater. Hvis hvert kjøretøy lagres som et øyeblikksbilde sammen med innsamlingstidspunktet og den opprinnelige JSON-filen, får teamet en historikk over egne observasjoner og kan behandle dataene på nytt dersom analyseskjemaet endres.

Automatiseringen består av flere trinn: test endepunkt og parametere, hent data etter en tidsplan, lagre svaret, bekreft strukturen og hent deretter ut de ønskede feltene. Tabellen kan brukes til diagrammer, temaklassifisering eller rapportering.

Hva API-dokumentasjonen bekrefter

På siden for TikTok Scraper API er basisadressen https://tiktok.evelode.com oppgitt, sammen med Hashtag-endepunktene GET /getHashtagInfo, GET /getHashtagFeed og GET /getHashtagFeedByID. Siden viser også et eksempel på en forespørsel til et annet endepunkt med parameteren license_key, og beskriver hvordan nøkkelen konfigureres i en Postman-samling.

For GET /getHashtagFeed oppgir den offisielle spesifikasjonen for endepunkter den obligatoriske parameteren query (URL-en til en hashtag eller navnet på en tagg), samt de valgfrie parameterne cursor, count, region og cache_timeout. Strømresponsen forventes å inneholde en matrise under tiktok.aweme_list. Blant feltene som er oppført for elementene, er aweme_id, desc, create_time, share_url, forfatterdata og statistics. Enkelte felt kan mangle, så kontroller den faktiske JSON-en før du behandler den.

I jsonscraper-samlingen i Postman kan du enkelt sende en testforespørsel, kontrollere det faktiske svaret og hente et testeksempel til senere kontroll av koden. Autentisering sendes med license_key. Oppbevar nøkkelen i en miljøvariabel, og ikke skriv den ut i logger.

Test forespørselen i Postman først

Begynn med én testhashtag. Velg endepunktet for hashtag-strømmen i samlingen, angi license_key slik dokumentasjonen beskriver, og send taggnavnet i query. Legg til count og en landskode i region ved behov. Send forespørselen og kontroller HTTP-statusen, toppnivåfeltet status og innholdet i tiktok.aweme_list.

Lagre et vellykket svar som en testfil i JSON-format. Bruk den til å kontrollere at identifikatoren for innlegget, beskrivelsen, publiseringstidspunktet, lenken og statistikken er til stede. Ta bare med et felt i analyses skjema etter at du har bekreftet at det returneres i riktig datatype.

Oppbevar API-nøkkelen i en miljøvariabel, ikke i kildefilen. Hvis nøkkelen sendes i URL-en, må du maskere den når forespørselen logges, slik at hele adressen ikke havner i loggene.

Python-klient for forespørsler og arkivering

Endepunktet og parameternavnene nedenfor samsvarer med den publiserte spesifikasjonen: query brukes for hashtaggen, og autentisering sendes via license_key. Eksemplet fungerer med Python 3.8+ og lagrer det opprinnelige svaret sammen med metadata om kjøringen.

import json
import os
from datetime import datetime, timezone
from pathlib import Path

import requests

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


def fetch_hashtag_feed(hashtag: str) -> dict:
    params = {
        "license_key": API_KEY,
        "query": hashtag,
        "count": 20,
    }
    response = requests.get(
        f"{BASE_URL}/getHashtagFeed",
        params=params,
        timeout=45,
    )
    response.raise_for_status()
    payload = response.json()
    if payload.get("status") != "ok":
        raise RuntimeError("API-et returnerte en annen status enn ok")
    return payload


def archive_response(hashtag: str, payload: dict) -> Path:
    collected_at = datetime.now(timezone.utc).isoformat()
    safe_tag = hashtag.lstrip("#").replace("/", "_")
    output_dir = Path("data/raw") / safe_tag
    output_dir.mkdir(parents=True, exist_ok=True)

    filename = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ.json")
    file_path = output_dir / filename
    file_path.write_text(
        json.dumps(
            {
                "hashtag": hashtag,
                "collected_at": collected_at,
                "response": payload,
            },
            ensure_ascii=False,
            indent=2,
        ),
        encoding="utf-8",
    )
    return file_path


if __name__ == "__main__":
    tag = "#eksempeltama"
    payload = fetch_hashtag_feed(tag)
    saved_path = archive_response(tag, payload)
    print(f"Arkivet er lagret: {saved_path}")

Angi miljøvariabelen JSONSCRAPER_TIKTOK_LICENSE_KEY før du kjører programmet. Forespørselen bruker den bekreftede parameteren query og begrenser antallet forespurte elementer med count. Svaret kontrolleres både for HTTP-status og JSON-status, og arkivet lagrer de faktiske dataene for senere behandling. Test kjøringen med én hashtag før du legger til tidsplan og analyse.

Slik legger du til normalisering uten skjøre antakelser

Dokumentasjonen oppgir at strømresponsen inneholder en matrise under tiktok.aweme_list. Før du konverterer dataene, må du kontrollere at tiktok er et objekt, og at aweme_list er en liste. Hent bare ut bekreftede felt fra hvert element, for eksempel aweme_id, desc, create_time, share_url og verdier fra statistics, når de finnes.

En intern tabell kan inneholde hashtaggen i forespørselen, innsamlingstidspunktet, video-ID-en og utvalgte måltall. For et valgfritt eller manglende måltall lagrer du en tom verdi: et manglende måltall er ikke det samme som en målt null. Oppbevar de opprinnelige svarene separat, slik at du kan bygge tabellen på nytt uten å sende en ny forespørsel.

Hvis svarformatet endres, bør typekontrollen stoppe feilaktig behandling og opprette en diagnostisk melding. Oppbevar en testfil i JSON-format sammen med parser-testen: den gjør det mulig å kontrollere at en ny kodeversjon fortsatt behandler det kjente skjemaet.

Måltall basert på gjentatte observasjoner

Hvis svaret inneholder tellere, lagrer du hver observasjon med et tidsstempel. For ett innlegg sammenligner du verdiene fra to kjøringer og beregner den observerte endringen i tidsrommet. Bruk aweme_id, som er oppført i spesifikasjonen, til sammenligning, og kontroller at den finnes i hvert element.

Antallet innlegg som oppdages for første gang i løpet av en dag, kan beregnes ut fra resultatene av kjøringene dine. Dette måltallet beskriver strømmen som returneres av bestemte forespørsler med angitte parametere og en bestemt tidsplan. Det gjør det mulig å sammenligne egne øyeblikksbilder når innsamlingsmetoden er konsekvent.

En enkel rapport kan vise antallet nye oppdagede innlegg per dag, fordelingen av tilgjengelige tellere og endringer i verdier for videoer som er funnet på nytt. Legg til forespørselstidspunktet og navnet på kildefilen, slik at analytikeren kan kontrollere opphavet til hver post.

Tidsplan og feilhåndtering

Når forespørselen og parseren er testet, kan du kjøre skriptet etter en tidsplan, for eksempel med cron, GitHub Actions eller en dataorkestrator. Legg listen over hashtagger i en separat konfigurasjon, slik at du kan legge til og fjerne emner uten å endre klientlogikken.

Ved automatiserte kjøringer angir du en tidsavbruddsgrense, et begrenset antall nye forsøk ved midlertidige nettverksfeil og logging av HTTP-status og forespørselens varighet. Ikke skriv nøkkelen til loggen. Ved parserfeil lagrer du trygge diagnostiske opplysninger og varsler den ansvarlige medarbeideren.

Spesifikasjonen støtter paginering med parameteren cursor for hashtag-strømmen. Hvis du trenger paginering, lagrer du markøren fra svaret og sender den videre i neste forespørsel uten å endre den. Behandle bare resultatene som returneres, og følg med på has_more hvis feltet finnes. Hvis forespørsler for flere hashtagger returnerer det samme innlegget, velger du en dedupliseringsnøkkel ut fra oppgaven: enten skal innlegget telles separat for hver hashtag, eller så skal bare unike videoer telles.

Klassifisering og automatisering av rapporter

Etter at du har hentet verifiserte rader, kan du klassifisere videobeskrivelser etter definerte temaer: feltet desc er oppført i elementskjemaet. En modell kan gruppere innlegg etter format, for eksempel veiledninger, anmeldelser eller brukererfaringer. Lagre originalteksten, etiketten, instruksjonsversjonen og resultatet, og send usikre tilfeller til menneskelig vurdering.

Beregn numeriske måltall med vanlig kode, slik at gjentatte kjøringer gir etterprøvbare beregninger. En klassifikator er nyttig for tekstbehandling, men sluttrapporten bør knytte konklusjonene til bestemte rader og observasjonsdatoer.

I et no-code-oppsett kan de samme trinnene kobles sammen i et automatiseringsverktøy: tidsplan, HTTP-forespørsel med den testede konfigurasjonen, svarvalidering, lagring av JSON, behandling av bekreftede felt og feilmelding. Test først kontrakten i Postman, og flytt den deretter over til Python, n8n eller Make.

Forventet resultat og neste steg

Når oppsettet er klart, har teamet et arkiv med API-svar og en observasjonstabell for de valgte hashtagene. Disse gjør det mulig å finne nye innlegg, sammenligne tilgjengelige måltall over tid og velge ut materiale for grundigere analyse. For sammenlignbare resultater bør du holde tidsplan, forespørselsparametere og normaliseringsregler ensartede.

Begynn med ett endepunkt og ett faktisk svar: send en forespørsel til /getHashtagFeed med parameteren query, lagre JSON-filen, og legg deretter til feltbehandling og tidsplan. Siden for TikTok Scraper API viser basisadressen og oversikten over endepunkter, mens spesifikasjonen for endepunkter inneholder parameternavnene som trengs for å implementere klienten.