플랫폼으로 필터링하면 애널리틱스 지표가 왜 비어 있나요?

모든 플랫폼이 모든 지표를 보고하지는 않습니다. 애널리틱스 요청을 플랫폼으로 필터링하면 응답에 availability 필드가 포함됩니다. not_available_for_platform이면 그 플랫폼이 해당 지표를 보고하지 않아 데이터가 비어 있는 것으로, 정상 동작이며 오류가 아닙니다. GET /애널리틱스/availability를 호출하면 섹션별·플랫폼별 전체 매트릭스를 볼 수 있습니다.

플랫폼이 API로 어떤 애널리틱스 지표를 지원하는지 어떻게 알 수 있나요?

GET /애널리틱스/availability를 호출하세요. 모든 애널리틱스 섹션과 모든 플랫폼의 전체 매트릭스와 각 플랫폼의 보고 주기를 캐시 가능한 정적 호출 한 번으로 돌려줍니다. 플랫폼으로 필터링한 요청에서는 같은 정보가 data 옆의 availability 필드로 나타납니다.

플랫폼의 애널리틱스 데이터 포인트가 왜 주당 하나만 표시되나요?

Kugou, Kuwo, QQ Music은 일간이 아니라 주간으로 보고합니다. 매주 트랙당 하나의 데이터 포인트가 생성되며, 보고서가 다루는 날짜로 기록되고 그 주 전체 합계를 담습니다. 주간 포인트 사이의 공백은 누락 데이터가 아니며, 포인트를 합산하면 범위의 정확한 합계가 나옵니다. 어떤 플랫폼이 주간 보고인지는 meta.platform_cadence나 GET /애널리틱스/availability로 확인하세요.

애널리틱스 API: 플랫폼, 가용성, 한도

LabelGrid 퍼블릭 API는 GET /애널리틱스/summary(선택한 섹션을 돌려주는 복합 엔드포인트)와 GET /애널리틱스/streams 같은 독립 시리즈 엔드포인트로 스트리밍 애널리틱스를 제공합니다. 이 페이지는 플랫폼 목록, 각 플랫폼이 보고하는 항목을 알아내는 방법, 보고 주기, 요청 한도를 다룹니다.

지원 플랫폼

filter[platform]은 아홉 개 스토어를 아우르는 열 개 값을 받습니다.

SPOTIFY, APPLE_MUSIC(ITUNES는 같은 스토어의 별칭으로 허용), DEEZER, BOOMPLAY, AWA, AUDIOMACK, KUGOU, KUWO, QQMUSIC

filter[platform]을 생략하면 계정에 데이터가 있는 모든 플랫폼을 합친 보기가 반환됩니다.

가용성 알아보기: `GET /애널리틱스/availability`

모든 플랫폼이 모든 지표를 보고하지는 않습니다. 가용성 디스커버리 엔드포인트는 전체 그림을 한 번의 호출로 돌려줍니다.

GET /애널리틱스/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 — 모든 애널리틱스 섹션 키(정식 순서). 이 목록이 기준이며, /애널리틱스/summary의 metrics[]가 받는 것과 같은 집합입니다.
platforms — filter[platform]이 받는 모든 값.
availability — 섹션, 그다음 플랫폼으로 인덱싱됩니다. 각 셀은 available 또는 not_available_for_platform입니다.
platform_cadence — 플랫폼별 daily 또는 weekly(보고 주기 참고).

