애널리틱스 API: 범위 필터와 트랙별 데이터

모든 애널리틱스 요청은 카탈로그의 일부를 대상으로 하고, 그 대상 전체를 하나로 집계한 결과를 돌려줍니다. 이 두 가지가 겹치면서 혼동이 생깁니다. 앨범 UPC로 필터링하면 그 앨범에 실린 트랙별 행이 아니라 앨범 전체의 수치가 나오거든요. 이 문서는 대상 범위를 정하는 필터, 집계가 결과를 어떻게 바꾸는지, 그리고 범위를 트랙 단위로 쪼개 주는 두 엔드포인트를 다룹니다.

범위 필터

애널리틱스 요청을 카탈로그의 일부로 좁히는 필터는 네 가지입니다. GET /애널리틱스/summary, 독립 시리즈 및 인구통계 엔드포인트, 그리고 GET /애널리틱스/leaderboards와 /애널리틱스/placements에서 사용할 수 있습니다.

필터	타입	해석되는 트랙
filter[release_id]	정수	해당 릴리스의 모든 트랙
filter[isrc]	문자열	그 ISRC를 가진 음원 하나
filter[upc]	문자열	그 바코드를 가진 릴리스의 모든 트랙
filter[artist_names][]	문자열 배열	카탈로그에서 해당 아티스트로 크레딧된 모든 트랙

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

네 가지를 모두 생략하면 요청은 접근 가능한 카탈로그 전체를 대상으로 합니다. 모든 애널리틱스 호출의 기본 범위입니다.

적용되는 필터는 하나뿐

네 필터는 release_id, isrc, upc, artist_names[] 순의 고정된 순서로 해석되며, 요청에 들어 있는 것 중 가장 앞선 하나만 적용됩니다. filter[release_id]와 filter[upc]를 함께 보내도 교집합이 되지는 않고 UPC가 무시됩니다. 의도한 필터 하나만 보내세요.

식별자가 내 것이 아닐 때

릴리스 수준의 세 필터는 식별자가 내 카탈로그 안에서 해석되지 않을 때 서로 다르게 반응합니다.

• **filter[release_id]**은 오류를 냅니다. 해당 릴리스가 없으면 404, 있지만 내 것이 아니면 403입니다.
• **filter[isrc]와 filter[upc]**는 빈 범위로 해석되어, 요청은 성공하고 data만 비어 있습니다.

그래서 사용자가 입력한 식별자로 API를 호출할 때는 404를 기다리지 말고 data가 비어 있는지를 확인해야 합니다.

내 레이블 하나로 좁히기

GET /애널리틱스/summary와 GET /애널리틱스/leaderboards는 **filter[label_id]**도 받습니다. 요청을 내 레이블 중 하나로 좁혀 주는 필터예요. 존재하지 않는 레이블은 404, 내 소유가 아닌 레이블은 403을 반환합니다. 범위를 좁힐 수만 있을 뿐, 범위를 넓히는 값은 없습니다.

스토어 기준으로 좁히려면 filter[platform]을 사용하세요. 허용되는 값과 섹션별·플랫폼별 매트릭스는 애널리틱스 API: 플랫폼, 가용성, 한도를 참고하세요.

범위 하나에 시리즈 하나

시리즈 엔드포인트와 /애널리틱스/summary의 각 섹션은 해석된 범위 전체를 집계합니다. 일간 시리즈는 날짜와 플랫폼으로 묶어 범위 안의 모든 트랙을 합산하므로, 돌아오는 행 수는 보고한 날짜와 플랫폼의 개수로 결정됩니다. 필터에 걸린 트랙이 몇 개인지는 영향을 주지 않아요.

GET /애널리틱스/streams?filter[start_date]=2026-06-01&filter[end_date]=2026-06-02&filter[upc]=0123456789012

{
  "data": [
    { "date": "2026-06-01", "platform": "SPOTIFY", "total": 1804 },
    { "date": "2026-06-01", "platform": "DEEZER", "total": 96 },
    { "date": "2026-06-02", "platform": "SPOTIFY", "total": 1731 }
  ]
}

