TikTok-sisällöntuottajien aiheiden analysointi: käytännön Python-työnkulku

Kun tiimi etsii aihetta seuraavaan kampanjaansa, kymmenien profiilien manuaalinen läpikäynti muuttuu nopeasti sekalaisiksi muistiinpanoiksi ilman yhteistä menetelmää. Yksi analyytikko kirjaa katselukerrat, toinen videotekstit, ja samankaltaisilla sanamuodoilla julkaistut videot päätyvät eri taulukoihin. Viikon kuluttua on vaikea sanoa, mikä toistuu useimmin: aihe, esitystapa vai vain onnistunut video.

Käytännöllinen tapa on ylläpitää pientä listaa julkisista tileistä, hakea säännöllisesti tiedot niiden videoista rakenteisessa muodossa ja tallentaa jokainen keräys erilliseksi tilannekuvaksi. Sen jälkeen julkaisuja ja saatavilla olevia mittareita voi vertailla ajan mittaan, ja kielimallia voi käyttää kuvatekstien alustavaan ryhmittelyyn. Alla esitellään tällaisen tutkimustyönkulun rakenne Pythonilla ja jsonscraperin TikTok Scraper API:lla.

Määritä kysymys ennen tietojen keräämistä

Kuvitellaan pienen urheiluravinnebrändin markkinointitiimi. Sen on selvitettävä, mitkä aiheet toistuvat valituilla julkisilla TikTok-sisällöntuottajilla ja mitkä videot kannattaa katsoa manuaalisesti. Tavoitteena on verrata ennalta valittujen tilien julkaisuja tarkastelujakson aikana, ei rakentaa yleispätevää TikTokin suosioluokitusta.

Tämä rajaa analyysin. Valittujen profiilien syötteen kerääminen auttaa tutkimaan näiden tilien sisältöä ja julkaisutiheyttä. Saatavilla olevat julkiset laskurit voi tallentaa kyselyhetkellä. Oman mainonnan tulosten arviointiin tarvitaan erillisiä tietoja, kuten mainosjärjestelmän tai verkkoanalytiikan kustannus- ja konversiotietoja.

Kirjaa tutkimusprotokolla ennen API:n käyttöönottoa: tililista, aloituspäivä, keräystiheys, analysoitavat kentät ja julkaisujen sisällyttämiskriteerit. Tallenna jokaisen kyselyn ajankohta. Näin voit erottaa yksittäisen videon mittarin muutoksen kahden havaintoaineiston välisestä erosta.

Mitä kerätä ja mitä laskea

Pienessä projektissa tarvitaan kolme tietokerrosta. Ensimmäinen sisältää tilin tunnisteen ja keräyksen käynnistysajan. Toinen on alkuperäinen API-vastaus, joka tallennetaan myöhempää tarkistusta varten. Kolmas koostuu kyselyitä ja raportteja varten normalisoiduista kentistä: videon ID, kuvateksti, julkaisuaika ja saatavilla olevat vuorovaikutuslaskurit.

Kenttien nimet ja vastauksen sisäinen rakenne on selvitettävä kyseisen reitin esimerkin perusteella. Älä oleta etukäteen, että lista on aina nimeltään videos tai katselukertojen laskuri views. Tee ensin dokumentoitu kysely ja tarkastele sen todellista JSON-vastausta. Määritä vasta sitten muunnos omaan skeemaasi.

Hyödyllisiä mittareita ovat uusien julkaisujen määrä aikavälillä, julkaisujen jakautuminen aiheisiin ja saman videon julkisten laskurien muutos tilannekuvien välillä. Vertaa viimeksi mainittua varten tietueita, joilla on sama videon ID. Näin jo julkaistun videon kehitys pysyy erillään uusien julkaisujen mittareista.

TikTok Scraper API:n käyttöönotto

