지표의 플랫폼 지원 여부 (API)

LabelGrid 공개 API를 통해 스트리밍 분석을 요청하고 단일 플랫폼으로 필터링하면, 응답은 해당 플랫폼이 요청한 지표를 실제로 보고하는지 알려줍니다. 이를 통해 통합 시스템이 “아직 데이터 없음”과 “이 플랫폼은 이 지표를 보고하지 않음”을 구분할 수 있습니다.

availability 필드

임의의 분석 요청에 플랫폼 필터(예: filter[platform]=SPOTIFY)를 추가하면, 응답에는 기존 data 옆에 availability 필드가 포함됩니다.

• available — 플랫폼이 이 지표를 보고합니다. data는 정상적으로 채워집니다.
• not_available_for_platform — 플랫폼이 이 지표를 보고하지 않습니다. data는 비어 있는 상태로 반환됩니다. 이는 오류가 아니라 예상된 동작입니다.

availability 필드는 단일 플랫폼으로 필터링할 때만 나타납니다. 플랫폼 필터가 없는 요청은 availability 키 없이 이전과 똑같이 data를 반환합니다.

data의 형태는 변경되지 않습니다. availability가 그 옆에 추가되므로 기존 통합은 수정 없이 계속 동작합니다.

단일 지표 엔드포인트

각 단일 분석 엔드포인트는 data 옆에 최상위 availability 값을 하나 반환합니다.

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

분석 요약 엔드포인트

/애널리틱스/summary 엔드포인트는 여러 섹션을 한 번에 반환합니다. 섹션마다 항목이 하나씩 있는 병렬 availability 맵을 함께 제공하므로, 플랫폼이 어떤 섹션을 보고하고 어떤 섹션이 비어서 반환되는지 알 수 있습니다.

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

어떤 플랫폼이 어떤 지표를 보고하는가

플랫폼 (filter[platform])	보고되는 지표
SPOTIFY	모든 분석 지표
APPLE_MUSIC (ITUNES도 허용됨)	스트림, 청취자, 국가별 스트림, 성별 스트림, 연령별 스트림

Apple Music의 경우 이 목록에 없는 지표는 빈 data와 함께 not_available_for_platform을 반환합니다. Spotify는 모든 분석 지표를 보고합니다.

통합에서 처리하는 방법

• 비어 있는 data를 “활동 없음”으로 간주하기 전에 availability를 확인하세요. not_available_for_platform과 함께 반환된 빈 결과는 플랫폼이 그 지표를 전혀 보고하지 않는다는 의미입니다.
• /애널리틱스/summary를 통해 여러 지표를 한 번에 요청할 때는 각 섹션에 대해 availability 맵의 해당 키를 확인하세요.
• 플랫폼으로 필터링하지 않으면 availability 필드가 없습니다. 응답은 이전과 똑같이 모든 플랫폼을 합친 통합 뷰입니다.

관련 문서

• API 개요 — 인증, 엔드포인트 및 전체 레퍼런스
• 분석 — 분석 대시보드와 각 탭이 표시하는 내용