Michael JohnsonBir uygulama veya yeni özellik kullanıma sunulduktan sonra geri bildirim kısa videolara hızla dağılır. Pazarlamacı birkaç videoyu elle bulup bağlantıları sohbete gönderir; ancak analist daha sonra hangi gönderilerin hesaba katıldığını ve görüntülenmelerin nasıl değiştiğini anlayamayabilir. Pratik bir çözüm, birkaç tutarlı sorgunun sonuçlarını düzenli olarak toplamak, ham yanıtları saklamak ve raporu doğrulanmış alanlara göre oluşturmaktır.
Bu rehberde, belirli bir senaryo için böyle bir toplama düzeni kuracağız: Bir ekip yeni bir özellik yayınladı ve açıklamasında ürün adının, önemli bir özelliğin veya yaygın bir kullanıcı sorununun geçtiği herkese açık TikTok videolarını haftalık olarak izlemek istiyor. Bu, arama sonuçlarından oluşan bir örneklemin izlenmesidir: API, sorgu ve parametrelere göre sonuç döndürür; lansmanla ilgili tüm gönderilerin eksiksiz bir listesini garanti etmez.
Önce ekibin hangi sinyale ihtiyaç duyduğunu belirleyin
Yüksek görüntülenme sayısı tek başına bundan sonra ne yapılması gerektiğini açıklamakta yetersizdir. Ekip için hangi soruların tekrarlandığını, insanların hangi kullanım senaryolarını gösterdiğini ve hangi videoların kayda değer düzeyde herkese açık etkileşim aldığını bilmek daha yararlıdır. Bu nedenle önce birkaç arama ifadesi belirleyin ve rapora hangi alanların gireceğine karar verin.
Örneğin, bir gönderi planlama aracını kullanıma sunarken “ürün adı”, “içerik planlayıcı” ve “TikTok nasıl planlanır” sorgularını deneyebilirsiniz. İfadeler, insanların aynı konuyu farklı biçimlerde anlatabileceğini yansıtmalıdır. Sonraki veri aktarımlarını aynı ayarlarla karşılaştırabilmek için bu ifadeleri izleme başlangıç tarihi ve bölgeyle birlikte kaydedin.
En temel tablo; toplama zamanını, arama ifadesini, video kimliğini, bağlantıyı, açıklamayı, içerik üreticisinin adını ve kimliğini, ayrıca mevcut görüntülenme, beğeni ve yorum değerlerini içerebilir. TikTok Scraper API belgelerinde arama sonuçları için aweme_id, desc, share_url, içerik üreticisi bilgileri ve bazı istatistik alanları listelenir. Bazı ölçümler eksik olabileceğinden, her nesnedeki alanları ayrı ayrı kontrol edin.
Belgelenmiş arama uç noktasını kullanın
Video aramak için https://tiktok.evelode.com temel adresindeki GET /searchVideo uç noktasını kullanın. Belgelerde zorunlu keyword parametresinin yanı sıra isteğe bağlı count, cursor, date_posted, sort_by, region ve cache_timeout parametreleri listelenir. Tarih filtresinin izin verilen değerleri arasında this-week, sıralama seçenekleri arasında ise relevance, most-liked ve date-posted bulunur. Parametrelerin kullanımını ve adlarını TikTok API uç noktaları başvuru belgesinden kontrol edin.
Lisans anahtarı, license_key sorgu parametresi olarak gönderilir. Üretim betiğinde anahtarı JSONSCRAPER_TIKTOK_LICENSE_KEY ortam değişkeninden okuyun; gizli bilgiyi kaynak koda yazmayın veya günlüklere eklemeyin. Bu örnek Python 3.8+ içindir ve requests paketini kullanır:
import os
import requests
BASE_URL = "https://tiktok.evelode.com"
API_KEY = os.environ["JSONSCRAPER_TIKTOK_LICENSE_KEY"]
def search_videos(keyword, cursor=None):
params = {
"license_key": API_KEY,
"keyword": keyword,
"count": 20,
"date_posted": "this-week",
"sort_by": "date-posted",
"region": "US",
}
if cursor is not None:
params["cursor"] = cursor
response = requests.get(
f"{BASE_URL}/searchVideo",
params=params,
timeout=30,
)
response.raise_for_status()
payload = response.json()
if payload.get("status") != "ok":
raise RuntimeError("TikTok API, ok dışında bir durum döndürdü")
return payload["tiktok"]
result = search_videos("content planning app")
print("Bulunan nesneler:", len(result.get("aweme_list", [])))Betik HTTP hatalarını ve yanıtın üst düzey durumunu kontrol eder. HTTP yanıtının başarılı olması, aramada mutlaka video bulunduğu anlamına gelmez: sonuç kümesi boşsa liste de boş olabilir. İlk çalıştırmada yanıtın tamamını güvenli bir depolama alanına kaydedip gerçek nesneleri normalleştirilmiş alan tablosuyla karşılaştırmak yararlı olur.
Arama yanıtının iki biçimini de işleyin
Arama sonuçlarının yapısında önemli bir ayrıntı vardır. Videolar doğrudan tiktok.aweme_list içinde bulunabileceği gibi tiktok.search_item_list[].aweme_info içindeki nesnelerde de yer alabilir. Yalnızca ilk listeyi okuyan bir işleyici, ikinci biçimde bulunan sonuçları atlayabilir.
Her iki yapıyı da destekleyen ve iç içe video nesnesi bulunmayan öğeleri sorun çıkarmadan atlayan küçük bir normalleştirici ekleyin:
def extract_awemes(tiktok):
items = list(tiktok.get("aweme_list") or [])
for item in tiktok.get("search_item_list") or []:
aweme = item.get("aweme_info")
if aweme:
items.append(aweme)
return items
def normalize(aweme, keyword, collected_at):
author = aweme.get("author") or {}
stats = aweme.get("statistics") or {}
return {
"collected_at": collected_at,
"keyword": keyword,
"video_id": aweme.get("aweme_id"),
"posted_at": aweme.get("create_time"),
"description": aweme.get("desc"),
"share_url": aweme.get("share_url"),
"author_id": author.get("uid"),
"author_name": author.get("nickname"),
"views": stats.get("play_count"),
"likes": stats.get("digg_count"),
"comments": stats.get("comment_count"),
"shares": stats.get("share_count"),
}Eksik değerler None olarak kalır. Bunları sıfırla değiştirmeyin: sıfır, ölçülmüş bir değeri belirtirken None, alanın yanıtta bulunmadığını korur. Bu ayrım ortalamaları, oranları ve ekip için yapılacak her türlü çıkarımı etkiler.
Yalnızca son görüntüyü değil, geçmişi de saklayın
Değişimleri görebilmek için gözlem kayıtlarını ayrı ayrı saklayın. Video kimliği gönderileri yinelenen kayıtlara karşı ayıklamak için uygundur, ancak geçmişi silmek için kullanılmamalıdır: bir sonraki toplamada aynı videonun yeniden görülmesi yeni bir gözlem noktası oluşturur. Örneğin gözlem tablosunun benzersiz anahtarı video_id ve collected_at alanlarından oluşturulabilir; bağlantı ve açıklama da kolay kontrol için kayda eklenebilir.
SQLite’ta basit bir şema, prototip oluşturmak için işinize yarayabilir:
import sqlite3
conn = sqlite3.connect("tiktok_observations.sqlite3")
conn.execute("""
CREATE TABLE IF NOT EXISTS observations (
video_id TEXT NOT NULL,
collected_at TEXT NOT NULL,
keyword TEXT NOT NULL,
posted_at INTEGER,
description TEXT,
share_url TEXT,
author_id TEXT,
author_name TEXT,
views INTEGER,
likes INTEGER,
comments INTEGER,
shares INTEGER,
PRIMARY KEY (video_id, collected_at, keyword)
)
""")
conn.commit()Uygulamada toplama zamanını UTC olarak normalleştirin, ham JSON’u ayrı kaydedin ve bir şema sürümü sütunu ekleyin. Yeni nesnelerin yapısı alışılmış olandan farklı olduğunda, ham yanıt dönüşümü yeniden denetlemenize yardımcı olur. Birden fazla sorguda bulunan gönderiler için eşleşen anahtar kelimeleri ayrı bir ilişkili tabloda saklayın veya rapor oluştururken bir araya getirin.
Sayfalama: yalnızca yanıttaki imleçle devam edin
cursor parametresi aramaya devam etmek için kullanılır. Değeri önceki yanıttan alınır ve değiştirilmeden geri gönderilir. has_more artık devam edilecek sonuç olmadığını belirttiğinde veya tanımlı sınıra ulaşıldığında işlem sonlandırılır. İmleci opak bir değer olarak kabul edin: kendiniz hesaplamayın ve sayfa sayacıyla değiştirmeyin.
def collect_pages(keyword, max_pages=3):
cursor = None
collected = []
for _ in range(max_pages):
page = search_videos(keyword, cursor)
collected.extend(extract_awemes(page))
if not page.get("has_more"):
break
cursor = page.get("cursor")
if cursor is None:
break
return collectedSayfa sayısını sınırlamak, düzenli görevin istek hacmini öngörülebilir kılar. Sonuç kümesine ilişkin bağlam sağlayabilmek için çalıştırma günlüğüne sayfa sayısını ve has_more değerini yazın. Sayfalama kullanılsa bile sonuç yalnızca alınan API yanıtlarını ve tanımlı toplama sınırını yansıtır; platformdaki tüm gönderilerin tahmini değildir.
Tekrarlanabilir bir rapor oluşturun
Ekibin daha sık sinyale ihtiyacı varsa toplama işlemini haftada bir veya daha sık planlayın. Her çalıştırmada sorgu listesini, parametreleri, zamanı, alınan nesne sayısını ve benzersiz kimlik sayısını kaydedin. O çalıştırmada ilk kez görülen gönderileri, daha önce karşılaşılanlardan ayrı sayın.
Raporda şu dört basit görünüm faydalı olur:
- Yeni videolar: bulunan arama ifadesiyle birlikte bağlantılar, açıklamalar ve yayın tarihleri.
- Tekrarlanan konular: açıklamaların “kurulum hatası”, “özellik isteği” ve “kullanım senaryosu incelemesi” gibi elle belirlenmiş kategorilere göre gruplandırılması.
- Herkese açık etkileşim: mevcut görüntülenme, beğeni, yorum ve paylaşım değerlerinin gözlem zamanıyla birlikte gösterilmesi.
- İncelenmesi gereken sinyaller: yeni ifadeler, sık sorulan sorular veya bir ekip üyesinin incelemesi gereken videolar.
Yanıttaki değerlerin anlamını ve güncelliğini doğrulamadan iki görüntü arasındaki farka “yeni beğeniler” demeyin. Doğru ifadeler, “en son alınan yanıttaki ölçüm değeri” ve “kaydedilmiş görüntüler arasındaki fark”tır. Böylece ekip, neyin hesaplandığını görür ve karar vermeden önce asıl gönderiyi açabilir.
Yapay zekâyı toplamanın yerine değil, sınıflandırma aşamasına ekleyin
Normalleştirme sonrasında video açıklamalarını, önceden tanımlanmış kategorilere göre sınıflandırması için bir modele gönderebilirsiniz. Yalnızca gerekli metin alanlarını iletin ve yapılandırılmış bir sonuç isteyin: kategori, kısa gerekçe, güven düzeyi ve etiketin dayandığı açıklama bölümü. Analistin tartışmalı durumları kontrol edebilmesi için asıl gönderiyi etiketin yanında saklayın.
İş akışı basit kalır: bir zamanlayıcı toplama işlemini başlatır; Python yanıtı doğrular ve JSON’u kaydeder; ayrı bir görev yeni kayıtları normalleştirir; sınıflandırıcı yalnızca yeni açıklamaları işler; rapor veritabanından oluşturulup ekibin seçtiği kanala gönderilir. TikTok Scraper API arama verilerini sağlar; sınıflandırma ve raporun iletilmesi ise Python, n8n veya Make ile uygulayabileceğiniz entegrasyon mantığınızdır.
Gürültüyü azaltmak için modele veri göndermeden önce bir kategori sözlüğü belirleyin ve elle etiketlenmiş bir örneklemi düzenli olarak kontrol edin. Kısa veya belirsiz açıklamalar için zorla kategori seçtirmek yerine “bağlam yetersiz” durumunu kullanmak yararlıdır. Yapay zekâ etiketleri inceleme kuyruğunu sıralamaya yardımcı olur; kullanıcı sorununa ilişkin çıkarımları ise gönderileri okuyup birden fazla gözlemi karşılaştırarak doğrulayın.
Hatalar, yeniden denemeler ve anahtarın güvenli kullanımı
Ağ isteği zaman aşımına uğrayabilir, geçici bir hatayla karşılaşabilir veya JSON olarak ayrıştırılamayan bir yanıt döndürebilir. İşlem adımlarını birbirinden ayırın: istek, HTTP kodunun denetlenmesi, JSON’un ayrıştırılması, üst düzey durumun doğrulanması, normalleştirme ve kayıt. Geçici sorunlarda artan aralıklarla sınırlı sayıda yeniden deneme yapın; kalıcı hataları daha sonra incelenmek üzere kaydedin ve çalıştırmayı başarılı olarak işaretlemeyin.
Anahtarı çalışma ortamının sır yöneticisinde veya ortam değişkeninde saklayın. API, license_key değerini sorgu dizesinde kabul ettiğinden, tam URL’yi ve istek parametrelerini günlüğe yazmaktan kaçının: bu kayıtlarda gizli anahtar bulunur. Hata ayıklama için anahtarı günlüklerden çıkararak uç noktayı, yanıt kodunu, süreyi, arama ifadesini ve görev kimliğini kaydedin.
Zamanlamayı ve örneklem hacmini kendi ihtiyacınıza ve platformun kullanım koşullarına göre belirleyin. Herkese açık verilerin toplanmasını gerçekten analiz için gerekenlerle sınırlayın; açıklamaların, bağlantıların ve içerik üreticisi kimliklerinin saklanmasını ekip içi kurallarda açıklayın. API yanıtları ve ölçümler eksik olabilir veya gözlemler arasında değişebilir; bu nedenle raporda her satırın toplama zamanını ve kaynağını koruyun.
Sonuç: elle paylaşılan bağlantılardan doğrulanabilir geçmişe
Kurulumun ardından ekip; düzenli güncellenen, bulunan videoların listesini, denetim için ham yanıtları, mevcut herkese açık ölçümlerin tablosunu ve yinelenen konuların özetini elde eder. Bu, yeni bir özellikle ilgili soruları daha çabuk fark etmeyi, kullanıcı senaryolarına örnekler bulmayı ve elle incelenecek gönderileri seçmeyi kolaylaştırır. Görüntülerin karşılaştırılması, daha önce bulunan videolardaki saklanmış değerlerin nasıl değiştiğini gösterir; sorgu günlüğü de örneklemin hangi yöntemle oluşturulduğunu açıklar.
Tek bir sorgu ve küçük bir sayfa sınırıyla başlayın, yanıtın gerçek yapısını kontrol edin, ardından ek ifadeler ve bir zamanlama ekleyin. Prototipi üretim ortamına taşımadan önce yinelenen kayıtları ayıklama, saklama ve hata işleme kurallarını belirleyin. Güncel uç noktalar ve parametreler için resmî API belgelerine bakın; özelliklere genel bakış ve deneme seçenekleri için TikTok Scraper API sayfasını ziyaret edin.