TikTok Scraper API:n kuvauksessa ilmoitetaan perusosoitteeksi https://tiktok.evelode.com, ja reittien viiteopas vahvistaa reitin GET /getUserFeed sekä parametrit query, max_cursor, count, region, with_pinned_posts, sort_type ja cache_timeout. Ensimmäiseen kyselyyn riittää profiilin lisääminen query-parametriin ja esimerkiksi tulosten määrän asettaminen count-parametrilla. Avain välitetään kyselymerkkijonossa license_key-parametrina; myös sen määritys kuvataan API:n viiteoppaassa. Postman-kokoelmassa voit tarkistaa endpointin ja testata vastauksen ennen integrointia.

Säilytä avain ympäristömuuttujassa. Älä lisää sitä lähdekoodiin, repositorioon, taulukkoon tai asiakassovellukseen. Tee kysely, tallenna onnistunut JSON-esimerkki päivämäärän ja reitin nimen kanssa ja käytä sitä normalisointisovittimen sekä testien pohjana.

Yksinkertainen Python-kysely

Viiteoppaan mukaan käyttäjäsyötteen vastaus sisältää ulomman tilatiedon ja tiktok-objektin, jonka aweme_list-kentässä julkaisulista sijaitsee. Tietueissa voi olla ID, kuvateksti, julkaisuaika, tekijä ja tilastotietoja. Tarkista yksittäiset kentät ja arvot saadusta vastauksesta, sillä osa tiedoista voi puuttua.

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

import requests

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


def fetch_user_feed(handle: str, count: int = 20) -> dict:
    response = requests.get(
        ENDPOINT_URL,
        params={
            "license_key": API_KEY,
            "query": handle,
            "count": count,
            "region": "US",
        },
        timeout=45,
    )
    response.raise_for_status()
    payload = response.json()
    if not isinstance(payload, dict):
        raise ValueError("Odotettiin JSON-objektia")
    if payload.get("status") != "ok":
        raise RuntimeError(f"API palautti tilan: {payload.get('status')!r}")
    tiktok = payload.get("tiktok")
    if not isinstance(tiktok, dict):
        raise ValueError("Vastauksesta puuttuu tiktok-objekti")
    return payload


def save_raw(payload: dict, account: str, output_dir: str = "data/raw") -> Path:
    collected_at = datetime.now(timezone.utc).isoformat()
    safe_account = "".join(c for c in account if c.isalnum() or c in "-_@")
    path = Path(output_dir) / f"{safe_account}_{collected_at.replace(':', '-')}.json"
    path.parent.mkdir(parents=True, exist_ok=True)
    path.write_text(
        json.dumps(
            {"collected_at": collected_at, "account": account, "payload": payload},
            ensure_ascii=False,
            indent=2,
        ),
        encoding="utf-8",
    )
    return path


def normalize_items(payload: dict, account: str, collected_at: str) -> list:
    items = payload["tiktok"].get("aweme_list", [])
    if not isinstance(items, list):
        raise ValueError("Kenttä tiktok.aweme_list ei ole lista")

    observations = []
    for item in items:
        if not isinstance(item, dict):
            continue
        stats = item.get("statistics")
        stats = stats if isinstance(stats, dict) else {}
        author = item.get("author")
        author = author if isinstance(author, dict) else {}
        observations.append({
            "account_handle": account,
            "collected_at": collected_at,
            "video_id": item.get("aweme_id"),
            "caption": item.get("desc"),
            "published_at_epoch": item.get("create_time"),
            "author_handle": author.get("unique_id"),
            "views": stats.get("play_count"),
            "likes": stats.get("digg_count"),
            "comments": stats.get("comment_count"),
            "shares": stats.get("share_count"),
        })
    return observations


if __name__ == "__main__":
    account = "creator_handle"
    payload = fetch_user_feed(account, count=20)
    collected_at = datetime.now(timezone.utc).isoformat()
    raw_path = save_raw(payload, account)
    observations = normalize_items(payload, account, collected_at)
    print(f"Tallennettu: {raw_path}; tietueita: {len(observations)}")

Aseta ennen ajoa ympäristöön JSONSCRAPER_TIKTOK_LICENSE_KEY ja asenna requests-kirjasto. Koodi tarkistaa HTTP-vastauksen, ulomman tilatiedon ja tiktok-objektin olemassaolon, minkä jälkeen se lukee aweme_list-kentän. Se tallentaa raakamuotoisen JSONin ja poimii viiteoppaan vahvistamat kentät jättäen puuttuvat arvot tyhjiksi. Haettu syöte on API:n palauttama tulosjoukko, joten raportissa tulee ilmoittaa kyselyn ajankohta ja valittu profiili.

