Cotygodniowy raport z wyszukiwania na TikToku jest przydatny, gdy pokazuje, jakie filmy pojawiły się w kolejnej próbce od poprzedniego uruchomienia. Wystarczy zapisywać identyfikatory już napotkanych filmów i dodawać do pliku CSV nowe wyniki. Poniżej znajduje się powtarzalny skrypt w Pythonie korzystający z TikTok Scraper API: wyszukuje filmy według słowa kluczowego, analizuje obie udokumentowane struktury odpowiedzi i prowadzi lokalną bazę identyfikatorów.
Cel: wychwytywać nowe pozycje, zamiast ponownie przeglądać cały zestaw wyników
Zespołowi wsparcia, badaczowi rynku lub analitykowi treści może być potrzebna regularna próbka publicznych filmów na podstawie zapytania dotyczącego produktu. Jeśli za każdym razem pobierany jest cały wynik, powtarzające się filmy utrudniają przegląd, a nowe pozycje giną wśród już przetworzonych. Dziennik identyfikatorów pozwala porównywać wyniki kolejnych uruchomień: plik CSV zawiera tylko filmy nowe dla tego procesu oraz podstawowe pola zwrócone w odpowiedzi.
Taki dziennik odpowiada na ograniczone, ale praktyczne pytanie: które elementy pojawiły się w odpowiedzi bieżącego uruchomienia, a nie było ich w zapisanym zbiorze identyfikatorów? Przydaje się to do ręcznego przeglądu oraz przekazywania danych do arkusza lub dalszej analizy. Próbka odzwierciedla wyniki API dla określonego zapytania; sama w sobie nie opisuje wszystkich publikacji na TikToku.
Co przygotować
- Python 3.8 lub nowszy.
- Dostęp do TikTok Scraper API i klucz licencyjny.
- Zapytanie, które można powtarzać bez zmiany znaczenia, na przykład nazwę produktu lub konkretne wyrażenie.
Zapisz klucz w zmiennej środowiskowej JSONSCRAPER_TIKTOK_LICENSE_KEY, a nie w pliku ze skryptem. W poniższym przykładzie klucz jest przekazywany jako parametr zapytania license_key, zgodnie ze schematem API. Nie wypisuj go w logach.
export JSONSCRAPER_TIKTOK_LICENSE_KEY="twój_klucz"
python -m pip install requests
W systemie Windows zmienną można ustawić w bieżącej sesji PowerShell tak: $env:JSONSCRAPER_TIKTOK_LICENSE_KEY="twój_klucz". Nie dodawaj prawdziwych sekretów do Git ani współdzielonego pliku CSV.
Integracja: wysłanie zapytania wyszukującego i normalizacja JSON
Dokumentacja opisuje trasę GET /searchVideo do wyszukiwania filmów z wymaganym parametrem keyword. W zapytaniu można też ustawić count, region, sortowanie, filtr czasu i kursor do przewijania wyników. W tym minimalnym przykładzie używane są tylko słowo kluczowe, liczba żądanych elementów i region USA. Dokumentacja tras TikTok API podaje dokładne nazwy parametrów.
Struktura odpowiedzi wyszukiwania wymaga szczególnej uwagi: tablica aweme_list może być pusta, a elementy filmów mogą znajdować się w search_item_list, gdzie dane są zagnieżdżone w aweme_info. Dlatego kod sprawdza obie ścieżki, następnie łączy elementy i usuwa duplikaty na podstawie aweme_id. Zapobiega to sytuacji, w której poprawnie sparsowany JSON zostaje błędnie zamieniony w pusty raport.
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 = "nazwa produktu"
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("Ustaw 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()
# Przykład odpowiedzi zawiera zewnętrzny status i zagnieżdżony obiekt tiktok.
if "status" in data and data["status"] != "ok":
raise RuntimeError("API zwróciło status inny niż ok")
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)
# Unikalne elementy bieżącej odpowiedzi z zachowaniem kolejności.
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"W odpowiedzi: {len(current)} unikalnych filmów; nowych: {len(new_items)}")
Skrypt zapisuje brakujące w JSON wartości jako puste komórki: poszczególne wpisy mogą nie zawierać niektórych pól ani metryk. Kod nie zastępuje braków zerem ani nie traktuje zera jako braku danych. Czas zbierania jest zapisany osobno od czasu publikacji, który API zwraca w polu create_time.
Jak działa sprawdzanie zmian
- Zapytanie zwraca stronę wyników wyszukiwania dla określonego słowa kluczowego.
- Normalizator zbiera wpisy z
aweme_listisearch_item_list[].aweme_info. - Skrypt usuwa duplikaty w obrębie odpowiedzi na podstawie identyfikatora filmu.
- Identyfikatory są porównywane z lokalnym dziennikiem JSON.
- Nowe identyfikatory trafiają do pliku CSV, a następnie cały napotkany zbiór jest zapisywany na potrzeby kolejnego uruchomienia.


