Michael JohnsonZespół marketingowy zauważa, że na TikToku pojawiają się filmy o nowym produkcie, ale ręczne sprawdzanie kilku hashtagów każdego dnia jest uciążliwe. Aby porównywać publikacje i widoczne wskaźniki w czasie, potrzebny jest powtarzalny proces zbierania danych z oznaczeniem czasu, archiwum oryginalnych odpowiedzi i kontrolą zmian.
Do takiego prototypu nadaje się TikTok Scraper API od jsonscraper: na stronie produktu wymieniono endpointy dotyczące hashtagów, użytkowników, filmów i wyszukiwania. Pierwszym krokiem jest sprawdzenie potrzebnego endpointu i formatu odpowiedzi w Postmanie, a następnie przeniesienie zweryfikowanej konfiguracji do Pythona. Dzięki temu można zbudować powtarzalny proces, pobierając tylko te pola, które rzeczywiście występują w odpowiedzi.
Cel: śledzić zmiany, a nie pojedynczy popularny film
Pojedyncza publikacja z dużą liczbą wyświetleń może przyciągnąć uwagę, ale przy planowaniu kampanii bardziej przydatna jest wiedza o tym, ile nowych filmów pojawia się na dany temat i jak zmieniają się publiczne wskaźniki już znalezionych publikacji. Na przykład sklep internetowy ze sprzętem sportowym może chcieć ocenić napływ filmów o konkretnym rodzaju treningu, zanim przygotuje powiązane z nim materiały reklamowe.
Ręczne sprawdzanie utrudnia porównania: zestaw wyników się zmienia, wskaźniki rosną, a pracownicy mogą zapisywać je w różnych formatach. Jeśli każdy odczyt zostanie zapisany wraz z czasem zebrania i oryginalnym JSON-em, zespół uzyska historię własnych obserwacji i będzie mógł ponownie przetworzyć dane po zmianie schematu analitycznego.
Automatyzacja składa się z kilku kroków: weryfikacji endpointu i parametrów, cyklicznego pobierania danych, zapisania odpowiedzi, sprawdzenia jej struktury, a następnie wyodrębnienia potrzebnych pól. Uzyskaną tabelę można wykorzystać do tworzenia wykresów, klasyfikacji tematycznej lub raportu.
Co potwierdza dokumentacja API
Na stronie TikTok Scraper API podano adres bazowy https://tiktok.evelode.com oraz wymieniono endpointy z grupy Hashtag: GET /getHashtagInfo, GET /getHashtagFeed i GET /getHashtagFeedByID. Strona pokazuje też przykładowe zapytanie do innego endpointu z parametrem license_key i opisuje konfigurację klucza w kolekcji Postmana.
W przypadku GET /getHashtagFeed oficjalna specyfikacja endpointów wskazuje wymagany parametr query (adres URL hashtagu lub nazwę taga), a także opcjonalne cursor, count, region i cache_timeout. W odpowiedzi z kanałem oczekiwana jest tablica tiktok.aweme_list; wśród wymienionych pól elementu znajdują się aweme_id, desc, create_time, share_url, dane autora i statistics. Niektóre pola mogą być nieobecne, dlatego przed przetwarzaniem należy sprawdzić rzeczywisty JSON.
W kolekcji jsonscraper w Postmanie można wygodnie wykonać próbne zapytanie, sprawdzić rzeczywistą odpowiedź i uzyskać przykład do późniejszego testowania kodu. Do autoryzacji przekazuje się license_key; klucz należy przechowywać w zmiennej środowiskowej i nie umieszczać go w logach.
Najpierw sprawdź zapytanie w Postmanie
Zacznij od jednego testowego hashtagu. Wybierz w kolekcji endpoint kanału hashtagów, ustaw license_key w sposób wskazany w dokumentacji i przekaż nazwę taga w parametrze query. W razie potrzeby dodaj count i kod kraju w region. Wykonaj zapytanie i sprawdź status HTTP, pole najwyższego poziomu status oraz zawartość tiktok.aweme_list.
Zapisz poprawną odpowiedź jako testowy plik JSON. Sprawdź, czy zawiera identyfikator publikacji, opis, czas publikacji, link i statystyki. Dodaj pole do schematu analitycznego dopiero po upewnieniu się, że jest zwracane w odpowiednim typie.
Klucz API przechowuj w zmiennej środowiskowej, a nie w pliku źródłowym. Jeśli klucz jest przekazywany w adresie URL, maskuj go podczas logowania zapytań, aby pełny adres nie trafiał do logów.
Klient w Pythonie do wysyłania zapytań i archiwizacji
Endpoint i nazwy parametrów poniżej są zgodne z opublikowaną specyfikacją: dla hashtagu używany jest parametr query, a autoryzacja odbywa się przez license_key. Przykład działa z Pythonem 3.8+ i zapisuje oryginalną odpowiedź wraz z metadanymi uruchomienia.
import json
import os
from datetime import datetime, timezone
from pathlib import Path
import requests
BASE_URL = "https://tiktok.evelode.com"
API_KEY = os.environ["JSONSCRAPER_TIKTOK_LICENSE_KEY"]
def fetch_hashtag_feed(hashtag: str) -> dict:
params = {
"license_key": API_KEY,
"query": hashtag,
"count": 20,
}
response = requests.get(
f"{BASE_URL}/getHashtagFeed",
params=params,
timeout=45,
)
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 archive_response(hashtag: str, payload: dict) -> Path:
collected_at = datetime.now(timezone.utc).isoformat()
safe_tag = hashtag.lstrip("#").replace("/", "_")
output_dir = Path("data/raw") / safe_tag
output_dir.mkdir(parents=True, exist_ok=True)
filename = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ.json")
file_path = output_dir / filename
file_path.write_text(
json.dumps(
{
"hashtag": hashtag,
"collected_at": collected_at,
"response": payload,
},
ensure_ascii=False,
indent=2,
),
encoding="utf-8",
)
return file_path
if __name__ == "__main__":
tag = "#przykladowytemat"
payload = fetch_hashtag_feed(tag)
saved_path = archive_response(tag, payload)
print(f"Archiwum zapisano: {saved_path}")
Przed uruchomieniem ustaw zmienną środowiskową JSONSCRAPER_TIKTOK_LICENSE_KEY. Zapytanie używa potwierdzonego parametru query i ogranicza liczbę pobieranych elementów przez count. W odpowiedzi sprawdzane są status HTTP i status JSON; archiwum przechowuje rzeczywiste dane do późniejszego przetwarzania. Przetestuj działanie na jednym hashtagu, zanim dodasz harmonogram i analitykę.
Jak dodać normalizację bez kruchych założeń
Dokumentacja wskazuje, że odpowiedź kanału zawiera tablicę tiktok.aweme_list. Przed przekształceniem sprawdź, czy tiktok jest obiektem, a aweme_list listą. Z każdego elementu pobieraj wyłącznie potwierdzone pola, na przykład aweme_id, desc, create_time, share_url i wartości z statistics, jeśli są dostępne.
Wewnętrzna tabela może zawierać hashtag zapytania, czas zebrania, identyfikator filmu i wybrane wskaźniki. W przypadku opcjonalnego lub nieobecnego wskaźnika zapisuj pustą wartość: brak metryki różni się od zmierzonego zera. Oryginalne odpowiedzi przechowuj osobno, aby ponownie zbudować tabelę bez wysyłania nowego zapytania.
Jeśli format odpowiedzi się zmieni, kontrola typów powinna przerwać nieprawidłowe przetwarzanie i wygenerować komunikat diagnostyczny. Zachowaj testowy JSON obok testu parsera: pomoże sprawdzić, czy nowa wersja kodu nadal obsługuje znany schemat.
Metryki oparte na powtarzanych obserwacjach
Jeśli odpowiedź zawiera liczniki, zapisuj każdą obserwację wraz ze znacznikiem czasu. Dla jednej publikacji porównaj wartości z dwóch uruchomień i oblicz zaobserwowaną zmianę w danym przedziale. Do porównania użyj wskazanego w specyfikacji aweme_id i sprawdź jego obecność w każdym elemencie.
Liczbę publikacji wykrytych po raz pierwszy danego dnia można obliczać na podstawie wyników własnych uruchomień. Ta metryka opisuje strumień zwrócony przez konkretne zapytania przy określonych parametrach i harmonogramie. Pozwala porównywać własne odczyty, o ile metoda zbierania danych pozostaje niezmienna.
Minimalny raport może przedstawiać dzienną liczbę nowo wykrytych publikacji, rozkład dostępnych liczników i zmiany wartości dla filmów znalezionych ponownie. Dodaj czas zapytania i nazwę pliku źródłowego, aby analityk mógł sprawdzić pochodzenie każdego rekordu.
Harmonogram i obsługa błędów
Gdy zapytanie i przetwarzanie są już sprawdzone, uruchamiaj skrypt według harmonogramu — na przykład przez cron, GitHub Actions lub orkiestrator danych. Listę hashtagów umieść w osobnej konfiguracji, aby dodawać i usuwać tematy bez zmieniania logiki klienta.
W przypadku automatycznego uruchamiania ustaw limit czasu, ograniczoną liczbę ponowień przy przejściowych błędach sieci i rejestrowanie statusu HTTP oraz czasu trwania zapytania. Nie zapisuj klucza w logach. W razie błędu przetwarzania zapisuj bezpieczne informacje diagnostyczne i powiadamiaj osobę odpowiedzialną.
Specyfikacja obsługuje stronicowanie za pomocą parametru cursor dla kanału hashtagów. Jeśli jest potrzebne, zapisuj kursor z odpowiedzi i przekazuj go w kolejnym zapytaniu bez przekształcania; przetwarzaj tylko zwrócone wyniki i kontroluj has_more, jeśli to pole występuje. Jeśli zapytania dotyczące kilku hashtagów zwracają tę samą publikację, wybierz klucz deduplikacji zgodnie z celem: uwzględniaj publikację osobno dla każdego hashtagu albo licz tylko unikalne filmy.
Klasyfikacja i automatyzacja raportów
Po uzyskaniu zweryfikowanych rekordów można dodać klasyfikację opisów filmów według zadanych tematów: pole desc jest wymienione w schemacie elementu. Model może grupować publikacje według formatu, na przykład instrukcje, recenzje lub relacje z własnych doświadczeń. Zachowuj oryginalny tekst, etykietę, wersję instrukcji i wynik, a wątpliwe przypadki przekazuj człowiekowi do weryfikacji.
Wskaźniki liczbowe obliczaj zwykłym kodem, aby kolejne uruchomienia zapewniały powtarzalne wyniki arytmetyczne. Klasyfikator przydaje się do przetwarzania tekstu; raport końcowy powinien łączyć wnioski z konkretnymi rekordami i datami obserwacji.
W scenariuszu no-code te same etapy można połączyć w narzędziu automatyzującym: harmonogram, zapytanie HTTP oparte na zweryfikowanej konfiguracji, kontrola odpowiedzi, zapis JSON, przekształcenie potwierdzonych pól i powiadomienie o błędzie. Najpierw sprawdź kontrakt w Postmanie, a następnie przenieś go do Pythona, n8n lub Make.
Oczekiwany rezultat i następny krok
Po konfiguracji zespół będzie dysponować archiwum odpowiedzi API i tabelą obserwacji dla wybranych hashtagów. Pomogą one znajdować nowe publikacje, porównywać dostępne wskaźniki w czasie i wybierać materiały do pogłębionej analizy. Aby wyniki były porównywalne, stosuj jednolity harmonogram, parametry zapytań i zasady normalizacji.
Zacznij od jednego endpointu i jednej rzeczywistej odpowiedzi: wykonaj zapytanie /getHashtagFeed z parametrem query, zapisz JSON, a następnie dodaj przetwarzanie pól i harmonogram. Strona TikTok Scraper API pokazuje adres bazowy i mapę endpointów, a specyfikacja endpointów zawiera nazwy parametrów potrzebne do implementacji klienta.