Tallenna tilannekuvat ja vertaile julkaisuja

Pieneen projektiin sopivat SQLite tai PostgreSQL. Säilytä raaka vastaus erillään normalisoiduista tietueista. Havaintotaulukon skeema voi olla esimerkiksi tällainen:

CREATE TABLE IF NOT EXISTS video_observations (
    account_handle TEXT NOT NULL,
    video_id TEXT NOT NULL,
    collected_at TEXT NOT NULL,
    published_at_epoch INTEGER,
    caption TEXT,
    views INTEGER,
    likes INTEGER,
    comments INTEGER,
    shares INTEGER,
    raw_file TEXT,
    PRIMARY KEY (account_handle, video_id, collected_at)
);

Jokainen suoritus lisää uuden tilannekuvan sen sijaan, että korvaisi aiemman. Laske laskurien erotus vain, kun saman videon molemmat arvot ovat olemassa. Sisällytä raporttiin kyselyiden välinen aika ja havaintoajankohta: ne kertovat, miltä ajalta muutos on kertynyt.

Aloita temaattinen ryhmittely pienellä luokittelusanastolla ja lisää tarvittaessa luokitin tai kielimalli. Anna mallille puhdistetut kuvatekstit, julkaisujen ID:t ja ennalta määritetyt kategoriat. Rakenteista tulosta, jossa on kategoria ja lyhyt perustelu, on helpompi vertailla suoritusten välillä kuin vapaamuotoista yhteenvetoa.

Lisää kielimalli ja varmennettava luokittelu

Malli voi luokitella kuvatekstejä alustavasti esimerkiksi aiheisiin ”reseptit”, ”harjoittelu”, ”tuotearvostelut” ja ”henkilökohtaiset tarinat”. Merkitse ensin muutama kymmenen julkaisua käsin. Vertaa automaattisia luokituksia näihin esimerkkeihin, tarkenna kategorioiden määritelmiä ja arvioi tulos uudelleen promptin tai mallin muutosten jälkeen.

Uusien julkaisujen määrä, laskurien mediaani ja tilannekuvien välinen erotus kannattaa laskea luotettavasti tavallisella koodilla. Käytä mallia tekstin luokitteluun ja lyhyiden selitysten laatimiseen. Säilytä alkuperäiset kuvatekstit ja numeeriset havainnot tarkistettavina.

Tallenna luokituksen kanssa julkaisun ID, promptin versio, käsittelypäivä ja käytetty malli. Virheellisen luokituksen tapauksessa analyytikko voi löytää kuvatekstin ja korjata sääntöä. Alkuperäinen luokitus ja manuaalinen korjaus kannattaa säilyttää erillisinä.

Automatisoi suoritus

Kun manuaalinen koeajo on tarkistettu, siirrä skripti croniin, GitHub Actionsiin, n8n:ään tai Makeen. Ajastin käynnistää keräyksen aikataulun mukaan, välittää tililistan, kirjaa tuloksen ja ohjaa raportin valittuun tallennuspaikkaan. Säilytä avain suoritusympäristön salaisuuksissa. Testaa ensin yhdellä tilillä ja laajenna listaa vasta sen jälkeen.

Jaa automaatio vaiheisiin: tilijono, API-kutsu, raakavastauksen tallennus, normalisointi, tilannekuvan tallennus ja raportin valmistelu. Yhden tilin virhe ei saa hävittää muiden tuloksia. Uudelleenajosta voi tehdä idempotentin käyttämällä suoritus-ID:tä ja tietokannan yksilöllisyysrajoitteita.

Kirjaa lokiin aika, tili, reitti, HTTP-tila, kesto, käsiteltyjen tietueiden määrä ja virheen kuvaus. Älä kirjoita API-avainta lokiin. Parametri cache_timeout on ilmoitettu reitille /getUserFeed; lisää se kyselyyn, jos tarvitset määritellyn välimuistiajan. API:n viiteoppaan mukaan oletusarvo on 3600 sekuntia.

