Viikoittaisesta TikTok-hakuraportista on hyötyä, kun se näyttää, mitkä videot löytyivät edellisen ajon jälkeen tehdyssä haussa. Tätä varten riittää, että tallennat jo nähtyjen videoiden tunnisteet ja lisäät CSV-tiedostoon uudet hakutulokset. Alla on toistettava Python-esimerkki, joka käyttää TikTok Scraper APIa: se hakee videoita avainsanalla, käsittelee dokumentoidut vastausmuodot ja ylläpitää paikallista tunnistetietokantaa.
Tavoite: huomaa uudet julkaisut koko tulosjoukon läpikäynnin sijaan
Tukitiimi, markkinatutkija tai sisältöanalyytikko voi tarvita säännöllisesti poiminnan julkisista videoista tietyn tuotehaun perusteella. Jos tulos viedään joka kerta kokonaisuudessaan, toistuvat videot hidastavat tarkastelua ja uudet julkaisut hukkuvat jo käsiteltyjen joukkoon. Tunnisteloki tekee jokaisen ajon tuloksesta vertailukelpoisen: CSV sisältää vain tämän prosessin kannalta uudet videot sekä vastauksessa palautuneet keskeiset kentät.
Tällainen loki vastaa rajattuun mutta käytännölliseen kysymykseen: mitkä videot esiintyivät tämän ajon vastauksessa mutta eivät tallennetussa tunnistejoukossa? Tämä sopii manuaalisen tarkastelun jonoksi sekä tietojen siirtämiseen taulukkoon tai jatkoanalyysiin. Poiminta kuvaa API:n tuloksia annetulle haulle; se ei itsessään kuvaa kaikkia TikTok-julkaisuja.
Mitä tarvitset
- Python 3.8 tai uudempi.
- Pääsy TikTok Scraper APIin ja lisenssiavain.
- Hakutermi, jota voi käyttää uudelleen merkitystä muuttamatta, kuten tuotteen nimi tai tietty ilmaus.
Tallenna avain ympäristömuuttujaan JSONSCRAPER_TIKTOK_LICENSE_KEY äläkä skriptitiedostoon. Alla olevassa esimerkissä avain välitetään API-määrityksen mukaisesti pyyntöparametrina license_key. Älä tulosta sitä suorituslokiin.
export JSONSCRAPER_TIKTOK_LICENSE_KEY="oma_avaimesi"
python -m pip install requests
Windows PowerShellissä voit asettaa muuttujan nykyistä istuntoa varten näin: $env:JSONSCRAPER_TIKTOK_LICENSE_KEY="oma_avaimesi". Älä lisää oikeita salaisuuksia Gitiin tai jaettuun CSV-tiedostoon.
Integrointi: tee hakupyyntö ja normalisoi JSON
Videohaun dokumentoitu GET-reitti on /searchVideo, ja se edellyttää keyword-parametria. Pyyntöön voi lisätä myös count-parametrin, alueen, lajittelun, aikarajauksen ja tulosten sivutukseen tarkoitetun kursorin. Tässä yksinkertaisessa esimerkissä käytetään vain avainsanaa, pyydettävien kohteiden määrää ja Yhdysvaltain aluetta. TikTok API -reittien hakemisto sisältää parametrien tarkat nimet.
Haun vastausrakenteeseen on kiinnitettävä huomiota: aweme_list-taulukko voi olla tyhjä, ja videotietueet voivat olla search_item_list-taulukossa, jossa tiedot ovat aweme_info-kentän sisällä. Siksi koodi tarkistaa molemmat polut, yhdistää tietueet ja poistaa kaksoiskappaleet aweme_id-tunnisteen perusteella. Näin onnistuneesti jäsennetty JSON ei virheellisesti muutu tyhjäksi raportiksi.
import csv
import json
import os
from pathlib import Path
from datetime import datetime, timezone
import requests
BASE_URL = "https://tiktok.evelode.com/searchVideo"
KEYWORD = "tuotteen nimi"
REGION = "US"
COUNT = 30
STATE_FILE = Path("seen_video_ids.json")
OUTPUT_FILE = Path("new_tiktok_videos.csv")
license_key = os.environ.get("JSONSCRAPER_TIKTOK_LICENSE_KEY")
if not license_key:
raise RuntimeError("Aseta JSONSCRAPER_TIKTOK_LICENSE_KEY")
response = requests.get(
BASE_URL,
params={
"license_key": license_key,
"keyword": KEYWORD,
"count": COUNT,
"region": REGION,
},
timeout=60,
)
response.raise_for_status()
data = response.json()
# Esimerkkivastauksessa on ulompi status ja sisäkkäinen tiktok-objekti.
if "status" in data and data["status"] != "ok":
raise RuntimeError("API palautti muun kuin ok-tilan")
tiktok = data.get("tiktok") or {}
items = list(tiktok.get("aweme_list") or [])
for entry in tiktok.get("search_item_list") or []:
info = entry.get("aweme_info")
if isinstance(info, dict):
items.append(info)
# Nykyisen vastauksen yksilölliset tietueet alkuperäisessä järjestyksessä.
current = {}
for item in items:
video_id = item.get("aweme_id")
if video_id:
current[str(video_id)] = item
if STATE_FILE.exists():
seen = set(json.loads(STATE_FILE.read_text(encoding="utf-8")))
else:
seen = set()
new_items = [(video_id, item) for video_id, item in current.items()
if video_id not in seen]
run_time = datetime.now(timezone.utc).isoformat()
fields = ["collected_at_utc", "query", "aweme_id", "created_at",
"author", "description", "share_url", "play_count",
"digg_count", "comment_count", "share_count"]
write_header = not OUTPUT_FILE.exists() or OUTPUT_FILE.stat().st_size == 0
with OUTPUT_FILE.open("a", newline="", encoding="utf-8") as f:
writer = csv.DictWriter(f, fieldnames=fields)
if write_header:
writer.writeheader()
for video_id, item in new_items:
author = item.get("author") or {}
stats = item.get("statistics") or {}
writer.writerow({
"collected_at_utc": run_time,
"query": KEYWORD,
"aweme_id": video_id,
"created_at": item.get("create_time"),
"author": author.get("unique_id") or author.get("nickname"),
"description": item.get("desc"),
"share_url": item.get("share_url"),
"play_count": stats.get("play_count"),
"digg_count": stats.get("digg_count"),
"comment_count": stats.get("comment_count"),
"share_count": stats.get("share_count"),
})
seen.update(current.keys())
STATE_FILE.write_text(json.dumps(sorted(seen)), encoding="utf-8")
print(f"Vastauksessa: {len(current)} yksilöllistä videota; uusia: {len(new_items)}")
Skripti kirjoittaa JSONista puuttuvat arvot tyhjiksi soluiksi: yksittäisestä tietueesta voi puuttua kenttiä ja mittareita. Koodi ei korvaa puuttuvaa arvoa nollalla eikä käsittele nollaa puuttuvana tietona. Keräysaika merkitään erikseen julkaisuaikaan nähden; API palauttaa julkaisuajan kentässä create_time.
Miten muutosseuranta toimii
- Pyyntö palauttaa hakutulossivun annetulla avainsanalla.
- Normalisoija kokoaa tietueet poluista
aweme_listjasearch_item_list[].aweme_info. - Skripti poistaa vastauksen sisäiset kaksoiskappaleet videon tunnisteen perusteella.
- Tunnisteita verrataan paikalliseen JSON-lokiin.
- Uudet tunnisteet lisätään CSV-tiedostoon, minkä jälkeen koko nähty tunnistejoukko tallennetaan seuraavaa ajoa varten.


