API Analytics: platform, ketersediaan, dan batasan

API publik LabelGrid menyajikan analytics streaming melalui GET /analitik/summary (endpoint komposit yang mengembalikan bagian-bagian yang Anda pilih) dan endpoint seri mandiri seperti GET /analitik/streams. Halaman ini mencakup kumpulan platform, cara mengetahui apa yang dilaporkan setiap platform, irama pelaporan, dan batasan permintaan.

Platform yang didukung

filter[platform] menerima sepuluh nilai yang mencakup sembilan toko:

SPOTIFY, APPLE_MUSIC (ITUNES diterima sebagai alias untuk toko yang sama), DEEZER, BOOMPLAY, AWA, AUDIOMACK, KUGOU, KUWO, QQMUSIC

Hilangkan filter[platform] untuk menerima tampilan gabungan semua platform yang datanya dimiliki akun Anda.

Menemukan ketersediaan: GET /analitik/availability

Tidak semua platform melaporkan semua metrik. Endpoint penemuan ketersediaan mengembalikan gambaran lengkap dalam satu panggilan:

GET /analitik/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 — setiap kunci bagian analytics, dalam urutan kanonis. Daftar ini yang berwenang: kumpulan yang sama dengan yang diterima metrics[] pada /analitik/summary.
• platforms — setiap nilai yang diterima filter[platform].
• availability — diindeks per bagian, lalu per platform. Setiap sel bernilai available atau not_available_for_platform.
• platform_cadence — daily atau weekly per platform (lihat Irama pelaporan).

Responsnya adalah konfigurasi statis — tidak bergantung pada akun Anda, rentang tanggal, atau filter apa pun — jadi ambil sekali dan simpan di cache. Tidak menerima parameter dan memakai autentikasi serta batas laju yang sama dengan endpoint /analitik/* lainnya.

Bidang availability pada permintaan yang difilter

Saat Anda memfilter permintaan analytics ke satu platform (misalnya filter[platform]=DEEZER), respons juga membawa bidang availability di samping data:

• available — platform melaporkan metrik ini; data terisi seperti biasa.
• not_available_for_platform — platform tidak melaporkan metrik ini; data kosong. Ini perilaku yang diharapkan, bukan error.

Endpoint mandiri membawa satu nilai tingkat atas; /analitik/summary membawa map dengan satu entri per bagian yang diminta. Permintaan tanpa filter platform tidak membawa bidang availability. Selalu baca availability sebelum menganggap data kosong sebagai “tidak ada aktivitas”.

Apa yang dilaporkan platform

Matriks secara sekilas (panggil endpoint untuk versi terkini yang berwenang):

Bagian	Platform yang melaporkannya
streams	Kesembilan platform
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, bagian dimensi Apple	APPLE_MUSIC
Komposisi audiens pendengar dan bagian per-stream (listener-plan-mix, avg-listen-time, hour-of-day, …)	SPOTIFY
Placements (GET /analitik/placements)	SPOTIFY, APPLE_MUSIC, DEEZER

Catatan tentang semantik listeners: Spotify dan Apple Music melaporkan jumlah pendengar harian per track tanpa duplikasi. Angka harian Audiomack adalah jumlah dari hitungan yang dilaporkan per negara dan tingkat langganan, sehingga pendengar yang aktif di lebih dari satu segmen pada hari yang sama berkontribusi lebih dari sekali.

Irama pelaporan: platform harian dan mingguan

Setiap respons GET /analitik/summary membawa map meta.platform_cadence yang menyatakan seberapa sering setiap platform melapor:

• daily — satu laporan per hari: SPOTIFY, APPLE_MUSIC, DEEZER, BOOMPLAY, AWA, AUDIOMACK
• weekly — satu laporan per minggu: KUGOU, KUWO, QQMUSIC

Platform mingguan menghasilkan satu titik data per track per minggu, bertanggal pada hari yang dicakup laporan dan membawa total minggu itu. Total tidak pernah dibagi ke tujuh hari. Pada seri harian Anda akan melihat satu tanggal terisi per minggu, tanpa baris pada tanggal-tanggal di antaranya.

Tangani ini di konsumen Anda dengan membaca platform_cadence alih-alih menyimpulkan irama dari jarak antar tanggal:

• Jangan perlakukan celah antara dua titik mingguan sebagai data yang hilang.
• Jangan bagi titik mingguan menjadi rata-rata harian.
• Menjumlahkan titik-titik apa adanya tetap memberi total yang benar untuk rentang apa pun.

Irama berbeda dari meta.section_granularity, yang menyatakan bagaimana titik-titik sebuah seri diberi tanggal (day atau week). Sebuah respons bisa membawa granularitas "day" dan irama "weekly" sekaligus — titik bertanggal harian, satu per minggu.

Memilih bagian: metrics[] pada /analitik/summary

metrics[] wajib pada GET /analitik/summary: sebutkan bagian yang Anda inginkan, dari 1 hingga 12 per permintaan.

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

Meminta lebih dari 12 kunci mengembalikan 422 yang meminta Anda membagi pilihan. Setiap proyeksi di-cache secara independen per cakupan dan jendela, jadi membagi pilihan besar menjadi beberapa permintaan murah pada panggilan berulang. Kunci bagian yang valid adalah daftar sections dari GET /analitik/availability; permintaan metrics[] yang tidak valid juga mencantumkannya di pesan error.

Batasan rentang tanggal

GET /analitik/summary serta endpoint seri dan demografi mandiri menerima rentang tanggal hingga 400 hari — cukup untuk satu tahun penuh plus periode pembanding dalam satu permintaan. Rentang yang melebihi batas mengembalikan 422 dengan pesan error yang menyebutkan batasnya.

Keluarga endpoint	Rentang maksimum
/analitik/summary dan endpoint seri/demografi mandiri	400 hari
/analitik/leaderboards, /analitik/placements	180 hari

Endpoint peringkat mempertahankan batas 180 harinya sendiri — dan ingat, menggabungkan beberapa jendela top-N pendek tidak merekonstruksi top-N untuk periode yang lebih panjang.

Dua perilaku lagi hadir bersama jendela 400 hari:

• Permintaan yang mencakup lebih dari 90 hari diukur terhadap batas laju kedua yang lebih rendah, di samping batas analytics standar (30/menit per akun dibanding standar 60; anggaran per IP egress partner juga dibagi dua dengan cara yang sama). Permintaan 90 hari atau kurang tidak terpengaruh. Melampaui salah satu batas mengembalikan 429 dengan header Retry-After dan X-RateLimit-* yang biasa.
• Rentang di dalam batas tetap bisa terlalu berat untuk dihitung — misalnya katalog sangat besar pada jendela penuh dengan banyak metrics[]. Itu mengembalikan 422 dengan pesan “persempit rentang tanggal”. Perlakukan sebagai dapat dicoba ulang: coba lagi dengan rentang lebih pendek atau bagian lebih sedikit. Error server yang tidak terkait tetap mengembalikan 500, jadi 422 di sini secara andal berarti “permintaan ini terlalu besar”.

Terkait

• Ikhtisar API — autentikasi, endpoint, dan referensi lengkap <<<<<<< HEAD
• Analytics — dasbor analytics dan apa yang ditampilkan setiap tab =======
• Analytics — dashboard analytics dan apa yang ditampilkan setiap tampilan
• Hubungkan Asisten AI Anda ke LabelGrid (MCP) — tanyakan analytics Anda dalam bahasa alami

origin/main