Michael JohnsonBir kampanya başlatıldıktan sonra ekip, seçilen sözcüklerle yapılan aramalarda hangi herkese açık videoların göründüğünü incelemek isteyebilir. Elle arama yapmak ve sonuçları birkaç gün sonra karşılaştırmak zordur. Küçük bir toplayıcı, aynı sorguları bir programa göre çalıştırıp yanıtları tarih ve arama ifadesiyle arşivleyebilir; böylece analist kayıtları inceleyip kendi özetini hazırlayabilir.
Bu kılavuzda, sabit ifadelerle yapılan aramaların sonuçlarını kaydetmeye yönelik Python tabanlı bir arşiv hattı gösteriliyor. Tek tek hashtag’leri veya hesapları izlemenin aksine, burada karşılaştırmanın temel koşulu aynı arama ifadelerini tekrarlamak ve her yanıtın ayrı bir anlık görüntüsünü saklamaktır. jsonscraper TikTok Scraper API sayfasında temel adres ve GET /searchVideo uç noktası belirtiliyor; bu uç noktanın belgelerinde arama ifadesinin zorunlu keyword parametresiyle gönderildiği açıklanıyor.
Görev ve ölçüm sınırları
Bir pazarlamacının her gün birkaç sabit ifadeyle arama sonuçlarını toplamak istediğini düşünelim: ürün adı, kategori ve müşteri sorununun ifadesi. Sistem her sorgu için toplama zamanını ve API yanıtını kaydeder. Örnek yanıtı kontrol ettikten sonra, videonun tanımlayıcısı veya varsa herkese açık sayaçlar gibi JSON’da gerçekten bulunan alanları normalleştirebilirsiniz.
Arşiv şu belirli soruyu yanıtlar: Kaydedilen ifadeyle yapılan aramada bu çalıştırma sırasında hangi kayıtlar döndürüldü? Yanıtta metrikler bulunuyorsa yinelenen gözlemler, farklı zamanlarda kaydedilen değerler arasındaki farkı gösterebilir. Bu fark, gözlemlenen anlık görüntülere ve aralarındaki süreye aittir; karşılaştırma için her iki toplama zamanını ve aynı alanı kaydedin.
Sorguyu yanıtla birlikte saklayın. Sonuçların kapsamı, belirli bir arama ifadesine ve toplama zamanına bağlıdır. Bu nedenle arşiv, TikTok’taki tüm içeriğin eksiksiz bir görünümü değil, seçilen sorguların sonuçlarını izlemek için kullanışlıdır. Tanımlayıcılar, ham yanıtlar ve zaman damgaları, sonraki tablodaki her satırın kaynağını doğrulamaya yardımcı olur.
Uç noktayı ve parametrelerini kontrol edin
TikTok API uç noktaları listesinde temel adres https://tiktok.evelode.com ve GET /searchVideo belirtiliyor. Güncel API belirtimi, keyword parametresini arama için zorunlu olarak tanımlıyor; isteğe bağlı parametreler arasında cursor, count, cache_timeout, date_posted, sort_by ve region yer alıyor. Kimlik doğrulama için license_key gönderilir. Uç nokta bilgileri Python SDK belgelerinde de bulunabilir.
count ve date_posted parametreleri yanıt boyutunu ve zaman filtresini belirlemeye yardımcı olur; sort_by belgelenen most-liked, relevance veya date-posted değerlerini kabul eder. Sayfalama kullanıyorsanız önceki yanıttan aldığınız cursor değerini opak bir değer olarak iletin; kendiniz hesaplamayın. Günlük arşivde karşılaştırılabilirliği sağlamak için istek parametrelerini ve kendi kodunuzun sürümünü verilerle birlikte saklayın.
Aşağıdaki örnekte deneme çalıştırması için küçük bir count değeri ve sabit US bölgesi kullanılıyor. Günlük toplamaya geçmeden önce tek bir isteği, HTTP durumunu ve JSON yapısını kontrol edin. Yanıt şeması bulunan videoları tiktok.aweme_list içinde veya video nesnesinin aweme_info altında yer aldığı tiktok.search_item_list içinde barındırabilir; kod gözlemlenmiş her iki biçimi de destekler.
Projeyi hazırlayın
Sanal ortam oluşturup requests paketini yükleyin:
python -m venv .venv
source .venv/bin/activate
pip install requestsPowerShell’de ortamı .venv\Scripts\Activate.ps1 komutuyla etkinleştirin. Anahtarı ve arama ifadeleri listesini ortam değişkenleriyle tanımlayın. TikTok API için belgelenmiş JSONSCRAPER_TIKTOK_LICENSE_KEY değişken adını kullanın:
export JSONSCRAPER_TIKTOK_LICENSE_KEY="anahtarınız"
export TIKTOK_QUERIES="ürün adı,ürün kategorisi,müşteri sorunu"Anlık görüntüleri toplayıp kaydedin
Örnek, her ifade için belgelenmiş uç noktaya bir istek gönderir; ardından ham JSON’u, toplama zamanını ve kullanılan parametreleri kaydeder. Dosya adında tarih ve arama ifadesi bulunur. Anahtar ortamda tutulur ve arşive eklenmez.
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, ok dışında bir durum döndürdü")
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"Sorgu yanıtı kaydedildi: {query}")
time.sleep(1)
print(f"Kaydedilen yanıt sayısı: {len(QUERIES)}")Bu temel toplayıcı, her ifade için count=10 ile tek bir istek gönderir. Daha kapsamlı toplama için cursor ile sayfalama ekleyin: API sonraki sonuçların bulunduğunu belirttiği sürece yanıttaki imleç değerini kullanarak yeni istekler gönderin ve her yanıtı ayrı kaydedin. İmleç ve sonuç sayısı belirli bir tarama geçişini tanımlar; kaydedilen JSON, her istekte tam olarak ne döndüğünü sonradan kontrol etmenizi sağlar.
Örnek, önce dış status değerini kontrol eder, ardından tiktok nesnesini okur. aweme_list öğelerini ve bu biçim mevcutsa search_item_list[].aweme_info öğelerini toplar. Video kaydı olası alanları arasında tanımlayıcı, açıklama, yazar, bağlantı ve istatistikler bulunur; bazı alanlar eksik olabilir. Bu nedenle yanıtın tamamını saklayın ve her alanın varlığını normalleştirme sırasında kontrol edin.
Bir saniyelik aralık, betiğin kendi istekleri arasındaki beklemedir; hizmetin hız sınırları hakkında bir iddia değildir. Sıklığı ve yeniden denemeleri erişim koşullarına ve belgelere göre ayarlayın. cache_timeout parametresi arama için belgelenmiştir; saniye cinsinden önbellek süresi belirlemenizi sağlar ve belirtime göre 0 değeri önbelleğe almayı devre dışı bırakır. Bu davranış senaryonuza uygunsa parametreyi isteğe ekleyin.
Gerçek yanıta göre normalleştirme ekleyin
İlk çalıştırmadan sonra kaydedilen dosyayı açıp payload yapısını inceleyin. Örnekteki extract_videos işlevi, yanıt biçimlerinde belgelenmiş iki konumdaki öğeleri toplar. Analiz için gereken alanların tam anahtarlarını bulun. Belirli bir kayıtta bir alan yoksa, varsayılan bir sayı atamak yerine alanı eksik değer olarak kaydedin.
Sonraki işlemler için bulunan her nesneyi bir satıra dönüştürüp collected_at ve query değerlerini eklemek kullanışlıdır. Doğrulanmış alanları CSV’ye veya veritabanına kaydedebilir, ham JSON’u ise arşivde tutabilirsiniz. Bu ikili yaklaşım kullanışlı tablolar oluşturmayı sağlarken her kaydın kaynağını doğrulamaya da imkân verir.
API bir video tanımlayıcısı döndürüyorsa, farklı çalıştırmalardaki aynı videoya ait gözlemleri ilişkilendirmek için bu tanımlayıcıyı kullanın. Geçmiş verilerin üzerine yazmayın; her gözlemi ayrı saklayın. Kararlı bir tanımlayıcı yoksa önce kayıtları eşleştirmek için hangi özelliklerin kullanılabileceğini kontrol edin ve açıklama metninin eşleşmesini kesin kanıt saymayın.
Anlık görüntüleri karşılaştırıp rapor hazırlayın
Normalleştirmeden sonra kayıtları doğrulanmış tanımlayıcıya göre gruplayın ve toplama zamanına göre sıralayın. Sayaç alanlarındaki ardışık iki değerin farkı basit kodla hesaplanabilir. Örneğin 12.400’den 18.900’e geçiş, bu anlık görüntüler arasında sayaç değerinin 6.500 arttığı anlamına gelir. Okuyucunun hesabı doğrulayabilmesi için raporda gözlem tarihlerini ve kaynak alanı belirtin.
Sonuç tablosu için kullanışlı bir yapı; arama ifadesini, yayın tanımlayıcısını, toplama zamanını ve yanıttan seçilen alanları içerir. Özeti sorgulara göre gruplayıp doğrulanmış bir sayaca göre sıralayabilirsiniz. Böylece ekip, daha sonra incelemek üzere döndürülen kayıtların doğrulanabilir bir listesini elde eder; tabloyu veya mesajı gerçek şemayı inceledikten sonra ayrı bir adım olarak oluşturun.
Önce JSON dosyalarını yerel olarak saklayın. Toplama düzenli hâle geldiğinde normalleştirilmiş satırları PostgreSQL’e veya bir analitik veri ambarına, ham yanıtları ise adında tarih ve sorgu bulunan bir nesne depolama alanına aktarın. Ayrıştırıcıyı geliştirirken kaynak dosyaları saklamak özellikle yararlıdır: geçmiş veriler üzerinde API’ye yeniden istek göndermeden tekrar çalıştırabilirsiniz.
Toplamayı programa bağlayın
Günlük arşiv için betiği cron veya ortamınızda bulunan başka bir zamanlayıcıyla çalıştırın. Örneğin bir görev, Python dosyasını günde bir kez çalıştırıp anahtarı ve arama ifadelerini ortam değişkenleriyle iletebilir. Düzenli kullanıma geçmeden önce tek bir isteği, ardından listenin tamamını kontrol edin; zamanlamayı ancak bundan sonra devreye alın.
Güvenilir çalıştırma için her isteğin durumunu kaydedin, geçici hatalarda yeniden deneme sayısını sınırlayın ve bir ifade başarısız olursa toplamanın eksik olduğunu işaretleyin. Hata mesajlarına anahtarı eklemeyin. Ayrıca dosyaları tarih ve sorgu adına göre ayırmak, yeniden çalıştırmanın önceki bir anlık görüntünün üzerine yazmasını önlemeye yardımcı olur.
Sıklığı göreve ve istek hacmine göre seçin. Günlük bir genel bakış için günde bir çalıştırma yeterlidir; gün içindeki değişiklikler ekip için önemliyse daha sık toplama anlamlı olabilir. Küçük bir ifade listesiyle başlayın, döndürülen sonuçların yararını kontrol edin ve erişim koşulları ile veri kullanım kuralları içinde kalarak kapsamı genişletin.
Tematik gruplandırma için yapay zekâdan yararlanın
Yanıt şeması doğrulandıktan sonra seçilen metin alanlarını, açıklamaları önceden tanımlanmış temalara göre gruplandırması veya kısa bir özet taslağı hazırlaması için bir modele aktarabilirsiniz. Kategorinin dayandığı metin parçasını, yayın tanımlayıcısını ve arama ifadesini sınıflandırma sonucuyla birlikte saklayın. Böylece analist modelin çıktısından kaynak kayda ulaşabilir.
Sayısal farkları, sıralamayı ve yinelenen kayıtların ayıklanmasını normal kodla hesaplayın. Model, metin işleme ve rapor ifadeleri hazırlama için uygundur; sayaçları ve zaman damgalarını ise kaydedilmiş yanıtlardan alın. Bu işlemleri birbirinden ayırmak, her sonucun kaynağını anlaşılır kılar.
Otomatik kategorilerin bir bölümünü elle kontrol edin ve düzeltmeleri test örnekleri olarak saklayın. Farklı yayın türleri düzenli olarak aynı gruba düşüyorsa kategori tanımlarını netleştirip kontrolü tekrarlayın. Bu süreç, sınıflandırma kalitesini görevinize ait veriler üzerinde değerlendirmenize yardımcı olur.
Sonuç: tekrarlanabilir arşiv ve doğrulanabilir özet
keyword parametresini kullanan belgelenmiş isteği çalıştırdıktan sonra ekipte şu bilgileri içeren bir arşiv oluşur: hangi ifadelerin ne zaman arandığı ve API’nin her biri için hangi verileri döndürdüğü. Bu arşiv üzerinden sonuç tablosu oluşturabilir, doğrulanmış alanları anlık görüntüler arasında karşılaştırabilir ve elle analiz için bulunan yayınların listesini hazırlayabilirsiniz.
Tek bir deneme sorgusuyla başlayın, ardından ifade listesini ve zamanlamayı ayarlayın. TikTok Scraper API açıklamasında temel adres ve uç noktalar listeleniyor; /searchVideo parametreleri ve yanıt biçimi ise API belirtiminde açıklanıyor. Doğrulanmış yanıtları arşivlemek, sabit arama ifadeleriyle tekrarlanabilir analiz için temel oluşturur.