TikTok arama sonuçları JSON ayrıştırılırken nasıl kaybolmaz?

TikTok’ta API üzerinden video ararken videolar, işleyicinin ilk bakışta beklediği dizide bulunmayabilir. jsonscraper’ın `\/searchVideo` isteği için incelenen yanıtında `aweme_list` alanı boştu; video verisi içeren öğeler ise `search_item_list[].aweme_info` içindeydi. Kod yalnızca `aweme_list` alanını okuyorsa yanıt bulunan videoları içerse bile sıfır video kaydeder. Geliştiriciler açısından bu, somut bir güvenilirlik sorunudur: veritabanına yazmadan veya rapora aktarmadan önce verilerin her iki biçimini de çıkarıp tek bir listede normalleştirmek gerekir.

Canlı örnek ve uç nokta açıklamasına jsonscraper API belirtiminden ve TikTok uç noktası belgelerinden ulaşılabilir. Belirtimdeki şema anlık görüntüsü 25 Ekim 2026 tarihini taşıyor; bu görüntü belirli bir yanıtın yapısını gösterir, sonraki her istekte her alanın bulunacağını garanti etmez.

Ayrıştırıcı neden boş bir liste döndürebilir?

`GET https:\/\/tiktok.evelode.com\/searchVideo` uç noktası, zorunlu `keyword` parametresini kullanarak video arar. Belgelerde ayrıca `cursor`, `count`, `cache_timeout`, `date_posted`, `sort_by` ve `region` parametreleri listeleniyor. Gözlemlenen yanıt şemasında üst nesne `status` ve iç içe `tiktok` nesnesini içeriyor; bunun içinde ise `cursor`, `has_more`, `status_code`, `aweme_list` ve `search_item_list` bulunuyor.

`count=3` ile anahtar kelime kullanılan belirli bir gözlemde `aweme_list` dizisi boştu. Buna karşın `search_item_list`, video bilgilerinin `aweme_info` içinde yer aldığı öğeler içeriyordu. Bu nesnelerde video kimliği, açıklama, gönderi URL’si, yazar ve görüntülenme, beğeni ya da yorum sayısı gibi istatistikler bulunabiliyordu. Açıklanan alanlar gözlemlenen şemayı yansıtır; yine de işleyicinin eksik değerleri kabul etmesi gerekir.

Buradan çıkarılacak pratik sonuç şudur: HTTP isteğinin başarılı olmasıyla beklenen alanlardan birinde boş olmayan bir dizi bulunması, iki ayrı kontroldür. Önce dış durum kodunu ve `tiktok` nesnesinin varlığını kontrol edin; ardından videoları belgelenmiş her konumdan toplayın. Analitik için kimlikleri ve ham yanıtı saklayın; böylece belirli bir kaydın nasıl çıkarılıp normalleştirildiğini izleyebilirsiniz.

Verileri depolamaya yazmadan önce normalleştirin

API ile kendi sisteminiz arasındaki kullanışlı sınır, iç içe `tiktok` nesnesini alıp standartlaştırılmış öğeler döndüren bir işlevdir. Bu işlev iki diziyi de işlemeli, sözlük olmayan veya boş öğeleri atlamalı ve aynı videonun `aweme_id` değerine göre tekrarını gidermelidir. Sağlayıcı bir sayaç döndürmediyse alanı boş bırakın: sıfır ölçülmüş bir değer anlamına gelirken `None` alanın bulunmadığını belirtir.

Aşağıda Python 3.8 ve üzeri için kısa bir örnek yer alıyor. Kod tek bir istek gönderir, aktarım ve üst düzey durumları denetler, sonucun iki biçimini de normalleştirir ve seçilen alanları yazdırır. Anahtar ortam değişkeninden okunur ve günlüğe yazdırılmaz.

import os
import requests

BASE_URL = "https:\/\/tiktok.evelode.com"


def extract_videos(tiktok):
    candidates = []
    aweme_list = tiktok.get("aweme_list") or []
    if isinstance(aweme_list, list):
        candidates.extend(aweme_list)

    search_items = tiktok.get("search_item_list") or []
    if isinstance(search_items, list):
        for item in search_items:
            if isinstance(item, dict):
                candidates.append(item.get("aweme_info"))

    unique = {}
    for video in candidates:
        if not isinstance(video, dict):
            continue
        video_id = video.get("aweme_id")
        if video_id:
            unique[video_id] = video
    return list(unique.values())


license_key = os.environ["JSONSCRAPER_TIKTOK_LICENSE_KEY"]
response = requests.get(
    BASE_URL + "\/searchVideo",
    params={
        "license_key": license_key,
        "keyword": "python tutorial",
        "count": 10,
        "region": "US",
    },
    timeout=30,
)
response.raise_for_status()
payload = response.json()

if payload.get("status") != "ok":
    raise RuntimeError("TikTok API returned a non-ok status")

tiktok = payload.get("tiktok")
if not isinstance(tiktok, dict):
    raise RuntimeError("Response has no tiktok object")

for video in extract_videos(tiktok):
    stats = video.get("statistics") or {}
    author = video.get("author") or {}
    print({
        "aweme_id": video.get("aweme_id"),
        "desc": video.get("desc"),
        "share_url": video.get("share_url"),
        "author": author.get("unique_id"),
        "play_count": stats.get("play_count"),
        "digg_count": stats.get("digg_count"),
        "comment_count": stats.get("comment_count"),
    })

