Analytics API'si: kapsam filtreleri ve parça bazında veriler

Her analytics isteği kataloğunuzun bir bölümünü kapsar ve her istek o bölüm için tek bir toplu sonuç döndürür. Bu ikisi bir araya gelince kafa karıştırır: bir çağrıyı albümün UPC’sine göre filtrelerseniz albümün sayılarını alırsınız, albümdeki parça başına bir satır değil. Bu kılavuz kapsamı belirleyen filtreleri, toplama işleminin sonuca etkisini ve bir kapsamı parça parça ayıran iki endpoint’i anlatır.

Kapsam filtreleri

Dört filtre, bir analytics isteğini kataloğunuzun bir bölümüne daraltır. GET /analizler/summary üzerinde, bağımsız seri ve demografi endpoint’lerinde, ayrıca GET /analizler/leaderboards ve /analizler/placements üzerinde çalışırlar.

Filtre	Tür	Çözümlendiği parçalar
filter[release_id]	tam sayı	o yayındaki tüm parçalar
filter[isrc]	metin	o ISRC’yi taşıyan tek kayıt
filter[upc]	metin	o barkoda sahip yayındaki tüm parçalar
filter[artist_names][]	metin dizisi	künyesinde o sanatçıların yer aldığı, kataloğunuzdaki tüm parçalar

GET /analizler/streams?filter[start_date]=2026-06-01&filter[end_date]=2026-06-30&filter[upc]=0123456789012

Hiçbirini göndermezseniz istek, erişebildiğiniz kataloğun tamamını kapsar; her analytics çağrısının varsayılan kapsamı budur.

Yalnızca bir filtre geçerli olur

Dördü sabit bir sırayla çözümlenir: önce release_id, sonra isrc, sonra upc, en sonda artist_names[]. Bu sırada istekte bulunan ilk filtre kazanır. filter[release_id] ile filter[upc]’yi birlikte göndermek ikisinin kesişimini almaz; UPC yok sayılır. Yalnızca kastettiğiniz filtreyi gönderin.

Tanımlayıcı size ait olmadığında ne olur

Tanımlayıcı kataloğunuzun içinde çözümlenmediğinde, yayın düzeyindeki üç filtre farklı yanıt verir:

• filter[release_id] hata verir: böyle bir yayın hiç yoksa 404, varsa ama size ait değilse 403.
• filter[isrc] ve filter[upc] boş bir kapsama çözümlenir ve istek boş bir data ile başarılı olur.

Bu yüzden API’yi kullanıcının elle girdiği bir tanımlayıcı üzerinden çağırıyorsanız, 404 beklemek yerine data’nın boş olup olmadığına bakın.

Tek bir etiketinize daraltma

GET /analizler/summary ve GET /analizler/leaderboards, isteği kendi etiketlerinizden yalnızca birine daraltan filter[label_id] parametresini de kabul eder. Tanınmayan bir etiket 404, size ait olmayan bir etiket 403 döndürür. Bu filtre kapsamınızı yalnızca daraltabilir; onu genişleten bir değer yoktur.

Bunun yerine mağazaya göre daraltmak isterseniz filter[platform] kullanın. Kabul edilen değerler ve bölümlerin platform bazındaki matrisi için bkz. Analytics API’si: platformlar, kullanılabilirlik ve limitler.

Tek kapsam girer, tek seri çıkar

Seri ve summary bölümleri, çözümlenen kapsam üzerinden toplama yapar. Günlük bir seri, tarihe ve platforma göre gruplar ve ölçümü kapsamdaki tüm parçalar boyunca toplar. Bu yüzden geri aldığınız satır sayısı, kaç tarihin ve kaç platformun rapor verdiğine bağlıdır; filtrenin kaç parçayla eşleştiğine değil.

GET /analizler/streams?filter[start_date]=2026-06-01&filter[end_date]=2026-06-02&filter[upc]=0123456789012

{
  "data": [
    { "date": "2026-06-01", "platform": "SPOTIFY", "total": 1804 },
    { "date": "2026-06-01", "platform": "DEEZER", "total": 96 },
    { "date": "2026-06-02", "platform": "SPOTIFY", "total": 1731 }
  ]
}