12곡짜리 앨범이든 싱글이든 응답 모양은 같습니다. 각 행의 total은 그 날짜와 그 플랫폼에서 범위 전체가 기록한 수치이며, 앨범에 트랙이 두 개든 스무 개든 값은 달라지지 않습니다.

인구통계 엔드포인트도 차원만 하나 바뀔 뿐 방식은 같습니다. /애널리틱스/streams-by-country는 국가로 묶어 범위 전체를 합산하므로, UPC로 필터링한 호출은 트랙별이 아니라 앨범 단위의 국가 분포를 돌려줍니다. /애널리틱스/summary의 모든 섹션이 같은 규칙을 따르며, 아래에서 다루는 두 섹션만 예외입니다.

참고

이는 의도된 동작이며 우회해야 할 제약이 아닙니다. 요청으로 바꿀 수 있는 부분도 없습니다. 시리즈 엔드포인트에는 “트랙별로 묶기” 같은 파라미터가 없어요. 트랙별 수치는 아래 두 엔드포인트에서 얻습니다.

트랙별 수치 얻기

원하는 것	얻는 방법
트랙 하나의 모든 지표	아무 애널리틱스 엔드포인트에나 filter[isrc]
기간별 트랙 합계를 순위로	GET /애널리틱스/leaderboards?type=tracks
트랙별 일간 시리즈	metrics[]=track-streams-daily를 지정한 GET /애널리틱스/summary

트랙별 합계: 리더보드 엔드포인트

GET /애널리틱스/leaderboards는 지정한 윈도우의 스트림 합계를 기준으로 카탈로그의 순위를 매깁니다. 애널리틱스 대시보드의 Top performers 카드에 해당하는 API입니다.

type은 필수이며 artists, tracks, albums, all(세 목록을 한 번에) 중 하나를 받습니다. 범위 필터는 시리즈에서와 똑같이 작동하므로, type=tracks에 filter[upc]를 더하면 그 앨범의 트랙만 나옵니다.

GET /애널리틱스/leaderboards?type=tracks&filter[start_date]=2026-06-01&filter[end_date]=2026-06-30&filter[upc]=0123456789012&limit=50

트랙 행에는 name, artistName, streams, release_id, identifier(플랫폼 식별자이며, 행이 둘 이상의 플랫폼에 걸쳐 있으면 null), isrc(그 행의 스트림이 속한 음원)가 담깁니다. 행은 스트림이 많은 순으로 정렬되어 돌아옵니다.

isrc는 그 행이 하나의 음원이라고 분명히 말할 수 있을 때 담깁니다. 같은 음원을 여러 플랫폼이 각자의 identifier로 보고하는 경우에도 마찬가지이며, 여러 서비스에 올라간 트랙에서는 이런 경우가 일반적입니다. 행이 음원 하나를 가리킨다고 확인할 수 없으면 null이 됩니다. 카탈로그 전체를 이름 기준으로 순위를 매기는 필터 없는 조회, filter[artist_names][]만으로 좁힌 행, 같은 제목과 같은 아티스트가 서로 다른 음원 두 개에 걸치는 행이 그렇습니다. null은 그 행에 연결할 음원이 하나로 정해지지 않는다는 뜻이지, 그 음원에 ISRC가 없다는 뜻이 아닙니다. isrc와 identifier는 서로 독립적인 값으로 읽으세요. 한쪽이 null이어도 다른 쪽에는 값이 들어올 수 있습니다. 모든 행에 ISRC가 필요하다면 아래의 트랙별 일간 섹션을 사용하세요.

미리 감안해야 할 한도가 두 가지 있습니다.

• limit의 기본값은 10이고 50을 넘을 수 없습니다. 트랙이 50개가 넘는 앨범은 이 엔드포인트로 전부 나열할 수 없습니다. 대신 트랙별 일간 섹션을 사용해 행을 직접 합산하세요.
• 윈도우는 180일을 넘을 수 없습니다. 시리즈 엔드포인트가 허용하는 400일보다 좁습니다. 짧은 윈도우 여러 개를 이어 붙여도 더 긴 기간의 순위는 재구성되지 않습니다. 각 달의 상위 10개를 모아도 분기의 상위 10개가 되지는 않으니까요.

