API Analytics: filter cakupan dan data per track

Setiap permintaan analytics mencakup sebagian katalog Anda, dan setiap permintaan mengembalikan satu hasil gabungan untuk bagian tersebut. Perpaduan keduanya inilah yang sering mengecoh: Anda memfilter satu panggilan dengan UPC album, lalu yang kembali adalah angka album itu, bukan satu baris untuk tiap track di dalamnya. Halaman ini membahas filter yang menentukan cakupan, apa yang dilakukan agregasi terhadap hasilnya, dan dua endpoint yang bisa memecah sebuah cakupan track demi track.

Filter cakupan

Ada empat filter yang mempersempit permintaan analytics ke sebagian katalog Anda. Semuanya berlaku pada GET /analitik/summary, pada endpoint seri dan endpoint demografi mandiri, serta pada GET /analitik/leaderboards dan /analitik/placements.

Filter	Tipe	Track yang dicakupnya
filter[release_id]	integer	semua track pada rilis tersebut
filter[isrc]	string	satu rekaman dengan ISRC tersebut
filter[upc]	string	semua track pada rilis dengan barcode tersebut
filter[artist_names][]	array string	semua track di katalog Anda yang dikreditkan kepada artis tersebut

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

Bila tidak ada satu pun filter ini yang dikirim, permintaan mencakup seluruh katalog yang bisa Anda akses. Itulah cakupan default untuk setiap panggilan analytics.

Hanya satu filter yang berlaku

Keempatnya diproses dalam urutan tetap: release_id, lalu isrc, lalu upc, lalu artist_names[]. Yang pertama ditemukan itulah yang dipakai. Mengirim filter[release_id] bersama filter[upc] tidak menggabungkan keduanya. UPC-nya diabaikan. Kirim saja filter yang benar-benar Anda maksud.

Apa yang terjadi bila identifier bukan milik Anda

Ketiga filter identifier memberi respons yang berbeda bila identifier tidak ditemukan di katalog Anda:

• filter[release_id] memunculkan error: 404 bila rilis itu tidak ada, 403 bila rilis itu ada tetapi bukan milik Anda.
• filter[isrc] dan filter[upc] menghasilkan cakupan kosong, dan permintaan tetap berhasil dengan data kosong.

Jadi bila integrasi Anda menerima identifier yang diketik pengguna, periksa apakah data kosong, jangan mengandalkan 404.

Mempersempit ke salah satu label Anda

GET /analitik/summary dan GET /analitik/leaderboards juga menerima filter[label_id], yang mempersempit permintaan ke satu label milik Anda. Label yang tidak dikenal mengembalikan 404, dan label yang bukan milik Anda mengembalikan 403. Filter ini hanya bisa mempersempit cakupan Anda. Tidak ada nilai yang bisa memperluasnya.

Untuk mempersempit ke toko tertentu, gunakan filter[platform]. Lihat API Analytics: platform, ketersediaan, dan batasan untuk nilai yang diterima dan matriks bagian per platform.

Satu cakupan masuk, satu seri keluar

Endpoint seri dan bagian-bagian pada summary mengagregasi seluruh cakupan setelah difilter. Seri harian mengelompokkan data per tanggal dan per platform, lalu menjumlahkan nilai seluruh track dalam cakupan tersebut. Jadi jumlah baris yang Anda terima bergantung pada berapa banyak tanggal dan platform yang melapor, bukan pada berapa banyak track yang cocok dengan filter.

GET /analitik/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 }
  ]
}

Baik album berisi dua belas track maupun sebuah single sama-sama mengembalikan bentuk seperti ini. Nilai total di setiap baris adalah angka untuk seluruh cakupan pada tanggal dan platform tersebut, dan tetap satu angka gabungan entah album itu berisi dua track atau dua puluh.

Endpoint demografi bekerja dengan cara yang sama, hanya dengan dimensi pengelompokan yang berbeda: /analitik/streams-by-country mengelompokkan per negara dan menjumlahkan seluruh cakupan, sehingga panggilan yang difilter dengan UPC memberi rincian per negara untuk albumnya, bukan untuk tiap track. Semua bagian /analitik/summary mengikuti aturan yang sama, dengan dua pengecualian yang dibahas di bawah.

Catatan

Ini memang disengaja, bukan keterbatasan yang perlu disiasati. Tidak ada parameter dalam permintaan yang bisa mengubahnya: endpoint seri tidak menyediakan cara untuk mengelompokkan hasil per track. Angka per track berasal dari dua endpoint di bawah ini.

Mendapatkan angka per track

Yang Anda butuhkan	Dari mana mendapatkannya
Semua data untuk satu track	filter[isrc] pada endpoint analytics mana pun
Total per track untuk satu periode, diurutkan berdasarkan peringkat	GET /analitik/leaderboards?type=tracks
Seri harian per track	GET /analitik/summary dengan metrics[]=track-streams-daily

Total per track: endpoint leaderboards

GET /analitik/leaderboards memeringkat katalog Anda berdasarkan jumlah streams sepanjang jendela waktu yang diminta. Ini padanan API dari kartu Top performers di dashboard Analytics.