On iki parçalık bir albüm de bir single da aynı yapıyı döndürür. Her satırdaki total, o tarih ve o platform için kapsamın tamamına ait rakamdır; albümde iki parça da olsa yirmi parça da olsa değer aynıdır.

Demografi endpoint’leri bir boyut ötede aynı şekilde davranır: /analizler/streams-by-country ülkeye göre gruplar ve kapsamın tamamı üzerinden toplar, yani UPC ile filtrelenmiş bir çağrı her parçanın değil albümün ülke dağılımını verir. /analizler/summary’nin her bölümü aynı kurala uyar. Aşağıda adı geçen iki bölüm bunun tek istisnasıdır.

Not

Bu bilinçli bir tasarımdır, etrafından dolaşılacak bir kısıtlama değil. İstekteki hiçbir şey bunu değiştirmez: seri endpoint’lerinde “parçaya göre grupla” diye bir parametre yoktur. Parça bazında sayılar aşağıdaki iki endpoint’ten gelir.

Parça bazında sayıları almak

İstediğiniz	Nereden alınır
Tek bir parçaya dair her şey	herhangi bir analytics endpoint’inde filter[isrc]
Bir dönem için sıralanmış parça bazında toplamlar	GET /analizler/leaderboards?type=tracks
Parça bazında günlük seri	metrics[]=track-streams-daily ile GET /analizler/summary

Parça bazında toplamlar: leaderboards endpoint’i

GET /analizler/leaderboards, kataloğunuzu seçilen pencerede toplanan stream sayısına göre sıralar. Analytics panelindeki Top performers kartının API karşılığıdır.

type zorunludur ve artists, tracks, albums ya da all (üç listenin tümü tek istekte) değerlerini alır. Kapsam filtreleri bir seriyi nasıl daraltıyorsa burada da tıpatıp aynı şekilde daraltır; bu yüzden filter[upc] ile birlikte type=tracks, size yalnızca o albümün parçalarını verir.

GET /analizler/leaderboards?type=tracks&filter[start_date]=2026-06-01&filter[end_date]=2026-06-30&filter[upc]=0123456789012&limit=50

Parça satırları name, artistName, streams, release_id, identifier ve isrc alanlarını taşır (identifier platform tanımlayıcısıdır; satır birden fazla platformu kapsıyorsa null olur. isrc ise satırdaki stream’lerin ait olduğu kayıttır). Satırlar stream sayısına göre, en yüksekten başlayarak gelir.

isrc, satırın tek bir kayda karşılık geldiği kesin olduğunda döner; aynı kaydı birden çok platformun her biri kendi identifier değeriyle bildirdiğinde de döner; birden fazla serviste bulunan bir parçada olağan durum budur. Satırın tek bir kaydı kapsadığı gösterilemiyorsa null gelir: tüm kataloğunuzu ada göre sıralayan filtresiz çağrılarda, yalnızca filter[artist_names][] ile daraltılmış satırlarda ve aynı başlık ile aynı sanatçının iki ayrı kaydı kapsadığı satırlarda. null, o satırın eşleştirilecek tek bir kaydı olmadığı anlamına gelir; kaydın ISRC’si bulunmadığı anlamına gelmez. isrc ile identifier alanlarını birbirinden bağımsız okuyun: biri null iken diğeri değer taşıyabilir. Her satırın bir ISRC taşıması gerekiyorsa aşağıdaki parça bazında günlük bölümleri kullanın.

Planlamaya değer iki limit var:

• limit varsayılan olarak 10’dur ve 50’yi aşamaz. 50’den fazla parçası olan bir albüm bu endpoint üzerinden eksiksiz listelenemez; bunun yerine parça bazında günlük bölümleri kullanıp satırları kendiniz toplayın.
• Pencere 180 günü aşamaz; bu, seri endpoint’lerinin izin verdiği 400 günden dardır. Birkaç kısa pencereyi arka arkaya eklemek daha uzun bir sıralamayı yeniden kurmaz, çünkü her ayın ilk onu çeyreğin ilk onu değildir.

Parça bazında günlük seri: iki summary bölümü