트랙별 일간 시리즈: summary의 두 섹션

GET /애널리틱스/summary에는 릴리스 전체 합계 대신 트랙을 하나씩 나눠 보고하는 섹션이 두 개 있습니다.

섹션	행 구조	보고하는 플랫폼
track-streams-daily	{ date, platform, isrc, streams }	모든 플랫폼
track-listeners-daily	{ date, platform, isrc, listeners }	Spotify, Apple Music, Amazon Music

두 섹션 모두 직접 요청해야 계산됩니다. metrics[]에 이름을 넣었을 때만 계산되고, filter[release_id], filter[isrc], filter[upc] 중 하나가 반드시 있어야 합니다. 릴리스나 트랙 필터 없이 이름만 넣으면 metrics에 오류가 붙은 422가 반환됩니다. 아티스트 이름 필터로는 이 조건이 충족되지 않습니다.

행은 날짜, 플랫폼, ISRC 순으로 정렬되며, 활동이 없는 날은 0이 아니라 행 자체가 없습니다. 리스너 수치는 하루 단위 집계라 날짜별로 더할 수 없습니다. 같은 사람이 이틀에 걸쳐 들었다면 각 날에 한 명씩으로 잡힙니다.

주의

트랙 × 일수 × 플랫폼이 너무 커지는 요청에는 날짜 범위를 좁히거나, filter[platform]을 지정하거나, filter[isrc]로 트랙 하나만 남기라는 422가 반환됩니다. 범위를 잘라내지 않고 요청 자체를 거부하기 때문에, 잘린 시리즈가 완전한 것처럼 차트에 올라가는 일은 없습니다.

실전 예시: 앨범의 트랙별 스트림

UPC가 0123456789012인 앨범이 있고, 6월 수치를 트랙별로 나눠 보고 싶다고 하죠.

트랙별 합계를 순위로 보려면 리더보드 엔드포인트에 그 앨범의 트랙을 요청하세요.

GET /애널리틱스/leaderboards?type=tracks&filter[start_date]=2026-06-01&filter[end_date]=2026-06-30&filter[upc]=0123456789012&limit=50

{
  "data": [
    { "name": "Nine Roses", "artistName": "Wiguez", "streams": 41208, "release_id": 88213, "identifier": "3n2f9xk2p1", "isrc": "USABC2600001" },
    { "name": "Harbour Lights", "artistName": "Wiguez", "streams": 18740, "release_id": 88213, "identifier": "7b1q4mz8v2", "isrc": "USABC2600002" }
  ],
  "meta": { "type": "tracks", "start_date": "2026-06-01", "end_date": "2026-06-30", "limit": 50 }
}

트랙마다 날짜별 시리즈를 보려면 summary 엔드포인트에서 트랙별 섹션을 요청하세요.

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

{
  "data": {
    "track-streams-daily": [
      { "date": "2026-06-01", "platform": "SPOTIFY", "isrc": "USABC2600001", "streams": 1412 },
      { "date": "2026-06-01", "platform": "DEEZER", "isrc": "USABC2600001", "streams": 78 },
      { "date": "2026-06-01", "platform": "SPOTIFY", "isrc": "USABC2600002", "streams": 392 }
    ]
  }
}

같은 호출에 metrics[]=track-listeners-daily를 추가하면 스트림과 함께 리스너도 볼 수 있습니다. 앨범에서 트랙 하나만 필요하다면 UPC를 빼고 그 트랙의 filter[isrc]를 넣으세요. 그러면 모든 애널리틱스 엔드포인트가 그 음원만을 보고합니다.

관련

• 애널리틱스 API: 플랫폼, 가용성, 한도 — 어떤 플랫폼이 어떤 지표를 보고하는지, 보고 주기, 날짜 범위 한도
• API 개요 및 빠른 시작 — 인증, 샌드박스, 전체 엔드포인트 레퍼런스
• 애널리틱스 — 같은 데이터를 대시보드에서
• AI 어시스턴트를 LabelGrid에 연결하기 (MCP) — 자연어로 애널리틱스 조회하기