TikTok: muuta hakutulokset viikoittaiseksi tukiaiheiden listaksi

Tukitiimi tarvitsee listan julkisista TikTok-videoista, joissa ihmiset keskustelevat epäselvästä ominaisuudesta tai esittävät tuotetta koskevia kysymyksiä. Manuaalista hakua on vaikea toistaa yhdenmukaisesti, ja hakujen API-vastaukset voivat tallentaa videot JSONissa eri kohtiin. Alla on yksinkertainen Python-skripti, joka hakee tuloksia avainsanoilla, yhdistää molemmat rakenteet, poistaa ID:n perusteella kaksoiskappaleet ja tallentaa löydetyt tietueet CSV-tiedostoon.

Mitä skripti tuottaa

Tuloksena syntyy taulukko, jossa on videon ID, linkki, kuvaus, julkaisuaika, tekijä ja saatavilla olevat reaktiolaskurit. Tuki- tai markkinointitiimi voi merkitä manuaalisesti, mitkä aiheet edellyttävät vastausta, ohjeen päivittämistä tai tarkistamista omasta CRM-järjestelmästä. Taulukko kuvaa vain määritetyillä hakulausekkeilla API:n palauttamia tuloksia. Käsittele sitä työlistana, älä kattavana luettelona kaikista keskusteluista.

Skripti hoitaa keruun ja alustavan lajittelun. Se ei päättele automaattisesti, onko kuvaus kysymys, valitus vai vitsi. Tällainen luokitus kannattaa lisätä manuaalisen tarkistuksen jälkeen tai erillisellä luokittimella ja kirjata samalla alkuperäinen teksti sekä päätöksen perustelu.

Mitä haetaan ja millainen vastaus on

jsonscraper dokumentoi videohakuun GET-reitin /searchVideo palvelimessa https://tiktok.evelode.com. Pakollinen parametri on keyword. Lisäksi voi antaa count-parametrin, alueen, lajittelun, julkaisujakson ja seuraavan sivun kursorin. Haun voi esimerkiksi toistaa useilla ennalta määritetyillä lausekkeilla: ominaisuuden nimellä, yleisellä virheilmoituksella ja lyhyellä asetuksia koskevalla kysymyksellä. Parametrit ja niiden sallitut arvot on lueteltu TikTok API:n ohjeessa.

Hakuvastauksessa on yksi parserin kannalta tärkeä erityispiirre: aweme_list-taulukko voi olla tyhjä, vaikka löydetyt objektit olisivat search_item_list-taulukossa ja kunkin alkion sisällä aweme_info-kentässä. Siksi alla oleva käsittelijä tarkistaa molemmat muodot. Esimerkkivastaus ja 25. lokakuuta 2026 tehdyssä tarkistuksessa havaitut kentät on esitetty jsonscraperin ensisijaisessa spesifikaatiossa. Tilastokentät voivat puuttua, joten koodi ei täytä niitä keksityillä arvoilla.

Valmistele avain ja hakulausekkeet

Tallenna avain ympäristömuuttujaan JSONSCRAPER_TIKTOK_LICENSE_KEY, älä lähdekooditiedostoon. Linux- tai macOS-komentorivillä voit tehdä sen näin:

export JSONSCRAPER_TIKTOK_LICENSE_KEY="oma_avaimesi"

Asenna pyyntöjen tekemiseen käytettävä kirjasto ja luo queries.txt-tiedosto, jossa on yksi hakulauseke kullakin rivillä, esimerkiksi tuotteen nimi asetukset ja ominaisuuden nimi ei toimi. Valitse ilmaisut yleisön kielen mukaan ja ylläpidä erillistä listaa, jotta viikoittaisissa poiminnoissa voidaan vertailla samoja hakuja.

python -m pip install requests

Kerää ja yhdenmukaista löydetyt videot

Esimerkki on yhteensopiva Python 3.8:n ja uudempien versioiden kanssa. Se tekee jokaiselle lausekkeelle yhden pyynnön tulosrajoituksella, tarkistaa HTTP-virheet ja vastauksen ylätason tilan sekä tallentaa vain todella mukana olevat kentät. Päällekkäiset osumat yhdistetään aweme_id-kentän perusteella, ja kaikki haut, joilla video löytyi, tallennetaan keywords-kenttään. Erillinen collected_at_utc-kenttä merkitsee tietojen hakuajan tulevien ajojen vertailua varten.

import csv
import os
import sys
from datetime import datetime, timezone

import requests

BASE_URL = "https://tiktok.evelode.com/searchVideo"
API_KEY = os.environ.get("JSONSCRAPER_TIKTOK_LICENSE_KEY")

if not API_KEY:
    raise SystemExit("Määritä JSONSCRAPER_TIKTOK_LICENSE_KEY")


def get_items(tiktok):
    """Poimii videot hakuvastauksen molemmista dokumentoiduista muodoista."""
    items = list(tiktok.get("aweme_list") or [])
    for entry in tiktok.get("search_item_list") or []:
        info = entry.get("aweme_info") if isinstance(entry, dict) else None
        if info:
            items.append(info)
    return items


with open("queries.txt", encoding="utf-8") as query_file:
    queries = [line.strip() for line in query_file if line.strip()]

collected_at = datetime.now(timezone.utc).isoformat()
videos = {}