Bağımlılığı python -m pip install requests komutuyla yükleyin, çalıştırma ortamında `JSONSCRAPER_TIKTOK_LICENSE_KEY` değişkenini ayarlayın ve dosyayı örneğin `search_videos.py` adıyla kaydedin. İstek parametreleri belgelerdeki adlarla eşleşir: `keyword`, `count` ve `region`; `license_key` ise sorgu parametresi olarak gönderilir. Kod, kaydedilmiş örnekte olduğu gibi yanıtın `status: "ok"` içerdiğini varsayar. API farklı bir durum döndürürse şüpheli yapının sonraki aşamalara aktarılmasını önlemek için işlem durur.

Örneği tekrarlanabilir bir veri toplama sürecine dönüştürün

Tek seferlik dışa aktarım için normalleştirilmiş öğeleri JSON Lines biçiminde veya bir tabloya yazmak yeterlidir. Sürekli çalışan bir süreçte ham yanıtı, alınma zamanı ve arama sorgusuyla birlikte saklayın. Normalleştirilmiş videoların tutulduğu ayrı tabloda `aweme_id` anahtar olarak kullanılabilir: sonuç tekrar geldiğinde kayıt güncellenir, iki dizide tekrarlanan bir kimlik ise mükerrer kayıt oluşturmaz.

Sonraki sayfayı istemek için belgelerde `cursor` parametresi belirtiliyor: önceki yanıtta alınan değeri gönderin. Bunu opak bir belirteç olarak değerlendirin; değiştirmeden saklayıp geri iletin. Sayfalama döngüsü, `has_more` devam olmadığını gösterdiğinde veya API kullanılabilir bir imleç sağlamadığında sona ermelidir; hatalı bir mantığın sonsuz döngü oluşturmasını engellemek için her çalıştırmadaki sayfa sayısını sınırlayın. Kaynaklar parametre adını ve gözlemlenen şemada `cursor` ile `has_more` alanlarının bulunduğunu doğruluyor, ancak sonuçların eksiksiz olacağını garanti etmiyor.

Birden fazla arama ifadesini izlerken ifadeyi video kimliği ve toplama zamanıyla birlikte saklayın. Böylece sorgulara göre dökümler oluşturabilir, sonuçları çalıştırmalar arasında karşılaştırabilir ve yeni kimlikleri daha ileri sınıflandırma için kuyruğa gönderebilirsiniz. Böyle bir sistem, alınan arama sonuçlarını temsil eder; veri kümesi sorguya, bölgeye, zamana ve API’nin gerçekten döndürdüğü öğelere bağlıdır.

Yalnızca isteğin başarılı olup olmadığını değil, veri kalitesini de denetleyin

Normalleştirme sonrasında işlem hattınız için basit teknik ölçümler tutmak yararlıdır: her diziden gelen kayıt sayısı, benzersiz kimlik sayısı, kimliği olmayan öğelerin oranı ve istatistikleri eksik öğelerin oranı. Bunlar belirli bir yanıtın işlenmesine ilişkin ölçümlerdir; video popülerliğini değerlendirmez. Örneğin `play_count` alanı bulunmayan öğelerin artması, analitik sisteminin bilinmeyen değeri sıfırla değiştirmek yerine boş bırakıp alanın eksik olduğunu belirtmesi gerektiğini gösterir.

Daha sonraki hesaplamaları her videoda aynı istatistiklerin mutlaka bulunduğu varsayımına bağlamayın. Ham verileri saklarken tüm JSON’u koruyun; analitik tabloda ise yalnızca gereken alanları seçip `NULL` değerlerine izin verin. Yanıtın biçimi değişirse ham arşiv, yeniden istek göndermeden normalleştiriciyi tekrar çalıştırmanıza olanak verir.

API anahtarını CI sırları veya orkestratörün ortam değişkenleri üzerinden iletin. Günlüklere kaydedilen URL’lere eklemeyin, istek parametreleri nesnesini yazdırmayın ve anahtar değerini ham yanıtların yanında saklamayın. İşlem zamanlanmış olarak çalışıyorsa istek zaman aşımı, HTTP hata işleme ve beklemeli yeniden denemeler ekleyin; farklı arama sonuçlarının sayfalarını karıştırmamak için imleci yalnızca ilgili arama sorgusuyla birlikte saklayın.

Sonuç: atlanan videolar yerine tek bir tablo

Normalleştirmeden sonra sonraki aşamadaki kod, öğe ister `aweme_list` ister `search_item_list[].aweme_info` içinde gelmiş olsun, tek bir video listesi alır. Kimlik yinelenenleri kaldırmayı sağlar, isteğe bağlı alanlar ise açıkça boş kalır. Böylece yalnızca tek bir dizinin okunmasından kaynaklanan boş rapor riski azalır ve dışa aktarma, filtreleme veya sınıflandırma gibi sonraki adımlar daha öngörülebilir olur.

Kontrole, temel API uç noktasının belirtildiği ve demoya geçişin bulunduğu TikTok Scraper API sayfasından başlayabilirsiniz. Entegrasyon için resmî belgeleri kullanın ve önce az sayıda öğeyle işlemeyi sınayın; gerekirse `count` değerini artırıp belgelenmiş imleçle sonuçları almaya devam edin. Böylece TikTok’un tüm sonuçlarını kapsadığı varsayımına değil, ihtiyaçlarınıza yönelik düzenli bir veri katmanına sahip olursunuz.