Prosessin visualisoinnista on hyötyä, kun skripti siirretään kollegoiden käyttöön: CSV on lisäysloki ja JSON sisältää kaksoiskappaleiden poiston tilan. Ne voi säilyttää erillään koodista ja varmuuskopioida yhdessä. Tiimi- tai pilviajoa varten korvaa paikallinen JSON-tiedosto sopivalla pysyvällä tallennusratkaisulla ja varmista tilan atominen päivitys, jotta rinnakkaiset ajot eivät ylikirjoita toisiaan.
Uudelleenajo ja sivutus
Toista ajo aikatauluttamalla se käyttöjärjestelmän ajastimella, CI-tehtävällä tai automaatiotyönkululla. Älä muuta avainsanaa kirjaamatta sen versiota: eri haut muodostavat eri otoksia, ja niiden yhdistäminen samaan lokiin vaikeuttaa tulkintaa. Yksinkertaisuuden vuoksi esimerkkiskripti käyttää yhtä hakua; voit käsitellä hakutermien luetteloa silmukassa ja tallentaa kunkin rivin query-kenttään.
API tukee hakutulosten sivutukseen cursor-parametria. Jos lisäät sivutuksen, välitä edellisen vastauksen kursori eteenpäin, käsittele sitä läpinäkymättömänä arvona ja lopeta, kun uusia sivuja ei enää tarvita. count-parametri asettaa pyydettävien kohteiden määrän, mutta todellinen tietuemäärä on tarkistettava vastauksesta. Useampikin sivu on silti vain joukko haun kautta saatuja tulossivuja, eikä se takaa koko alustan kattavaa otosta.
Tässä esimerkissä ei tarkoituksella luokitella tekstiä automaattisesti eikä tehdä päätelmiä ”trendistä”. CSV auttaa nostamaan uudet löydetyt tietueet nopeasti esiin; analyytikko voi sen jälkeen luokitella ne aiheen, tarkoituksen tai kysymystyypin mukaan ja tarkistaa esimerkit manuaalisesti. Jos otat käyttöön kielimallin, välitä sille vain tarvittavat tekstikentät ja pyydä palauttamaan luokat yhdessä alkuperäisen tunnisteen kanssa, jotta tulos voidaan tarkistaa ja yhdistää tietueeseen.
Tarkistukset ja yleiset virheet
- HTTP-virhe.
raise_for_status()keskeyttää suorituksen, jos HTTP-koodi ei kuulu onnistuneisiin koodeihin. Tarkista API:n saatavuus, parametrit ja tili ennen tilatiedoston päivittämistä. - API:n tila ei ole
ok. Skripti keskeyttää ennen tulosten kirjoittamista, jos vastauksessa on ylätasonstatus-kenttä, jonka arvo poikkeaa muusta. Näin aiempi loki säilyy eikä virheellistä vastausta tulkita tyhjäksi tulosjoukoksi. aweme_liston tyhjä. Tarkista myössearch_item_list; koodi käsittelee molemmat rakenteet.- Videot toistuvat ajojen välillä. Tämä on odotettavissa, kun hakutulossivut menevät päällekkäin: videot eivät päädy raporttiin uudelleen, jos niiden tunniste on jo tallennettu.
- Mittari puuttuu. Solu jää tyhjäksi. Erota puuttuvat arvot todellisista nollista laskennassa.
- Tila katoaa. Skripti käsittelee kaikki palautuneet tunnisteet uusina. Varmuuskopioi
seen_video_ids.jsonyhdessä CSV-tiedoston kanssa tai käytä pysyvää tietokantaa.
Automatisoinnissa tallenna diagnostiikkatiedot ilman avainta: ajoaika, HTTP-koodi, API:n tila, jäsennettyjen tietueiden määrä ja uusien tunnisteiden määrä. Näin voit erottaa sen, ettei uusia videoita löytynyt, epäonnistuneesta pyynnöstä. Voit arkistoida alkuperäisen kokonaisen vastauksen erikseen, jos skeemaa on myöhemmin tarkistettava; rajoita käyttöoikeuksia ja säilytysaikaa tiimin tarpeiden mukaan.
Tulos
Ajettuasi skriptin sinulla on CSV, jossa ovat lokin kannalta uudet videotunnisteet, kuvaukset, linkit ja saatavilla olevat julkiset kentät, sekä JSON-tila seuraavan ajon vertailua varten. Tulos sopii kompaktiksi syötteeksi tukitiimille, analytiikkaan tai sisältötiimille. Voit tutustua API:n kuvaukseen ja käyttöoikeusvaihtoehtoihin TikTok Scraper API -sivulla; tarkista haun täsmälliset parametrit virallisesta reittihakemistosta.