TikTok arama sonuçlarını haftalık destek konu listesine dönüştürün

Destek ekibinin, insanların anlaşılmayan bir özellikten söz ettiği veya ürün hakkında soru sorduğu herkese açık TikTok videolarının listesine ihtiyacı olabilir. Elle arama yapmak aynı şekilde tekrarlanması zor bir iştir; ayrıca arama API'si yanıtındaki videolar JSON'un farklı bölümlerinde bulunabilir. Aşağıda, anahtar kelimelerle sonuçları sorgulayan, her iki yapıyı birleştiren, ID'ye göre yinelenenleri kaldıran ve bulunan kayıtları CSV'ye kaydeden basit bir Python betiği yer alıyor.

Betiğin üreteceği sonuç

Çıktı olarak video ID'si, bağlantı, açıklama, yayınlanma zamanı, yazar ve mevcut etkileşim sayaçlarını içeren bir tablo elde edilir. Destek veya pazarlama ekibi, yanıt verilmesi, kılavuzun güncellenmesi ya da kendi CRM'lerinde kontrol edilmesi gereken konuları elle işaretleyebilir. Tablo, belirtilen sorgular için API'nin döndürdüğü sonuçları yansıtır; tüm tartışmaları kapsayan eksiksiz bir katalog değil, inceleme amaçlı bir örneklem olarak değerlendirin.

Betik, verileri toplamayı ve ilk aşamada sıralamayı sağlar. Bir açıklamanın soru, şikâyet ya da şaka olup olmadığını otomatik olarak belirlemez: bu etiketi elle inceleme sonrasında veya ayrı bir sınıflandırıcıyla eklemek; özgün metni ve kararın gerekçesini kaydetmek daha uygundur.

Neler sorgulanmalı ve yanıt nasıl yapılandırılmış?

jsonscraper, video araması için https://tiktok.evelode.com sunucusunda GET /searchVideo yolunu belgeliyor. Zorunlu parametre keyword; ayrıca count, bölge, sıralama, yayın dönemi ve sonraki sayfanın imleci de gönderilebilir. Örneğin, önceden belirlenmiş birkaç ifadeyle arama düzenli olarak tekrarlanabilir: özellik adı, sık kullanılan bir hata ifadesi ve ayarlarla ilgili kısa bir soru. Parametreler ve kabul edilen değerleri TikTok API başvuru kılavuzunda listeleniyor.

Arama yanıtında ayrıştırıcı açısından önemli bir özellik var: aweme_list dizisi boş olabilir; bu durumda bulunan nesneler search_item_list içinde, her birinin aweme_info alanında yer alabilir. Bu nedenle aşağıdaki işleyici her iki biçimi de kontrol ediyor. Yanıt örneği ve 25 Ekim 2026 tarihli kontrolde gözlemlenen alanlar jsonscraper'ın birincil belirtiminde verilmiştir; istatistik alanları bulunmayabileceğinden kod olmayan değerler üretmez.

Bir anahtar ve sorgu listesi hazırlayın

Anahtarı kaynak dosyaya değil, JSONSCRAPER_TIKTOK_LICENSE_KEY ortam değişkenine kaydedin. Linux veya macOS kabuğunda bunu şöyle yapabilirsiniz:

export JSONSCRAPER_TIKTOK_LICENSE_KEY="anahtarınız"

İstekler kitaplığını yükleyin ve her satırda bir arama ifadesi bulunan queries.txt dosyasını hazırlayın. Örneğin ürün adı ayarı ve özellik adı çalışmıyor ifadelerini kullanabilirsiniz. İfadeleri hedef kitlenizin diline göre seçin ve haftalık dışa aktarımların aynı sorguları karşılaştırması için ayrı bir listede tutun.

python -m pip install requests

Bulunan videoları toplayıp normalleştirin

Örnek Python 3.8 ve üzeri sürümlerle uyumludur. Her ifade için belirli bir sonuç sınırıyla bir sorgu yapar, HTTP hatalarını ve üst düzey durumu denetler, ardından yalnızca gerçekten mevcut alanları kaydeder. Yinelenen eşleşmeler aweme_id üzerinden birleştirilir ve videonun bulunduğu tüm sorgular keywords alanına yazılır. Ayrı bir collected_at_utc alanı, sonraki çalıştırmalarla karşılaştırma yapabilmek için verinin alındığı zamanı kaydeder.

import csv
import os
import sys
from datetime import datetime, timezone

import requests

BASE_URL = "https://tiktok.evelode.com/searchVideo"
API_KEY = os.environ.get("JSONSCRAPER_TIKTOK_LICENSE_KEY")

if not API_KEY:
    raise SystemExit("JSONSCRAPER_TIKTOK_LICENSE_KEY değişkenini ayarlayın")


def get_items(tiktok):
    """Videoları belgelenmiş arama yanıtının her iki biçiminden de çıkarır."""
    items = list(tiktok.get("aweme_list") or [])
    for entry in tiktok.get("search_item_list") or []:
        info = entry.get("aweme_info") if isinstance(entry, dict) else None
        if info:
            items.append(info)
    return items


with open("queries.txt", encoding="utf-8") as query_file:
    queries = [line.strip() for line in query_file if line.strip()]

collected_at = datetime.now(timezone.utc).isoformat()
videos = {}

