Analytics API'si: platformlar, kullanılabilirlik ve limitler

LabelGrid herkese açık API’si, streaming analytics’i GET /analizler/summary (seçtiğiniz bölümleri döndüren bileşik bir endpoint) ve GET /analizler/streams gibi bağımsız seri endpoint’leri üzerinden sunar. Bu sayfa platform kümesini, her platformun neyi raporladığını nasıl keşfedeceğinizi, raporlama sıklığını ve istek limitlerini kapsar.

Desteklenen platformlar

filter[platform], dokuz mağazayı kapsayan on değer kabul eder:

SPOTIFY, APPLE_MUSIC (ITUNES aynı mağazanın takma adı olarak kabul edilir), DEEZER, BOOMPLAY, AWA, AUDIOMACK, KUGOU, KUWO, QQMUSIC

Hesabınızın verisi olan tüm platformların birleşik görünümünü almak için filter[platform] parametresini atlayın.

Kullanılabilirliği keşfetmek: GET /analizler/availability

Her platform her metriği raporlamaz. Kullanılabilirlik keşif endpoint’i tüm tabloyu tek çağrıda döndürür:

GET /analizler/availability

{
  "data": {
    "sections": ["streams", "listeners", "saves", ...],
    "platforms": ["SPOTIFY", "APPLE_MUSIC", "DEEZER", "BOOMPLAY", "AWA", "AUDIOMACK", "KUGOU", "KUWO", "QQMUSIC"],
    "availability": {
      "streams": { "SPOTIFY": "available", "KUGOU": "available" },
      "listeners": { "SPOTIFY": "available", "KUGOU": "not_available_for_platform" }
    },
    "platform_cadence": { "SPOTIFY": "daily", "KUGOU": "weekly" }
  }
}

• sections — kanonik sırayla tüm analytics bölüm anahtarları. Bu liste yetkilidir: /analizler/summary üzerinde metrics[]’in kabul ettiği kümenin aynısıdır.
• platforms — filter[platform]’un kabul ettiği tüm değerler.
• availability — önce bölüme, sonra platforma göre dizinlenir. Her hücre available veya not_available_for_platform değeridir.
• platform_cadence — platform başına daily veya weekly (bkz. Raporlama sıklığı).

