TikTok-hakutulosten arkistointi Pythonilla

Kampanjan käynnistämisen jälkeen tiimin voi olla hyödyllistä tarkistaa, mitä julkisia videoita valittujen sanojen hakutuloksissa näkyy. Manuaalista hakua on vaikea toistaa ja vertailla muutaman päivän kuluttua. Pieni keruuohjelma voi suorittaa samat kyselyt aikataulun mukaan ja arkistoida vastaukset päivämäärän ja hakulausekkeen kanssa, jotta analyytikko voi tarkistaa tietueet ja laatia oman yhteenvedon.

Tässä oppaassa esitellään Pythonilla toteutettava arkistointiputki, joka tallentaa kiinteiden hakulausekkeiden tulokset. Yksittäisten hashtagien tai tilien seurannasta poiketen vertailun avain on samojen hakulausekkeiden toistaminen ja kustakin vastauksesta erillisen tilannekuvan tallentaminen. jsonscraperin TikTok Scraper API -sivu ilmoittaa perusosoitteen ja reitin GET /searchVideo; reitin dokumentaatiossa hakulauseke välitetään pakollisessa keyword-parametrissa.

Tehtävä ja mittauksen rajat

Oletetaan, että markkinoija haluaa kerätä päivittäin hakutulokset muutamalle kiinteälle lausekkeelle: tuotteen nimelle, tuoteryhmälle ja asiakkaan ongelmaa kuvaavalle ilmaukselle. Järjestelmä tallentaa kunkin kyselyn kohdalla keruuajan ja API-vastauksen. Kun vastausesimerkki on tarkistettu, voidaan lisätä niiden JSONissa todella esiintyvien kenttien normalisointi, kuten videon tunniste tai julkiset laskurit, jos ne ovat mukana.

Arkisto vastaa täsmälliseen kysymykseen: mitä tietueita haku palautti tallennetulle lausekkeelle kyseisellä ajokerralla? Jos vastaus sisältää mittareita, toistuvat havainnot voivat näyttää eri ajankohtina tallennettujen arvojen välisen eron. Ero koskee havaittuja tilannekuvia ja niiden välistä aikaväliä; vertailua varten tallenna molemmat keruuajat ja sama kenttä.

Tallenna kysely vastauksen kanssa. Tulosten sisältö liittyy tiettyyn hakulausekkeeseen ja keruuajankohtaan. Siksi arkisto soveltuu valittujen kyselyjen hakutulosten seurantaan, ei koko TikTok-sisällön kattavaksi yleiskatsaukseksi. Tunnisteet, alkuperäiset vastaukset ja aikaleimat auttavat tarkistamaan, mistä myöhemmän taulukon kukin rivi on peräisin.

Tarkista reitti ja sen parametrit

TikTok API -reittikartassa ilmoitetaan perusosoite https://tiktok.evelode.com ja GET /searchVideo. Ajantasaisen API-määrittelyn mukaan keyword on pakollinen hakusparametri; valinnaisiin parametreihin kuuluvat cursor, count, cache_timeout, date_posted, sort_by ja region. Tunnistautumisessa käytetään license_key-parametria. Reitin tiedot löytyvät myös Python SDK:n dokumentaatiosta.

count- ja date_posted-parametrit auttavat määrittämään vastauksen koon ja aikarajauksen; sort_by hyväksyy dokumentoidut arvot most-liked, relevance tai date-posted. Jos käytät sivutusta, välitä edellisessä vastauksessa saatu cursor sellaisenaan äläkä laske sitä itse. Vertailukelpoista päivittäistä arkistoa varten tallenna kyselyn parametrit ja oman koodisi versio datan yhteyteen.

Alla olevassa esimerkissä käytetään pientä count-arvoa testiajoon ja kiinteää US-aluetta. Tarkista ennen päivittäistä keruuta yksi kysely, sen HTTP-tila ja JSONin rakenne. Vastausskeemassa löydetyt videot voivat olla muodossa tiktok.aweme_list tai muodossa tiktok.search_item_list, jossa video-objekti sijaitsee kohdassa aweme_info; koodi tukee molempia havaittuja muotoja.

Valmistele projekti

Luo virtuaaliympäristö ja asenna requests:

python -m venv .venv
source .venv/bin/activate
pip install requests

PowerShellissä ympäristö aktivoidaan komennolla .venv\Scripts\Activate.ps1. Määritä avain ja hakulausekkeiden luettelo ympäristömuuttujien avulla. Käytä TikTok API:ssa dokumentoitua muuttujan nimeä JSONSCRAPER_TIKTOK_LICENSE_KEY:

