Disponibilidade de métricas por plataforma (API)

Quando você solicita analytics de streaming pela API pública do LabelGrid e filtra por uma única plataforma, a resposta informa se essa plataforma realmente reporta a métrica solicitada. Isso permite que sua integração distinga entre «ainda não há dados» e «esta plataforma nunca reporta esta métrica».

O campo availability

Adicione um filtro de plataforma a qualquer solicitação de analytics — por exemplo filter[platform]=SPOTIFY — e a resposta incluirá um campo availability ao lado do habitual data:

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

O campo availability aparece somente quando você filtra por uma única plataforma. Solicitações sem filtro de plataforma retornam data exatamente como antes, sem nenhuma chave availability.

O formato de data não muda — availability é adicionado ao lado, então integrações existentes continuam funcionando sem modificação.

Endpoints de métrica individual

Cada endpoint de analytics individual retorna um único valor availability de nível superior ao lado do seu data:

{
  "availability": "not_available_for_platform",
  "data": []
}

O endpoint de resumo de analytics

O endpoint /analytics/summary retorna várias seções de uma vez. Ele carrega um mapa availability paralelo com uma entrada por seção, para que você saiba quais seções a plataforma reporta e quais voltam vazias:

{
  "availability": {
    "streams": "available",
    "listeners": "available",
    "streams_by_country": "available",
    "streams_by_gender": "available",
    "streams_by_age": "available",
    "saves": "not_available_for_platform"
  },
  "data": { }
}

Quais plataformas reportam quais métricas

Plataforma (filter[platform])	Métricas reportadas
SPOTIFY	Todas as métricas de analytics
APPLE_MUSIC (ITUNES também é aceito)	Streams, ouvintes, streams por país, streams por gênero e streams por idade

Para a Apple Music, qualquer métrica fora dessa lista retorna not_available_for_platform com data vazio. O Spotify reporta todas as métricas de analytics.

Como tratar isso na sua integração

• Leia availability antes de tratar um data vazio como «sem atividade». Um resultado vazio com not_available_for_platform significa que a plataforma não reporta essa métrica de forma alguma.
• Quando você solicita várias métricas de uma vez via /analytics/summary, verifique a chave correspondente no mapa availability para cada seção.
• Se você não filtrar por plataforma, não há campo availability — a resposta é a visão combinada de todas as plataformas, exatamente como antes.

Relacionado

• Visão geral da API — autenticação, endpoints e a referência completa
• Analytics — o painel de analytics e o que cada aba mostra