for keyword in queries:
    response = requests.get(
        BASE_URL,
        params={
            "license_key": API_KEY,
            "keyword": keyword,
            "count": 30,
            "region": "US",
            "sort_by": "relevance",
        },
        timeout=30,
    )
    response.raise_for_status()
    payload = response.json()

    if payload.get("status") != "ok":
        print("API durumu başarısız olan sorgu:", keyword, file=sys.stderr)
        continue

    tiktok = payload.get("tiktok") or {}
    for item in get_items(tiktok):
        video_id = item.get("aweme_id")
        if not video_id:
            continue

        if video_id not in videos:
            author = item.get("author") or {}
            stats = item.get("statistics") or {}
            videos[video_id] = {
                "aweme_id": video_id,
                "keywords": [keyword],
                "description": item.get("desc"),
                "share_url": item.get("share_url"),
                "create_time": item.get("create_time"),
                "author": author.get("unique_id") or author.get("nickname"),
                "play_count": stats.get("play_count"),
                "digg_count": stats.get("digg_count"),
                "comment_count": stats.get("comment_count"),
                "share_count": stats.get("share_count"),
                "collected_at_utc": collected_at,
            }
        elif keyword not in videos[video_id]["keywords"]:
            videos[video_id]["keywords"].append(keyword)

columns = [
    "aweme_id", "keywords", "description", "share_url", "create_time",
    "author", "play_count", "digg_count", "comment_count", "share_count",
    "collected_at_utc",
]
with open("tiktok_support_review.csv", "w", newline="", encoding="utf-8-sig") as output:
    writer = csv.DictWriter(output, fieldnames=columns)
    writer.writeheader()
    for video in videos.values():
        row = dict(video)
        row["keywords"] = " | ".join(row["keywords"])
        writer.writerow(row)

print("Kaydedilen benzersiz video sayısı:", len(videos))

Sorgu params parametresi üzerinden gönderildiğinden, kitaplık metin ifadelerini URL'de doğru biçimde kodlar. Belgelerde anlatıldığı üzere anahtar, sorgu parametresinde yer alır; uygulama günlüğüne sorgunun tam URL'sini yazdırmayın. Sorun giderme için HTTP yanıt kodunu, arama ifadesini ve çalıştırma zamanını kaydedin; ancak gizli bilgileri ve görev için gerekmeyen kişisel verileri hariç tutun.

CSV'yi yanlış çıkarımlara kapılmadan okuyun

keywords sütunu, videonun bulunduğu tüm ifadeleri içerir; collected_at_utc ise yayınlanma zamanını toplama zamanından ayırmaya yarar. ID, yinelenenleri kaldırmak için kullanışlıdır; bağlantı ise insan tarafından kontrol edilmesini sağlar. Boş bir sayaç, ilgili yanıt alanının bulunmadığı anlamına gelir; değerinin sıfır olduğu anlamına gelmez.

İlk sıralama için CSV'nin çalışma kopyasına konu, sinyal türü, yanıt gerekli ve dahili içerik bağlantısı sütunlarını ekleyin. Konu seçenekleri ürününüze uygun olmalıdır; örneğin kurulum, ödeme, uyumluluk veya hata giderme. Bu düzenleme, dışa aktarılan veriyi inceleme kuyruğuna dönüştürür ve kararı özgün video üzerinden kontrol etme olanağını korur.

Toplamayı zamanlayın

Önce betiği elle çalıştırıp birkaç satırı ve bağlantıyı kontrol edin. Ardından cron'a, CI görevine veya Python sürecini çalıştırabilen bir otomasyon senaryosuna ekleyin. Düzenli raporlar için her dışa aktarımı saklayın ya da benzersiz video anahtarı ve anlık görüntü tarihiyle verileri bir depoya ekleyin. Böylece ekip yeni bulunan yayınları tekrar gözlemlerden ayırabilir ve kullanılabilir sayaçların çalıştırmalar arasında nasıl değiştiğini izleyebilir.

Sonuçlarda ilerlemek için cursor parametresi kullanılabilir; bu parametre önceki çağrının yanıtından alınmalıdır. Bu basit örnekte sayfalama bilerek eklenmemiştir: sınırlı sayıda sorguyu kontrol etmek ve tekrarlamak daha kolaydır. Sayfaları eklerseniz imleci olduğu gibi saklayın, devam durumu bayrağına göre durun ve her çalıştırma için bir üst çağrı sınırı belirleyin. API sorgusu bir örneklem döndürür; satır sayısını TikTok'un tamamını kapsayan bir sonuç olarak yorumlamayın.

Uygulamanın pratik sınırları

Arama sonuçları, ekip tarafından zaten bilinen ifadelerle videoları keşfetmek için uygundur. Sınıflandırmaya yönelik materyal toplamaya yardımcı olur; ancak gelen başvuruların, kendi sitenizin analizlerinin veya videonun bağlamını kontrol etmenin yerini tutmaz. Açıklama, videonun özünü yansıtmayabilir ve mevcut ölçümler verilerin alındığı andaki durumu gösterir. Çalışanların sınıflandırmayı yeniden gözden geçirebilmesi için konuları ve çıkarımları özgün alanlardan ayrı kaydedin.

Düzenli izlemeye başlamadan önce dışa aktarıma kimin erişebileceğini, verilerin ne kadar süre saklanacağını ve herkese açık bilgilerin hangi amaçla kullanılacağını belirleyin. Yalnızca ürün incelemesi için gerekli alanları saklayın ve medya dosyalarını kopyalamak yerine özgün yayınlara bağlantı vermeyi tercih edin. Sorgulama ve kullanılabilir entegrasyon seçeneklerini kontrol etmek için TikTok Scraper API sayfasını ve arama yolu belgelerini inceleyin.