type wajib diisi dan menerima artists, tracks, albums, atau all (ketiga daftar sekaligus dalam satu permintaan). Filter cakupan bekerja persis seperti pada endpoint seri, jadi type=tracks bersama filter[upc] memberi Anda track album itu saja.

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

Setiap baris track berisi name, artistName, streams, release_id, identifier (identifier platform, atau null bila baris itu mencakup lebih dari satu platform), dan isrc (rekaman yang menjadi asal stream pada baris itu). Baris dikembalikan terurut berdasarkan streams, dari yang tertinggi.

isrc terisi setiap kali baris itu jelas merupakan satu rekaman, termasuk ketika beberapa platform melaporkan rekaman yang sama dengan identifier masing-masing, yang lazim terjadi pada track yang tersedia di lebih dari satu layanan. Nilainya null bila tidak dapat dibuktikan bahwa baris itu hanya mencakup satu rekaman: panggilan tanpa filter, yang memeringkat berdasarkan nama di seluruh katalog Anda; baris yang hanya dipersempit dengan filter[artist_names][]; dan baris yang judul serta artisnya sama tetapi mencakup dua rekaman berbeda. null berarti baris itu tidak memiliki satu rekaman tunggal yang bisa dipasangkan dengannya, bukan berarti rekamannya tidak memiliki ISRC. Baca isrc dan identifier sebagai dua hal yang independen: salah satunya bisa null sementara yang lain berisi nilai. Bila setiap baris harus memuat ISRC, gunakan bagian harian per track di bawah.

Dua batasan yang perlu Anda perhitungkan sejak awal:

• limit bernilai 10 secara default dan tidak boleh lebih dari 50. Album dengan lebih dari 50 track tidak bisa ditampilkan utuh lewat endpoint ini. Gunakan bagian harian per track, lalu jumlahkan sendiri barisnya.
• Jendela waktunya tidak boleh lebih dari 180 hari, lebih sempit daripada 400 hari yang diizinkan endpoint seri. Menggabungkan beberapa jendela pendek tidak akan menghasilkan peringkat untuk periode yang lebih panjang, karena sepuluh besar tiap bulan bukanlah sepuluh besar satu kuartal.

Seri harian per track: dua bagian pada summary

GET /analitik/summary memiliki dua bagian yang melaporkan tiap track secara terpisah, bukan total untuk keseluruhan rilis:

Bagian	Bentuk baris	Dilaporkan oleh
track-streams-daily	{ date, platform, isrc, streams }	semua platform
track-listeners-daily	{ date, platform, isrc, listeners }	Spotify, Apple Music, dan Amazon Music

Keduanya harus diminta secara eksplisit: bagian ini hanya dihitung bila Anda mencantumkannya dalam metrics[], dan keduanya mewajibkan filter[release_id], filter[isrc], atau filter[upc]. Menyebut salah satunya tanpa filter rilis atau track mengembalikan 422 dengan pesan error pada field metrics. Filter nama artis tidak memenuhi syarat ini.

Baris diurutkan berdasarkan tanggal, lalu platform, lalu ISRC. Hari tanpa aktivitas tidak memunculkan baris sama sekali, bukan baris bernilai nol. Angka pendengar adalah hitungan per hari dan tidak bisa dijumlahkan antartanggal: orang yang sama mendengarkan pada dua hari berbeda terhitung satu pendengar di masing-masing hari.

Perhatian

Bila hasil kali track × hari × platform terlalu besar, permintaan mengembalikan 422 yang meminta Anda mempersempit rentang tanggal, menyetel filter[platform], atau mempersempit ke satu track dengan filter[isrc]. Rentangnya ditolak, bukan dipotong, sehingga seri yang tidak lengkap tidak pernah masuk ke grafik Anda seolah-olah utuh.

Contoh kasus: streams per track untuk sebuah album

Misalkan Anda memiliki album dengan UPC 0123456789012 dan ingin melihat angka bulan Juni yang dirinci per track.

Untuk daftar peringkat total per track, panggil endpoint leaderboards untuk track album tersebut:

GET /analitik/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 }
}

Untuk seri harian tiap track, minta bagian per track dari endpoint summary:

GET /analitik/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 }
    ]
  }
}

Tambahkan metrics[]=track-listeners-daily pada panggilan yang sama untuk mendapatkan data pendengar sekaligus streams. Bila Anda hanya membutuhkan satu track di album itu, hilangkan UPC-nya lalu kirim filter[isrc] track tersebut. Dengan begitu, semua endpoint analytics hanya melaporkan rekaman tersebut.

Terkait

• API Analytics: platform, ketersediaan, dan batasan — platform mana melaporkan metrik apa, irama pelaporan, dan batas rentang tanggal
• Ikhtisar API dan Panduan Cepat — autentikasi, sandbox, dan referensi endpoint lengkap
• Analytics — data yang sama di dashboard
• Hubungkan Asisten AI Anda ke LabelGrid (MCP) — tanyakan analytics Anda dalam bahasa alami