export JSONSCRAPER_TIKTOK_LICENSE_KEY="oma_avaimesi"
export TIKTOK_QUERIES="tuotteen nimi,tuoteryhmä,asiakkaan ongelma"

Kerää ja tallenna tilannekuvat

Esimerkki lähettää yhden kyselyn kutakin hakulausetta kohti dokumentoituun reittiin ja tallentaa sitten alkuperäisen JSONin, keruuajan ja käytetyt parametrit. Tiedostonimessä näkyvät päivämäärä ja hakulauseke. Avain säilytetään ympäristössä eikä sitä lisätä arkistoon.

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("API palautti muun kuin ok-tilan")

    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"Tallennettu vastaus kyselylle: {query}")
    time.sleep(1)

print(f"Tallennettuja vastauksia: {len(QUERIES)}")

Tämä vähimmäistoteutus tekee yhden kyselyn kutakin lausetta kohti käyttäen arvoa count=10. Laajempaa keruuta varten lisää sivutus cursor-parametrilla: jatka kyselyitä välittämällä vastauksen kursoriarvo, kunnes API ilmoittaa, ettei tuloksia ole enempää, ja tallenna jokainen vastaus erikseen. Kursori ja tulosten määrä määrittävät yksittäisen haun; tallennetusta JSONista voi myöhemmin tarkistaa, mitä kukin kysely palautti.

Esimerkki tarkistaa ulomman status-arvon ja lukee sitten tiktok-objektin. Se kerää kohteet aweme_list-listasta sekä search_item_list[].aweme_info-polusta, jos tämä muoto on käytössä. Videotietueen mahdollisia kenttiä ovat tunniste, kuvaus, tekijä, linkki ja tilastot; yksittäisiä kenttiä voi puuttua. Tallenna siis koko vastaus ja tarkista jokaisen kentän olemassaolo tietoja normalisoidessasi.

Yhden sekunnin tauko on skriptin omien kyselyiden välinen viive, ei väite palvelun rajoituksista. Määritä kyselytiheys ja uudelleenyritykset käyttöehtojen ja dokumentaation mukaan. cache_timeout-parametri on dokumentoitu haulle; sillä voi määrittää välimuistin keston sekunteina, ja määrittelyn mukaan arvo 0 poistaa välimuistin käytöstä. Lisää parametri kyselyyn, kun tämä toimintatapa sopii käyttötarkoitukseesi.

Lisää normalisointi todellisen vastauksen perusteella

Avaa tallennettu tiedosto ensimmäisen ajon jälkeen ja tutki payload-rakennetta. Esimerkin extract_videos-funktio kerää kohteet vastaukselle dokumentoiduista kahdesta hakutulosten paikasta. Selvitä analyysiin tarvittavien kenttien tarkat avaimet. Jos kenttä puuttuu yksittäisestä tietueesta, säilytä se puuttuvana äläkä korvaa sitä oletetulla luvulla.

Jatkoy käsittelyä varten on kätevää muodostaa yksi rivi kutakin löydettyä objektia kohti ja lisätä siihen collected_at ja query. Vahvistetut kentät voi tallentaa CSV-tiedostoon tai tietokantaan, ja alkuperäisen JSONin voi jättää arkistoon. Näin syntyy sekä käytännöllisiä taulukoita että mahdollisuus tarkistaa jokaisen tietueen alkuperä.

Jos API palauttaa videon tunnisteen, käytä sitä saman videon eri ajoilla tehtyjen havaintojen yhdistämiseen. Säilytä kukin havainto erikseen äläkä ylikirjoita aiempia tietoja. Jos pysyvää tunnistetta ei ole, selvitä ensin, millä ominaisuuksilla tietueita voi yhdistää, äläkä oleta kuvauksen tekstin perusteella tehtyä osumaa varmaksi.

Vertaile tilannekuvia ja laadi raportti

Ryhmittele tietueet normalisoinnin jälkeen tarkistetun tunnisteen mukaan ja lajittele ne keruuajan perusteella. Laskurikenttien kahden peräkkäisen arvon erotuksen voi laskea tavallisella koodilla. Esimerkiksi muutos arvosta 12 400 arvoon 18 900 tarkoittaa, että laskurin arvo muuttui tilannekuvien välillä 6 500:lla. Ilmoita raportissa havaintojen päivämäärät ja alkuperäinen kenttä, jotta lukija voi tarkistaa laskelman.