Yanıt statik yapılandırmadır — hesabınıza, bir tarih aralığına veya herhangi bir filtreye bağlı değildir — bir kez alıp önbelleğe alın. Parametre almaz ve diğer /analizler/* endpoint’leriyle aynı kimlik doğrulamayı ve hız limitlerini kullanır.

Filtrelenmiş isteklerde availability alanı

Bir analytics isteğini tek bir platforma göre filtrelediğinizde (örneğin filter[platform]=DEEZER), yanıt data’nın yanında bir availability alanı da taşır:

• available — platform bu metriği raporlar; data normal şekilde doldurulur.
• not_available_for_platform — platform bu metriği raporlamaz; data boştur. Bu beklenen davranıştır, hata değildir.

Bağımsız endpoint’ler tek bir üst düzey değer taşır; /analizler/summary, istenen her bölüm için bir girdi içeren bir map taşır. Platform filtresi olmayan istekler availability alanı taşımaz. Boş bir data’yı “etkinlik yok” olarak yorumlamadan önce her zaman availability’yi okuyun.

Platformlar neyi raporlar

Matris bir bakışta (yetkili ve güncel sürüm için endpoint’i çağırın):

Bölümler	Raporlayan platformlar
streams	Dokuz platformun tümü
listeners	SPOTIFY, APPLE_MUSIC, AUDIOMACK
saves	SPOTIFY, AUDIOMACK
skips, shares, completion-rate, lyrics-view-rate, canvas-view-rate, device-split, source-split, saves-by-tier, shares-by-country	SPOTIFY
streams-by-country	SPOTIFY, APPLE_MUSIC, DEEZER, BOOMPLAY, AUDIOMACK
streams-by-gender, streams-by-age	SPOTIFY, APPLE_MUSIC
library-adds, playlist-adds, shazams, shazams-by-city, shazams-by-state, Apple boyut bölümleri	APPLE_MUSIC
Dinleyici kitle bileşimi ve per-stream bölümleri (listener-plan-mix, avg-listen-time, hour-of-day, …)	SPOTIFY
Placement’lar (GET /analizler/placements)	SPOTIFY, APPLE_MUSIC, DEEZER

Listener semantiği hakkında bir not: Spotify ve Apple Music, parça başına tekilleştirilmiş günlük dinleyici sayısı raporlar. Audiomack’in günlük rakamı, ülke ve abonelik seviyesine göre raporlanan sayıların toplamıdır; aynı gün birden fazla dilimde etkin olan bir dinleyici birden çok kez katkıda bulunur.

Raporlama sıklığı: günlük ve haftalık platformlar

Her GET /analizler/summary yanıtı, her platformun ne sıklıkla raporladığını belirten bir meta.platform_cadence map’i taşır:

• daily — günde bir rapor: SPOTIFY, APPLE_MUSIC, DEEZER, BOOMPLAY, AWA, AUDIOMACK
• weekly — haftada bir rapor: KUGOU, KUWO, QQMUSIC

Haftalık bir platform, raporun kapsadığı güne tarihlenmiş ve o haftanın tüm toplamını taşıyan parça başına haftada bir veri noktası üretir. Toplam asla yedi güne bölünmez. Günlük bir seride haftada bir dolu tarih görürsünüz; aradaki tarihlerde satır yoktur.

Bunu tüketicinizde, sıklığı tarihlerin aralığından çıkarmak yerine platform_cadence okuyarak ele alın:

• İki haftalık nokta arasındaki boşluğu eksik veri olarak değerlendirmeyin.
• Haftalık bir noktayı günlük ortalamaya bölmeyin.
• Noktaları oldukları gibi toplamak yine herhangi bir aralığın doğru toplamını verir.

Sıklık, döndürülen bir serinin noktalarının nasıl tarihlendiğini (day veya week) belirten meta.section_granularity’den farklıdır. Bir yanıt aynı anda "day" ayrıntı düzeyi ve "weekly" sıklık taşıyabilir — gün tarihli noktalar, haftada bir.

Bölüm seçme: /analizler/summary üzerinde metrics[]

metrics[], GET /analizler/summary üzerinde zorunludur: istediğiniz bölümleri adlandırın, istek başına 1’den 12’ye kadar.

GET /analizler/summary?filter[start_date]=2026-06-01&filter[end_date]=2026-06-30&metrics[]=streams&metrics[]=listeners

12’den fazla anahtar istemek, seçimi bölmenizi isteyen bir 422 döndürür. Her projeksiyon kapsam ve pencere başına bağımsız olarak önbelleğe alınır; bu yüzden büyük bir seçimi birden çok isteğe bölmek, tekrarlanan çağrılarda ucuzdur. Geçerli bölüm anahtarları, GET /analizler/availability’nin sections listesidir; geçersiz bir metrics[] isteği de bunları hata mesajında sıralar.

Tarih aralığı limitleri

GET /analizler/summary ile bağımsız seri ve demografi endpoint’leri, en fazla 400 günlük bir tarih aralığı kabul eder — tek istekte tam bir yıl artı bir karşılaştırma dönemi için yeterli. Limiti aşan bir aralık, hata mesajında limiti belirten bir 422 döndürür.

Endpoint ailesi	Maksimum aralık
/analizler/summary ve bağımsız seri/demografi endpoint’leri	400 gün
/analizler/leaderboards, /analizler/placements	180 gün

Sıralama endpoint’leri kendi 180 günlük limitlerini korur — ve birkaç kısa top-N penceresini birleştirmenin, daha uzun bir dönemin top-N’ini yeniden oluşturmadığını unutmayın.

400 günlük pencereyle iki davranış daha geliyor:

• 90 günden uzun süreyi kapsayan istekler, standart analytics limitine ek olarak ikinci ve daha düşük bir hız limitine karşı sayılır (hesap başına dakikada 30’a karşılık standart 60; partner çıkış IP’si bütçeleri de aynı şekilde yarıya iner). 90 gün veya daha kısa istekler etkilenmez. Herhangi bir limiti aşmak, olağan Retry-After ve X-RateLimit-* başlıklarıyla 429 döndürür.
• Limitin içindeki bir aralık yine de hesaplanamayacak kadar ağır olabilir — örneğin çok sayıda metrics[] ile tam pencerede çok büyük bir katalog. Bu, “tarih aralığını daraltın” mesajıyla 422 döndürür. Bunu yeniden denenebilir kabul edin: daha kısa bir aralık veya daha az bölümle yeniden deneyin. İlgisiz bir sunucu hatası yine 500 döndürür; dolayısıyla buradaki bir 422 güvenilir biçimde “bu istek çok büyüktü” anlamına gelir.

İlgili

<<<<<<< HEAD

• API’ye Genel Bakış — kimlik doğrulama, uç noktalar ve tam referans
• Analytics — analytics panosu ve her sekmenin gösterdikleri =======
• API’ye Genel Bakış — kimlik doğrulama, endpoint’ler ve tam referans
• Analytics — analytics paneli ve her görünümün ne gösterdiği
• AI Asistanınızı LabelGrid’e Bağlayın (MCP) — analytics’inizi doğal dille sorgulayın

origin/main