응답은 정적 구성입니다. 계정, 날짜 범위, 필터에 의존하지 않으므로 한 번 가져와 캐시하면 됩니다. 파라미터를 받지 않으며 다른 /애널리틱스/* 엔드포인트와 같은 인증과 속도 제한을 사용합니다.

필터링된 요청의 `availability` 필드

애널리틱스 요청을 단일 플랫폼으로 필터링하면(예: filter[platform]=DEEZER) 응답의 data 옆에 availability 필드도 붙습니다.

available — 플랫폼이 이 지표를 보고하며 data가 정상적으로 채워집니다.
not_available_for_platform — 플랫폼이 이 지표를 보고하지 않아 data가 비어 있습니다. 정상 동작이며 오류가 아닙니다.

독립 엔드포인트는 최상위 값 하나를, /애널리틱스/summary는 요청한 섹션마다 항목이 있는 맵을 갖습니다. 플랫폼 필터가 없는 요청에는 availability 필드가 없습니다. 빈 data를 “활동 없음”으로 해석하기 전에 항상 availability를 확인하세요.

플랫폼이 보고하는 항목

매트릭스 요약입니다(기준이 되는 최신 버전은 엔드포인트를 호출해 확인하세요).

섹션	보고하는 플랫폼
`streams`	아홉 개 플랫폼 전부
`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`, Apple 차원 섹션	`APPLE_MUSIC`
리스너 구성 및 스트림 단위 섹션(`listener-plan-mix`, `avg-listen-time`, `hour-of-day` 등)	`SPOTIFY`
Placements(`GET /애널리틱스/placements`)	`SPOTIFY`, `APPLE_MUSIC`, `DEEZER`

리스너 의미에 대한 참고: Spotify와 Apple Music은 트랙별로 중복을 제거한 일일 리스너 수를 보고합니다. Audiomack의 일일 수치는 국가·구독 등급별 보고 수를 합산한 값이라, 같은 날 여러 조각에서 활동한 리스너는 여러 번 반영됩니다.

보고 주기: 일간 및 주간 플랫폼

모든 GET /애널리틱스/summary 응답에는 각 플랫폼의 보고 빈도를 알려주는 meta.platform_cadence 맵이 붙습니다.

daily — 하루 한 번 보고: SPOTIFY, APPLE_MUSIC, DEEZER, BOOMPLAY, AWA, AUDIOMACK
weekly — 주 한 번 보고: KUGOU, KUWO, QQMUSIC

주간 플랫폼은 보고서가 다루는 날짜로 기록되고 그 주 전체 합계를 담은 트랙당 주 하나의 데이터 포인트를 생성합니다. 합계가 7일로 나뉘는 일은 없습니다. 일간 시리즈에서는 주당 하나의 날짜만 채워지고 그 사이 날짜에는 행이 없습니다.

날짜 간격에서 주기를 추측하지 말고 platform_cadence를 읽어서 처리하세요.

두 주간 포인트 사이의 공백을 누락 데이터로 취급하지 마세요.
주간 포인트를 일일 평균으로 나누지 마세요.
포인트를 그대로 합산하면 어떤 범위든 정확한 합계가 나옵니다.

주기는 **meta.section_granularity**와 다릅니다. 후자는 반환된 시리즈의 포인트가 어떻게 날짜 지정되는지(day 또는 week)를 나타냅니다. 하나의 응답이 세분화 "day"와 주기 "weekly"를 동시에 가질 수 있어요. 날짜는 일 단위, 포인트는 주당 하나라는 뜻입니다.

섹션 선택: `/애널리틱스/summary`의 `metrics[]`

GET /애널리틱스/summary에서 metrics[]는 필수입니다. 원하는 섹션을 1개부터 요청당 12개까지 지정하세요.

GET /애널리틱스/summary?filter[start_date]=2026-06-01&filter[end_date]=2026-06-30&metrics[]=streams&metrics[]=listeners

12개를 넘는 키를 요청하면 선택을 나누라는 422가 반환됩니다. 각 프로젝션은 범위와 윈도우별로 독립적으로 캐시되므로, 큰 선택을 여러 요청으로 나눠도 반복 호출 비용은 낮습니다. 유효한 섹션 키는 GET /애널리틱스/availability의 sections 목록이며, 잘못된 metrics[] 요청의 오류 메시지에도 나열됩니다.

날짜 범위 한도

GET /애널리틱스/summary와 독립 시리즈/인구통계 엔드포인트는 최대 400일의 날짜 범위를 받습니다. 한 번의 요청으로 만 1년에 비교 기간까지 담을 수 있어요. 한도를 넘는 범위는 422를 반환하며, 오류 메시지에 한도가 표시됩니다.

엔드포인트 계열	최대 범위
`/애널리틱스/summary` 및 독립 시리즈/인구통계 엔드포인트	400일
`/애널리틱스/leaderboards`, `/애널리틱스/placements`	180일

랭킹 엔드포인트는 자체 180일 한도를 유지합니다. 짧은 top-N 윈도우 여러 개를 합쳐도 더 긴 기간의 top-N은 재구성되지 않는다는 점도 참고하세요.

400일 윈도우와 함께 두 가지 동작이 더 추가됩니다.

<<<<<<< HEAD

API 개요 — 인증, 엔드포인트 및 전체 레퍼런스
분석 — 분석 대시보드와 각 탭이 표시하는 내용 =======
90일을 넘는 요청은 표준 애널리틱스 한도에 더해 두 번째의 더 낮은 속도 제한에도 집계됩니다(계정당 분당 30, 표준은 60. 파트너 이그레스 IP 예산도 같은 방식으로 절반). 90일 이하 요청은 영향이 없습니다. 어느 한도든 초과하면 일반적인 Retry-After 및 X-RateLimit-* 헤더와 함께 429가 반환됩니다.
한도 안의 범위라도 계산하기에 너무 무거울 수 있습니다. 예를 들어 매우 큰 카탈로그를 전체 윈도우에 많은 metrics[]로 요청하는 경우입니다. 이때 “날짜 범위를 좁히세요” 메시지와 함께 422가 반환됩니다. 재시도 가능한 상황으로 다루고, 더 짧은 범위나 더 적은 섹션으로 다시 시도하세요. 무관한 서버 오류는 여전히 500을 반환하므로, 여기서의 422는 “이 요청이 너무 컸다”는 뜻으로 믿을 수 있습니다.