Hyödylliseen yhteenvetotaulukkoon kuuluvat hakulauseke, julkaisun tunniste, keruuaika ja valitut vastauskentät. Yhteenvedon voi ryhmitellä kyselyiden mukaan ja lajitella yhden vahvistetun laskurin perusteella. Näin tiimi saa tarkistettavan luettelon palautetuista tietueista myöhempää tarkastelua varten; toteuta taulukko tai viesti erillisenä vaiheena, kun olet tutustunut todelliseen skeemaan.

Tallenna JSON-tiedostot aluksi paikallisesti. Kun keruusta tulee säännöllistä, siirrä normalisoidut rivit PostgreSQL:ään tai analytiikkavarastoon ja alkuperäiset vastaukset objektitallennukseen, jonka tiedostonimessä ovat päivämäärä ja kysely. Alkuperäisen vastauksen säilyttäminen on erityisen hyödyllistä jäsentimen kehityksen aikana: sen voi suorittaa uudelleen historiallisella datalla ilman uutta API-kyselyä.

Aikatauluta keruu

Päivittäistä arkistoa varten käynnistä skripti cronilla tai muulla ympäristössäsi käytettävissä olevalla ajastimella. Tehtävä voi esimerkiksi suorittaa Python-tiedoston kerran vuorokaudessa ja välittää avaimen sekä hakulausekkeet ympäristömuuttujien kautta. Tarkista ennen säännöllistä käyttöä yksi kysely, sitten koko luettelo ja ota aikataulu käyttöön vasta sen jälkeen.

Luotettavaa ajoa varten tallenna kunkin kyselyn tila, rajoita väliaikaisten virheiden uudelleenyritysten määrää ja merkitse keruu keskeneräiseksi, jos jokin hakulauseke epäonnistuu. Älä sisällytä avainta virheilmoituksiin. Tiedostojen erottelu päivämäärän ja kyselyn nimen mukaan on myös hyödyllistä, jotta uusi ajo ei ylikirjoita aiempaa tilannekuvaa.

Valitse keruutiheys tehtävän ja kyselymäärän perusteella. Päivittäiseen yleiskatsaukseen riittää yksi ajo päivässä; tiheämpi keruu on perusteltua, jos tiimiä kiinnostavat päivänsisäiset muutokset. Aloita pienellä hakulausekkeiden joukolla, tarkista palautettujen tulosten hyödyllisyys ja laajenna keruuta sitten käyttöehtojen ja datan käyttöä koskevien sääntöjen puitteissa.

Hyödynnä tekoälyä aiheiden ryhmittelyssä

Kun vastausskeema on vahvistettu, valitut tekstikentät voi antaa mallille kuvausten ryhmittelyyn ennalta määriteltyjen aiheiden mukaan tai lyhyen yhteenvedon luonnoksen laatimiseen. Säilytä luokittelun yhteydessä alkuperäisen julkaisun tunniste, hakulauseke ja tekstikatkelma, johon luokka perustuu. Näin analyytikko voi siirtyä mallin päätelmästä alkuperäiseen tietueeseen.

Laske numeeriset erot, lajittelu ja kaksoiskappaleiden poisto tavallisella koodilla. Malli sopii tekstin käsittelyyn ja raportin sanamuotojen laatimiseen; laskurien arvot ja aikaleimat tulee ottaa tallennetuista vastauksista. Näiden toimintojen erottelu tekee jokaisen päätelmän alkuperän ymmärrettäväksi.

Tarkista osa automaattisista luokitteluista käsin ja tallenna korjaukset testiesimerkeiksi. Jos erityyppiset julkaisut päätyvät toistuvasti samaan ryhmään, täsmennä luokkien määritelmiä ja tarkista luokittelu uudelleen. Näin luokittelun laatua voi arvioida oman tehtävän datalla.

Yhteenveto: toistettava arkisto ja tarkistettava kooste

Kun dokumentoitu kysely suoritetaan keyword-parametrilla, tiimille syntyy arkisto siitä, mitä hakulausekkeita käytettiin, milloin ne suoritettiin ja mitä tietoja API palautti kullekin niistä. Sen pohjalta voi rakentaa tulostaulukon, vertailla vahvistettuja kenttiä tilannekuvien välillä ja laatia luettelon löydetyistä julkaisuista manuaalista analyysia varten.

Aloita yhdellä testikyselyllä ja määritä sitten hakulausekkeiden luettelo sekä aikataulu. TikTok Scraper API:n kuvauksessa annetaan perusosoite ja reittikartta; /searchVideo-parametrit ja vastausmuoto kuvataan API-määrittelyssä. Vahvistettujen vastausten arkistointi luo perustan toistettavalle, kiinteisiin hakulausekkeisiin perustuvalle analyysille.