Tarkista laatu ennen raportin julkaisemista

Vertaa muutamaa normalisoitua tietuetta alkuperäiseen JSONiin. Tarkista, että toistuva keräys tunnistaa saman videon ID:n perusteella, päivämäärät tulkitaan odotetusti, numeeriset kentät ovat oikean tyyppisiä ja puuttuvien arvojen osuus tunnetaan. Tee sitten uusi ajo ja varmista, että tietokanta säilytti vanhat havainnot ja lisäsi uudet.

Älä sekoita tilejä tai keräysjaksoja. Käytä aiheiden vertailussa samanpituisia jaksoja tai ilmoita niiden pituus selvästi raportissa. Laskurien kehitystä tarkastellessa kirjaa tilannekuvien välinen aika, jotta lukija ymmärtää vertailtavien jaksojen mittakaavan.

Säilytä alkuperäinen kuvateksti ja luo puhdistettu versio erikseen. Emojit, hashtagit, linkit ja kielelliset erityispiirteet voivat vaikuttaa luokitteluun; erillisten kenttien avulla voit tarkistaa siivouksen vaikutuksen ja laskea kategoriat uudelleen ilman uutta API-kyselyä.

Millaiseen tulokseen työnkululla päästään

Muutaman keräyskierroksen jälkeen tiimillä on taulukko julkaisuista ja tilannekuvista, kuvatekstien alustava aihejaottelu sekä raportti uusista videoista valitulla aikavälillä. Tämä auttaa valitsemaan videoita asiantuntijan tarkasteltavaksi, havaitsemaan toistuvia aiheita valituilla tileillä ja tarkistamaan julkisten laskurien muutokset havaintopäivien välillä.

Tietojen pohjalta voi laatia hypoteeseja toimituskalenteriin: vertailla eri tapoja käsitellä samaa kysymystä tai nostaa esiin aiheita oman sisällön testaamista varten. Kaupallisen vaikutuksen arvioinnissa havainnot tulee yhdistää kampanjoiden sisäisiin tietoihin.

Aloita valitsemalla pieni lista julkisia tilejä ja testaa GET /getUserFeed Postman-pyyntökokoelmassa. Siirrä koodiin vain parametrit ja kenttäpolut, jotka reitin dokumentaatio ja sen todellinen vastaus vahvistavat.

Julkisten tietojen vastuullinen kerääminen

Rajaa tililista tutkimuksen tavoitteeseen, kerää vain tarvittavat kentät ja määritä raakavastauksille säilytysaika. Ennen tietojen kaupallista käyttöä tarkista sovellettavat alustan ehdot ja henkilötietovaatimukset omalla lainkäyttöalueellasi. Käyttöoikeuksien hallinta ja vanhentuneiden tilannekuvien poistaminen auttavat pitämään prosessin tehtävän rajoissa.

Poista tiedoista ennen niiden lähettämistä tekoälypalveluun kentät, joita malli ei tarvitse. Ilmoita raportissa julkaisun ID ja havaintopäivä, jotta työntekijä voi siirtyä tietueeseen ja tarkistaa päätelmän perustan.

Käynnistyksen lyhyt tarkistuslista

1. Määritä aihealue, tililista, jakso ja analyysikysymykset.
2. Tarkista reitin GET /getUserFeed parametrit viiteoppaasta ja todellinen vastaus Postmanissa.
3. Tallenna JSON-esimerkki ja määritä normalisoija vahvistetuille kentille.
4. Tallenna raakavastaus ja erilliset tilannekuvat keräysaikoineen.
5. Laske numeeriset mittarit koodilla; käytä tekoälyä tekstin alustavaan ryhmittelyyn.
6. Lisää ajastus, lokitus, uudelleenyritysten käsittely ja säilytysaika.

Näin seurannasta tulee toistettava tutkimus: jokainen päätelmä liittyy julkaisuun ja havaintoaikaan, ja koodi perustuu valitun reitin todelliseen skeemaan.