GET /analizler/summary, yayın genelindeki toplam yerine her parçayı ayrı ayrı raporlayan iki bölüm taşır:

Bölüm	Satır yapısı	Raporlayan
track-streams-daily	{ date, platform, isrc, streams }	tüm platformlar
track-listeners-daily	{ date, platform, isrc, listeners }	Spotify, Apple Music ve Amazon Music

İkisi de isteğe bağlıdır: yalnızca metrics[] içinde adlarını verdiğinizde hesaplanır ve ikisi de filter[release_id], filter[isrc] veya filter[upc] gerektirir. Yayın ya da parça filtresi olmadan birini adlandırmak, hatası metrics alanına iliştirilmiş bir 422 döndürür. Sanatçı adı filtresi bu koşulu karşılamaz.

Satırlar önce tarihe, sonra platforma, sonra ISRC’ye göre sıralanır; etkinlik olmayan bir gün sıfır yerine hiç satır taşımaz. Dinleyici rakamları günlük sayımlardır ve tarihler boyunca toplanamaz: iki gün dinleyen aynı kişi, o günlerin her birinde bir dinleyicidir.

Dikkat

Parça × gün × platform çarpımı fazla büyük olan bir istek, tarih aralığını daraltmanızı, filter[platform] belirlemenizi veya filter[isrc] ile tek bir parçaya inmenizi isteyen bir 422 döndürür. Aralık kırpılmaz, reddedilir; böylece yarım kalmış bir seri hiçbir zaman tammış gibi görünüp grafiklerinize girmez.

Uygulamalı örnek: bir albümde parça başına stream sayıları

UPC’si 0123456789012 olan bir albümünüz var ve haziran ayının sayılarını parça bazında görmek istiyorsunuz.

Parça bazında toplamların sıralı listesi için, leaderboards endpoint’inden albümün parçalarını isteyin:

GET /analizler/leaderboards?type=tracks&filter[start_date]=2026-06-01&filter[end_date]=2026-06-30&filter[upc]=0123456789012&limit=50

{
  "data": [
    { "name": "Nine Roses", "artistName": "Wiguez", "streams": 41208, "release_id": 88213, "identifier": "3n2f9xk2p1", "isrc": "USABC2600001" },
    { "name": "Harbour Lights", "artistName": "Wiguez", "streams": 18740, "release_id": 88213, "identifier": "7b1q4mz8v2", "isrc": "USABC2600002" }
  ],
  "meta": { "type": "tracks", "start_date": "2026-06-01", "end_date": "2026-06-30", "limit": 50 }
}

Her parçanın gün gün serisi için, summary endpoint’inden parça bazındaki bölümü isteyin:

GET /analizler/summary?filter[start_date]=2026-06-01&filter[end_date]=2026-06-30&filter[upc]=0123456789012&metrics[]=track-streams-daily

{
  "data": {
    "track-streams-daily": [
      { "date": "2026-06-01", "platform": "SPOTIFY", "isrc": "USABC2600001", "streams": 1412 },
      { "date": "2026-06-01", "platform": "DEEZER", "isrc": "USABC2600001", "streams": 78 },
      { "date": "2026-06-01", "platform": "SPOTIFY", "isrc": "USABC2600002", "streams": 392 }
    ]
  }
}

Stream’lerin yanında dinleyicileri de görmek için aynı çağrıya metrics[]=track-listeners-daily ekleyin. Albümde yalnızca tek bir parça ilginizi çekiyorsa UPC’yi bırakın ve onun yerine o parçanın filter[isrc] değerini gönderin; bu durumda her analytics endpoint’i yalnızca o kaydı raporlar.

İlgili

• Analytics API’si: platformlar, kullanılabilirlik ve limitler — hangi platformun hangi metrikleri raporladığı, raporlama sıklığı ve tarih aralığı üst sınırları
• API’ye Genel Bakış ve Hızlı Başlangıç — kimlik doğrulama, sandbox ve tam endpoint referansı
• Analytics — aynı veriler panelde
• Yapay Zeka Asistanınızı LabelGrid’e Bağlayın (MCP) — analytics’inizi gündelik dille sorgulayın