Wizualizacja tego procesu jest przydatna podczas przekazywania skryptu współpracownikom: CSV to dziennik przyrostowy, a JSON przechowuje stan deduplikacji. Można je trzymać i archiwizować razem, ale osobno od kodu. W przypadku uruchamiania zespołowego lub w chmurze zastąp lokalny plik JSON odpowiednim trwałym magazynem i zadbaj o atomową aktualizację stanu, aby równoległe uruchomienia nie nadpisywały swoich zmian.
Ponowne uruchamianie i paginacja
Uruchamiaj skrypt cyklicznie za pomocą harmonogramu systemowego, zadania CI lub procesu automatyzacji. Nie zmieniaj słowa kluczowego bez odnotowania jego wersji: różne zapytania tworzą różne próbki, a mieszanie ich w jednym dzienniku utrudnia interpretację. Dla uproszczenia przedstawiony skrypt obsługuje jedno zapytanie; listę zapytań można przetwarzać w pętli, zapisując wartość w polu query dla każdego wiersza.
API obsługuje parametr cursor do przewijania wyników wyszukiwania. Jeśli dodajesz paginację, przekazuj kursor z poprzedniej odpowiedzi, przechowuj go jako nieprzezroczystą wartość i zakończ pobieranie, gdy dalsze strony nie będą potrzebne. Parametr count określa liczbę żądanych elementów, ale faktyczną liczbę wpisów należy ustalić na podstawie odpowiedzi. Nawet kilka stron to nadal pobrane strony wyników wyszukiwania, a nie gwarancja pełnego pokrycia platformy.
W bieżącym przykładzie celowo nie ma automatycznej klasyfikacji tekstu ani wnioskowania o „trendzie”. CSV ułatwia wyodrębnienie nowych znalezionych wpisów; analityk może następnie oznaczyć je według tematu, intencji lub rodzaju pytania i ręcznie sprawdzić przykłady. Jeśli korzystasz z modelu językowego, przekazuj mu tylko potrzebne pola tekstowe i poproś o zwracanie kategorii wraz z oryginalnym identyfikatorem, aby można było zweryfikować wynik i powiązać go z wpisem.
Kontrole i typowe błędy
- Błąd HTTP.
raise_for_status()zatrzymuje działanie przy kodzie HTTP spoza zakresu oznaczającego powodzenie. Zanim zaktualizujesz plik stanu, sprawdź dostępność API, parametry i konto. - Status API różni się od
ok. Skrypt zatrzymuje się przed zapisaniem wyników, jeśli odpowiedź zawiera najwyższego poziomu polestatusz inną wartością. Dzięki temu poprzedni dziennik pozostaje bez zmian i łatwiej uniknąć uznania błędnej odpowiedzi za pusty wynik. - Pusta lista w
aweme_list. Sprawdź równieżsearch_item_list; kod uwzględnia obie struktury. - Filmy powtarzają się między uruchomieniami. Jest to spodziewane w przypadku nakładających się stron wyników wyszukiwania: nie trafiają ponownie do raportu, jeśli ich identyfikator został już zapisany.
- Brak metryki. Komórka pozostaje pusta. W obliczeniach odróżniaj brakujące wartości od rzeczywistych zer.
- Utrata stanu. Skrypt uzna wszystkie zwrócone identyfikatory za nowe. Twórz kopię zapasową pliku
seen_video_ids.jsonrazem z CSV albo użyj trwałej bazy danych.
W automatyzacji zapisuj informacje diagnostyczne bez klucza: czas uruchomienia, kod HTTP, status API, liczbę przeanalizowanych wpisów i liczbę nowych identyfikatorów. Ułatwia to odróżnienie braku nowych filmów od nieudanego zapytania. Pełną oryginalną odpowiedź można osobno archiwizować, jeśli potrzebna jest późniejsza weryfikacja schematu; ogranicz dostęp i okres przechowywania zgodnie z potrzebami zespołu.
Rezultat
Po uruchomieniu otrzymujesz plik CSV z filmami o identyfikatorach nowych dla dziennika, opisami, linkami i dostępnymi polami publicznymi, a także stan JSON do porównania z kolejnym uruchomieniem. Taki wynik sprawdza się jako kompaktowa kolejka zadań dla zespołu wsparcia, analityków lub zespołu treści. Opis API i dostępnych wariantów dostępu znajdziesz na stronie TikTok Scraper API; dokładne parametry wyszukiwania sprawdzaj w oficjalnej dokumentacji tras.