API de Analytics: plataformas, disponibilidade e limites

A API pública do LabelGrid serve analytics de streaming por GET /analytics/summary (um endpoint composto que retorna as seções que você seleciona) e endpoints de séries independentes como GET /analytics/streams. Esta página cobre o conjunto de plataformas, como descobrir o que cada plataforma reporta, a cadência de reporte e os limites das requisições.

Plataformas suportadas

filter[platform] aceita dez valores cobrindo nove lojas:

SPOTIFY, APPLE_MUSIC (ITUNES é aceito como alias da mesma loja), DEEZER, BOOMPLAY, AWA, AUDIOMACK, KUGOU, KUWO, QQMUSIC

Omita filter[platform] para receber a visão combinada de todas as plataformas para as quais sua conta tem dados.

Descobrindo a disponibilidade: GET /analytics/availability

Nem toda plataforma reporta todas as métricas. O endpoint de descoberta de disponibilidade retorna o quadro completo em uma chamada:

GET /analytics/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 — todas as chaves de seção de analytics, em ordem canônica. Esta lista é a autoridade: é o mesmo conjunto que metrics[] aceita em /analytics/summary.
• platforms — todos os valores que filter[platform] aceita.
• availability — indexado por seção e depois por plataforma. Cada célula é available ou not_available_for_platform.
• platform_cadence — daily ou weekly por plataforma (veja Cadência de reporte).

A resposta é configuração estática — não depende da sua conta, de um intervalo de datas nem de nenhum filtro — então busque uma vez e mantenha em cache. Não aceita parâmetros e usa a mesma autenticação e os mesmos limites de taxa dos outros endpoints /analytics/*.

O campo availability em requisições filtradas

Quando você filtra uma requisição de analytics por uma única plataforma (por exemplo filter[platform]=DEEZER), a resposta também carrega um campo availability ao lado de data:

• available — a plataforma reporta esta métrica; data é preenchido normalmente.
• not_available_for_platform — a plataforma não reporta esta métrica; data fica vazio. É o comportamento esperado, não um erro.

Os endpoints independentes carregam um único valor de nível superior; /analytics/summary carrega um mapa com uma entrada por seção solicitada. Requisições sem filtro de plataforma não carregam campo availability. Sempre leia availability antes de tratar um data vazio como “sem atividade”.

O que as plataformas reportam

A matriz de relance (chame o endpoint para a versão atual e autoritativa):

Seções	Plataformas que as reportam
streams	Todas as nove plataformas
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, seções de dimensões da Apple	APPLE_MUSIC
Composição de audiência de listeners e seções per-stream (listener-plan-mix, avg-listen-time, hour-of-day, …)	SPOTIFY
Placements (GET /analytics/placements)	SPOTIFY, APPLE_MUSIC, DEEZER

Uma nota sobre a semântica de listeners: Spotify e Apple Music reportam uma contagem diária de listeners sem duplicatas por faixa. O número diário do Audiomack é a soma das contagens reportadas por país e nível de assinatura, então um listener ativo em mais de um segmento no mesmo dia contribui mais de uma vez.

Cadência de reporte: plataformas diárias e semanais

Toda resposta de GET /analytics/summary carrega um mapa meta.platform_cadence indicando com que frequência cada plataforma reporta:

• daily — um relatório por dia: SPOTIFY, APPLE_MUSIC, DEEZER, BOOMPLAY, AWA, AUDIOMACK
• weekly — um relatório por semana: KUGOU, KUWO, QQMUSIC

Uma plataforma semanal produz um ponto de dados por faixa por semana, datado no dia que o relatório cobre e carregando o total daquela semana. O total nunca é dividido pelos sete dias. Em uma série diária você verá uma data preenchida por semana, sem linhas nas datas intermediárias.

Trate isso no seu consumidor lendo platform_cadence em vez de inferir a cadência pelo espaçamento das datas:

• Não trate o intervalo entre dois pontos semanais como dados faltando.
• Não divida um ponto semanal em uma média diária.
• Somar os pontos como estão ainda dá o total correto de qualquer intervalo.

A cadência é distinta de meta.section_granularity, que indica como os pontos de uma série retornada são datados (day ou week). Uma resposta pode carregar granularidade "day" e cadência "weekly" ao mesmo tempo — pontos datados por dia, um por semana.

Selecionando seções: metrics[] em /analytics/summary

metrics[] é obrigatório em GET /analytics/summary: nomeie as seções que você quer, de 1 até 12 por requisição.

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

Solicitar mais de 12 chaves retorna um 422 pedindo para dividir a seleção. Cada projeção é mantida em cache de forma independente por escopo e janela, então dividir uma seleção grande em várias requisições sai barato em chamadas repetidas. As chaves de seção válidas são a lista sections de GET /analytics/availability; uma requisição metrics[] inválida também as enumera na mensagem de erro.

Limites de intervalo de datas

GET /analytics/summary e os endpoints independentes de séries e demografia aceitam um intervalo de datas de até 400 dias — o suficiente para um ano inteiro mais um período de comparação em uma única requisição. Um intervalo acima do limite retorna um 422 cuja mensagem de erro informa o limite.

Família de endpoints	Intervalo máximo
/analytics/summary e endpoints independentes de séries/demografia	400 dias
/analytics/leaderboards, /analytics/placements	180 dias

Os endpoints de ranking mantêm seu próprio limite de 180 dias — e note que combinar várias janelas top-N mais curtas não reconstrói o top-N de um período mais longo.

Dois comportamentos a mais chegam com a janela de 400 dias:

• Requisições que abrangem mais de 90 dias são medidas contra um segundo limite de taxa mais baixo, além do limite padrão de analytics (30/minuto por conta contra o padrão de 60; os orçamentos por IP de saída de parceiros são reduzidos à metade da mesma forma). Requisições de 90 dias ou menos não são afetadas. Exceder qualquer um dos limites retorna 429 com os cabeçalhos habituais Retry-After e X-RateLimit-*.
• Um intervalo dentro do limite ainda pode ser pesado demais para calcular — por exemplo, um catálogo muito grande na janela completa com muitas metrics[]. Isso retorna 422 com uma mensagem de “reduza o intervalo de datas”. Trate como algo que pode ser tentado de novo: repita com um intervalo mais curto ou menos seções. Um erro de servidor não relacionado ainda retorna 500, então um 422 aqui significa de forma confiável “esta requisição era grande demais”.

Relacionado

• Visão geral da API — autenticação, endpoints e a referência completa <<<<<<< HEAD
• Analytics — o painel de analytics e o que cada aba mostra =======
• Analytics — o dashboard de analytics e o que cada visualização mostra
• Conecte seu assistente de IA ao LabelGrid (MCP) — consulte seus analytics em linguagem natural

origin/main