API de Analytics: plataformas, disponibilidad y límites

La API pública de LabelGrid sirve analytics de streaming a través de GET /analiticas/summary (un endpoint compuesto que devuelve las secciones que usted selecciona) y endpoints de series independientes como GET /analiticas/streams. Esta página cubre el conjunto de plataformas, cómo descubrir qué informa cada plataforma, la cadencia de informes y los límites de las solicitudes.

Plataformas admitidas

filter[platform] acepta diez valores que cubren nueve tiendas:

SPOTIFY, APPLE_MUSIC (ITUNES se acepta como alias de la misma tienda), DEEZER, BOOMPLAY, AWA, AUDIOMACK, KUGOU, KUWO, QQMUSIC

Omita filter[platform] para recibir la vista combinada de todas las plataformas para las que su cuenta tiene datos.

Descubrir la disponibilidad: GET /analiticas/availability

No todas las plataformas informan todas las métricas. El endpoint de descubrimiento de disponibilidad devuelve el panorama completo en una sola llamada:

GET /analiticas/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 las claves de sección de analytics, en orden canónico. Esta lista es la autoridad: es el mismo conjunto que metrics[] acepta en /analiticas/summary.
• platforms — todos los valores que acepta filter[platform].
• availability — indexado por sección y luego por plataforma. Cada celda es available o not_available_for_platform.
• platform_cadence — daily o weekly por plataforma (vea Cadencia de informes).

La respuesta es configuración estática — no depende de su cuenta, de un rango de fechas ni de ningún filtro — así que obténgala una vez y cachéela. No acepta parámetros y usa la misma autenticación y los mismos límites de tasa que los demás endpoints /analiticas/*.

El campo availability en solicitudes filtradas

Cuando filtra una solicitud de analytics por una sola plataforma (por ejemplo filter[platform]=DEEZER), la respuesta también incluye un campo availability junto a data:

• available — la plataforma informa esta métrica; data se rellena con normalidad.
• not_available_for_platform — la plataforma no informa esta métrica; data está vacío. Es el comportamiento esperado, no un error.

Los endpoints independientes llevan un único valor de nivel superior; /analiticas/summary lleva un mapa con una entrada por sección solicitada. Las solicitudes sin filtro de plataforma no llevan campo availability. Lea siempre availability antes de interpretar un data vacío como “sin actividad”.

Qué informan las plataformas

La matriz de un vistazo (llame al endpoint para la versión autoritativa y actual):

Secciones	Plataformas que las informan
streams	Las nueve 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, secciones de dimensiones de Apple	APPLE_MUSIC
Composición de audiencia de listeners y secciones per-stream (listener-plan-mix, avg-listen-time, hour-of-day, …)	SPOTIFY
Placements (GET /analiticas/placements)	SPOTIFY, APPLE_MUSIC, DEEZER

Una nota sobre la semántica de listeners: Spotify y Apple Music informan un recuento diario de listeners sin duplicados por track. La cifra diaria de listeners de Audiomack es la suma de los recuentos que informa por país y nivel de suscripción, de modo que un listener activo en más de un segmento el mismo día contribuye más de una vez.

Cadencia de informes: plataformas diarias y semanales

Cada respuesta de GET /analiticas/summary incluye un mapa meta.platform_cadence que indica con qué frecuencia informa cada plataforma:

• daily — un informe por día: SPOTIFY, APPLE_MUSIC, DEEZER, BOOMPLAY, AWA, AUDIOMACK
• weekly — un informe por semana: KUGOU, KUWO, QQMUSIC

Una plataforma semanal produce un punto de datos por track y por semana, fechado en el día que cubre el informe y con el total de toda esa semana. El total nunca se divide entre los siete días. En una serie diaria verá una fecha con datos por semana, sin filas en las fechas intermedias.

Gestiónelo en su integración leyendo platform_cadence en lugar de inferir la cadencia del espaciado de las fechas:

• No trate el hueco entre dos puntos semanales como datos faltantes.
• No divida un punto semanal en una media diaria.
• Sumar los puntos tal cual sigue dando el total correcto de cualquier rango.

La cadencia es distinta de meta.section_granularity, que indica cómo están fechados los puntos de una serie devuelta (day o week). Una respuesta puede llevar granularidad "day" y cadencia "weekly" al mismo tiempo — puntos fechados por día, uno por semana.

Seleccionar secciones: metrics[] en /analiticas/summary

metrics[] es obligatorio en GET /analiticas/summary: nombre las secciones que quiere, desde 1 hasta 12 por solicitud.

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

Solicitar más de 12 claves devuelve un 422 que le pide dividir la selección. Cada proyección se cachea de forma independiente por alcance y ventana, así que dividir una selección grande en varias solicitudes resulta barato en llamadas repetidas. Las claves de sección válidas son la lista sections de GET /analiticas/availability; una solicitud metrics[] inválida también las enumera en su mensaje de error.

Límites de rango de fechas

GET /analiticas/summary y los endpoints independientes de series y demografía aceptan un rango de fechas de hasta 400 días — suficiente para un año completo más un período de comparación en una sola solicitud. Un rango que supere el límite devuelve un 422 cuyo mensaje de error indica el límite.

Familia de endpoints	Rango máximo
/analiticas/summary y endpoints independientes de series/demografía	400 días
/analiticas/leaderboards, /analiticas/placements	180 días

Los endpoints de rankings mantienen su propio límite de 180 días — y tenga en cuenta que combinar varias ventanas top-N más cortas no reconstruye el top-N de un período más largo.

Dos comportamientos más llegan con la ventana de 400 días:

• Las solicitudes que abarcan más de 90 días se miden contra un segundo límite de tasa más bajo, además del límite estándar de analytics (30/minuto por cuenta frente al estándar de 60; los presupuestos por IP de salida de partners se reducen a la mitad de la misma forma). Las solicitudes de 90 días o menos no se ven afectadas. Superar cualquiera de los dos límites devuelve 429 con las cabeceras habituales Retry-After y X-RateLimit-*.
• Un rango dentro del límite puede seguir siendo demasiado pesado de calcular — por ejemplo, un catálogo muy grande con la ventana completa y muchas metrics[]. Eso devuelve 422 con un mensaje de “reduzca el rango de fechas”. Trátelo como reintentable: reintente con un rango más corto o menos secciones. Un error de servidor no relacionado sigue devolviendo 500, así que un 422 aquí significa de forma fiable “esta solicitud era demasiado grande”.

Relacionado

<<<<<<< HEAD

• Descripción general de la API — autenticación, endpoints y la referencia completa
• Analíticas — el panel de analíticas y qué muestra cada pestaña =======
• Resumen de la API — autenticación, endpoints y la referencia completa
• Analytics — el dashboard de analytics y qué muestra cada vista
• Conecte su asistente de IA a LabelGrid (MCP) — consulte sus analytics en lenguaje natural

origin/main