Michael JohnsonPo uruchomieniu kampanii zespołowi może przydać się sprawdzenie, jakie publiczne filmy pojawiają się w wynikach wyszukiwania dla wybranych słów. Ręczne wyszukiwanie trudno powtórzyć i porównać po kilku dniach. Niewielki skrypt może uruchamiać te same zapytania według harmonogramu i archiwizować odpowiedzi wraz z datą oraz wyszukiwaną frazą, aby analityk mógł sprawdzić wpisy i przygotować własne zestawienie.
Ten poradnik przedstawia potok archiwizujący w Pythonie, który zapisuje wyniki wyszukiwania dla ustalonych fraz. W odróżnieniu od monitorowania poszczególnych hashtagów lub kont, kluczem do porównania jest tu ponawianie tych samych wyszukiwań i zapisywanie osobnego zrzutu każdej odpowiedzi. Strona TikTok Scraper API jsonscraper podaje adres bazowy i endpoint GET /searchVideo; dokumentacja tego endpointu określa, że frazę wyszukiwania przekazuje się w wymaganym parametrze keyword.
Cel i granice pomiaru
Załóżmy, że marketer chce codziennie zbierać wyniki dla kilku ustalonych fraz: nazwy produktu, kategorii i sformułowania opisującego problem klienta. Dla każdego zapytania system zapisuje czas zbierania danych i odpowiedź API. Po sprawdzeniu przykładowej odpowiedzi można dodać normalizację pól, które rzeczywiście występują w JSON-ie, na przykład identyfikatora filmu lub publicznych liczników, jeśli są dostępne.
Archiwum odpowiada na konkretne pytanie: jakie wpisy zwróciło wyszukiwanie dla zapisanej frazy podczas tego uruchomienia? Jeśli odpowiedź zawiera wskaźniki, kolejne obserwacje mogą pokazać różnicę między wartościami zarejestrowanymi w różnych momentach. Taka różnica dotyczy obserwowanych zrzutów i czasu, który je dzieli; aby umożliwić porównanie, zapisuj oba czasy zbierania danych i to samo pole.
Zapisuj zapytanie razem z odpowiedzią. Zestaw wyników zależy od konkretnej frazy i momentu zbierania danych. Dlatego archiwum przydaje się do śledzenia wyników dla wybranych zapytań, a nie jako pełny przegląd wszystkich treści na TikToku. Identyfikatory, oryginalne odpowiedzi i znaczniki czasu pomagają sprawdzić, skąd pochodzi każdy wiersz w późniejszej tabeli.
Sprawdź endpoint i jego parametry
Mapa endpointów TikTok API podaje adres bazowy https://tiktok.evelode.com i GET /searchVideo. Aktualna specyfikacja API wskazuje keyword jako wymagany parametr wyszukiwania; wśród parametrów opcjonalnych wymienia cursor, count, cache_timeout, date_posted, sort_by i region. Do autoryzacji przekazuje się license_key. Informacje o endpoincie są również dostępne w dokumentacji Python SDK.
Parametry count i date_posted pomagają określić wielkość odpowiedzi i zakres czasu; sort_by przyjmuje udokumentowane wartości most-liked, relevance lub date-posted. Jeśli korzystasz z paginacji, przekaż wartość cursor otrzymaną w poprzedniej odpowiedzi jako nieprzezroczystą wartość i nie obliczaj jej samodzielnie. Aby codzienne archiwum nadawało się do porównań, zapisuj obok danych parametry zapytania i wersję własnego kodu.
W poniższym przykładzie do testowego uruchomienia użyto małej wartości count i ustalonego regionu US. Przed codziennym zbieraniem danych sprawdź pojedyncze zapytanie, jego status HTTP i strukturę JSON. Schemat odpowiedzi może zawierać znalezione filmy w tiktok.aweme_list albo w tiktok.search_item_list, gdzie obiekt filmu znajduje się w aweme_info; kod obsługuje obie zaobserwowane formy.
Przygotuj projekt
Utwórz środowisko wirtualne i zainstaluj requests:
python -m venv .venv
source .venv/bin/activate
pip install requestsW PowerShell aktywacja środowiska odbywa się poleceniem .venv\Scripts\Activate.ps1. Ustaw klucz i listę wyszukiwanych fraz za pomocą zmiennych środowiskowych. W przypadku TikTok API użyj udokumentowanej nazwy zmiennej JSONSCRAPER_TIKTOK_LICENSE_KEY:
export JSONSCRAPER_TIKTOK_LICENSE_KEY="twój_klucz"
export TIKTOK_QUERIES="nazwa produktu,kategoria produktu,problem klienta"Zbieranie i zapisywanie zrzutów
Przykład wysyła po jednym zapytaniu dla każdej frazy do udokumentowanego endpointu, a następnie zapisuje oryginalny JSON, czas zbierania danych i użyte parametry. Nazwa pliku zawiera datę i wyszukiwaną frazę. Klucz jest przechowywany w środowisku i nie trafia do archiwum.
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 zwróciło status inny niż ok")
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"Zapisano odpowiedź dla zapytania: {query}")
time.sleep(1)
print(f"Zapisano odpowiedzi: {len(QUERIES)}")Ten minimalny skrypt wykonuje jedno zapytanie dla każdej frazy z count=10. Aby zebrać szerszy zakres danych, dodaj paginację za pomocą cursor: kontynuuj zapytania, przekazując wartość kursora z odpowiedzi, dopóki API informuje o dostępności kolejnych wyników, i zapisuj każdą odpowiedź osobno. Kursor i liczba wyników określają konkretny przebieg; zapisany JSON pozwala później sprawdzić, co dokładnie zwrócono w każdym zapytaniu.
Przykład sprawdza zewnętrzny status, a następnie odczytuje obiekt tiktok. Zbiera elementy z aweme_list, a także z search_item_list[].aweme_info, jeśli ta forma występuje. Potencjalne pola rekordu filmu obejmują identyfikator, opis, autora, link i statystyki; poszczególne pola mogą być nieobecne. Dlatego zapisuj pełną odpowiedź, a podczas normalizacji sprawdzaj obecność każdego pola.
Jednosekundowa przerwa to odstęp między zapytaniami wysyłanymi przez sam skrypt, a nie deklaracja dotycząca limitów usługi. Częstotliwość i ponowienia skonfiguruj zgodnie z warunkami dostępu i dokumentacją. Parametr cache_timeout jest udokumentowany dla wyszukiwania; pozwala określić czas przechowywania w pamięci podręcznej w sekundach, a zgodnie ze specyfikacją wartość 0 wyłącza buforowanie. Dodaj go do zapytania, jeśli takie działanie pasuje do twojego scenariusza.
Dodaj normalizację zgodną z rzeczywistą odpowiedzią
Po pierwszym uruchomieniu otwórz zapisany plik i sprawdź strukturę payload. Funkcja extract_videos z przykładu zbiera elementy z dwóch udokumentowanych miejsc, w których mogą występować formy wyników wyszukiwania. Znajdź dokładne klucze potrzebnych do analizy pól. Jeśli pole nie występuje w konkretnym rekordzie, zachowaj je jako brakującą wartość zamiast podstawiać przypuszczalną liczbę.
Do dalszego przetwarzania wygodnie jest utworzyć jeden wiersz dla każdego znalezionego obiektu, dodając do niego collected_at i query. Potwierdzone pola można zapisywać w pliku CSV lub bazie danych, a oryginalny JSON pozostawić w archiwum. Taki zestaw pozwala tworzyć przejrzyste tabele, a jednocześnie sprawdzać pochodzenie każdego wpisu.
Jeśli API zwraca identyfikator filmu, użyj go do powiązania obserwacji tego samego filmu z różnych uruchomień. Przechowuj każdą obserwację osobno i nie nadpisuj wcześniejszych. Jeśli brakuje stabilnego identyfikatora, najpierw sprawdź, które atrybuty pozwalają dopasować rekordy, i nie zakładaj, że zgodność tekstu opisu gwarantuje tożsamość.
Porównaj zrzuty i przygotuj raport
Po normalizacji pogrupuj rekordy według zweryfikowanego identyfikatora i posortuj je według czasu zbierania danych. Różnicę między kolejnymi wartościami pól będących licznikami można obliczyć zwykłym kodem. Na przykład zmiana z 12 400 na 18 900 oznacza, że między tymi zrzutami wartość licznika wzrosła o 6 500. W raporcie podaj daty obserwacji i nazwę pola źródłowego, aby czytelnik mógł sprawdzić obliczenie.
Przydatna struktura tabeli wynikowej obejmuje wyszukiwaną frazę, identyfikator publikacji, czas zbierania danych i wybrane pola z odpowiedzi. Zestawienie można pogrupować według zapytań i posortować według jednego potwierdzonego licznika. Dzięki temu zespół otrzyma możliwą do zweryfikowania listę zwróconych wpisów do dalszego przeglądu; tabelę lub wiadomość wdroż jako osobny etap po poznaniu rzeczywistego schematu.
Na początku przechowuj pliki JSON lokalnie. Gdy zbieranie danych stanie się regularne, przenieś znormalizowane wiersze do PostgreSQL lub hurtowni danych, a oryginalne odpowiedzi do magazynu obiektowego, używając daty i zapytania w nazwie. Zachowywanie oryginału jest szczególnie przydatne podczas ulepszania parsera: można ponownie uruchomić go na danych historycznych bez ponownego odpytywania API.
Uruchamiaj zbieranie danych według harmonogramu
Aby tworzyć codzienne archiwum, uruchamiaj skrypt przez cron lub inny harmonogram dostępny w twoim środowisku. Na przykład zadanie może raz dziennie uruchamiać plik Pythona, przekazując mu klucz i wyszukiwane frazy przez zmienne środowiskowe. Przed regularnym użyciem sprawdź jedno zapytanie, następnie całą listę i dopiero wtedy włącz harmonogram.
Aby zapewnić niezawodne działanie, zapisuj status każdego zapytania, ogranicz liczbę ponowień po błędach tymczasowych i oznacz niekompletne zbieranie danych, jeśli jedno z zapytań zakończy się niepowodzeniem. Nie umieszczaj klucza w komunikatach o błędach. Warto również rozdzielać pliki według daty i nazwy zapytania, by ponowne uruchomienie nie nadpisało poprzedniego zrzutu.
Dobierz częstotliwość do zadania i liczby zapytań. Do codziennego przeglądu wystarczy jedno uruchomienie dziennie; częstsze zbieranie ma sens, gdy zespół chce śledzić zmiany w ciągu dnia. Zacznij od krótkiej listy fraz, sprawdź przydatność zwracanych wyników, a następnie rozszerz zakres zbierania w granicach warunków dostępu i zasad korzystania z danych.
Użyj AI do grupowania tematycznego
Po potwierdzeniu schematu odpowiedzi wybrane pola tekstowe można przekazać modelowi w celu pogrupowania opisów według z góry określonych tematów lub przygotowania krótkiego szkicu zestawienia. Obok klasyfikacji zachowaj identyfikator publikacji, wyszukiwaną frazę i fragment tekstu, na którym oparto kategorię. Dzięki temu analityk będzie mógł przejść od wyniku modelu do oryginalnego wpisu.
Różnice liczbowe, sortowanie i usuwanie duplikatów obliczaj zwykłym kodem. Model przydaje się do przetwarzania tekstu i formułowania raportu, natomiast wartości liczników i znaczniki czasu pobieraj z zapisanych odpowiedzi. Rozdzielenie tych operacji ułatwia zrozumienie pochodzenia każdego wniosku.
Ręcznie sprawdzaj część automatycznych kategorii i zapisuj poprawki jako przykłady testowe. Jeśli różne typy publikacji regularnie trafiają do tej samej grupy, doprecyzuj definicje kategorii i powtórz sprawdzanie. Taki proces pomaga oceniać jakość klasyfikacji na danych odpowiadających twojemu zadaniu.
Podsumowanie: powtarzalne archiwum i weryfikowalne zestawienie
Po uruchomieniu udokumentowanego zapytania z parametrem keyword zespół zyskuje archiwum pokazujące, jakie frazy wyszukiwano, kiedy to robiono i jakie dane API zwróciło dla każdej z nich. Na tej podstawie można stworzyć tabelę wyników, porównać potwierdzone pola między zrzutami i przygotować listę znalezionych publikacji do ręcznej analizy.
Zacznij od jednego testowego zapytania, a następnie skonfiguruj listę fraz i harmonogram. Opis TikTok Scraper API zawiera adres bazowy i mapę endpointów; parametry /searchVideo i format odpowiedzi opisano w specyfikacji API. Archiwizowanie zweryfikowanych odpowiedzi tworzy podstawę powtarzalnej analityki dla ustalonych fraz wyszukiwania.