for keyword in queries:
    response = requests.get(
        BASE_URL,
        params={
            "license_key": API_KEY,
            "keyword": keyword,
            "count": 30,
            "region": "US",
            "sort_by": "relevance",
        },
        timeout=30,
    )
    response.raise_for_status()
    payload = response.json()

    if payload.get("status") != "ok":
        print("API palautti epäonnistuneen tilan haulle:", keyword, file=sys.stderr)
        continue

    tiktok = payload.get("tiktok") or {}
    for item in get_items(tiktok):
        video_id = item.get("aweme_id")
        if not video_id:
            continue

        if video_id not in videos:
            author = item.get("author") or {}
            stats = item.get("statistics") or {}
            videos[video_id] = {
                "aweme_id": video_id,
                "keywords": [keyword],
                "description": item.get("desc"),
                "share_url": item.get("share_url"),
                "create_time": item.get("create_time"),
                "author": author.get("unique_id") or author.get("nickname"),
                "play_count": stats.get("play_count"),
                "digg_count": stats.get("digg_count"),
                "comment_count": stats.get("comment_count"),
                "share_count": stats.get("share_count"),
                "collected_at_utc": collected_at,
            }
        elif keyword not in videos[video_id]["keywords"]:
            videos[video_id]["keywords"].append(keyword)

columns = [
    "aweme_id", "keywords", "description", "share_url", "create_time",
    "author", "play_count", "digg_count", "comment_count", "share_count",
    "collected_at_utc",
]
with open("tiktok_support_review.csv", "w", newline="", encoding="utf-8-sig") as output:
    writer = csv.DictWriter(output, fieldnames=columns)
    writer.writeheader()
    for video in videos.values():
        row = dict(video)
        row["keywords"] = " | ".join(row["keywords"])
        writer.writerow(row)

print("Tallennettuja ainutlaatuisia löydettyjä videoita:", len(videos))

Pyyntö lähetetään params-parametrin avulla, joten kirjasto koodaa tekstimuotoiset lausekkeet oikein URL-osoitteeseen. Avain on silti kyselyparametrissa, kuten ohjeissa kuvataan. Älä tulosta pyynnön koko URL-osoitetta sovelluksen lokiin. Vianmääritystä varten tallenna HTTP-vastauksen koodi, hakulausekkeen nimi ja käynnistysaika, mutta jätä pois salaisuudet ja tehtävän kannalta tarpeettomat henkilötiedot.

CSV:n tulkitseminen ilman virheellisiä päätelmiä

keywords-sarake sisältää kaikki lausekkeet, joilla video löytyi; collected_at_utc auttaa erottamaan hakuajan julkaisuajasta. ID soveltuu kaksoiskappaleiden poistamiseen ja linkki videon tarkistamiseen. Tyhjä laskurikenttä tarkoittaa, että kyseinen kenttä puuttui vastauksesta, ei sitä, että arvo olisi nolla.

Lisää ensimmäistä lajittelua varten CSV:n työkopioon sarakkeet aihe, signaalin tyyppi, vastausta tarvitaan ja linkki sisäiseen materiaaliin. Aihevaihtoehtojen tulisi vastata tuotettanne: esimerkiksi asennus, maksaminen, yhteensopivuus tai virheen korjaaminen. Näin poiminnasta muodostuu käsittelyjono, ja luokitus voidaan tarkistaa alkuperäisen videon perusteella.

Ajoita keruu

Suorita ensin skripti manuaalisesti ja tarkista muutama rivi ja linkki. Lisää se sitten cron-ajoon, CI-tehtävään tai automaatioskriptiin, joka pystyy käynnistämään Python-prosessin. Säännöllisiä raportteja varten tallenna kukin poiminta erikseen tai lisää rivit tietovarastoon, jossa videon ja tilannekuvan päivämäärän yhdistelmä toimii yksilöllisenä avaimena. Näin tiimi voi erottaa uudet löydetyt julkaisut toistuvista havainnoista ja seurata saatavilla olevien laskurien muutoksia ajojen välillä.

cursor-parametri on tarkoitettu hakutulosten selaamiseen; se on välitettävä edellisen kutsun vastauksesta. Tässä yksinkertaisessa esimerkissä sivutusta ei tarkoituksella ole mukana: rajattua hakujoukkoa on helpompi tarkistaa ja toistaa. Jos lisäät sivutuksen, käsittele kursoria läpinäkymättömänä arvona, lopeta jatkamisilmaisimen perusteella ja aseta yhden ajon kutsuille yläraja. API-pyyntö palauttaa otoksen; älä tulkitse rivimäärää TikTokin täydelliseksi kattavuudeksi.

Käytännön rajoitukset

Hakutulokset sopivat videoiden löytämiseen tiimin jo tuntemilla ilmaisuilla. Niiden avulla voi kerätä aineistoa luokittelua varten, mutta ne eivät korvaa saapuvia yhteydenottoja, oman sivuston analytiikkaa tai videon kontekstin tarkistamista. Kuvaus ei välttämättä kerro videon ydinsisältöä, ja saatavilla olevat mittarit kuvaavat tilannetta tietojen hakuhetkellä. Merkitse aiheet ja johtopäätökset erikseen alkuperäisistä kentistä, jotta henkilöstö voi tarkistaa luokituksen myöhemmin.

Ennen säännöllisen seurannan aloittamista määritä, kenellä on pääsy poimintoihin, kuinka kauan tietoja säilytetään ja mihin tarkoitukseen julkisia tietoja käytetään. Säilytä vain tuotteen käsittelyn kannalta tarpeelliset kentät ja suosi linkkejä alkuperäisiin julkaisuihin mediatiedostojen kopioimisen sijaan. Tutustu TikTok Scraper API -sivuun sekä hakureitin dokumentaatioon, kun haluat selvittää pyyntöön ja integraatiovaihtoehtojen tarkistamiseen liittyviä asioita.