コンテンツにスキップ
Help Center
サポート

アナリティクス API: スコープフィルターとトラック単位のデータ

アナリティクスのリクエストは必ずカタログの一部を対象とし、その範囲全体を集計した結果を 1 つ返します。この 2 つが重なると、意外な結果になりがちです。アルバムの UPC でフィルターすると、収録トラックごとの行ではなくアルバム全体の数字が返ってきます。このページでは、スコープを決めるフィルター、集計が結果に及ぼす影響、そしてスコープをトラック単位に分解する 2 つのエンドポイントを説明します。

スコープフィルター

Section titled “スコープフィルター”

アナリティクスのリクエストをカタログの一部に絞り込むフィルターが 4 つあります。GET /アナリティクス/summary、単独のシリーズ/デモグラフィックエンドポイント、GET /アナリティクス/leaderboards と /アナリティクス/placements で使えます。

フィルター型解決されるトラック
filter[release_id]整数そのリリースの全トラック
filter[isrc]文字列その ISRC を持つ 1 つの録音
filter[upc]文字列そのバーコードを持つリリースの全トラック
filter[artist_names][]文字列の配列カタログ内でそれらのアーティストがクレジットされている全トラック
GET /アナリティクス/streams?filter[start_date]=2026-06-01&filter[end_date]=2026-06-30&filter[upc]=0123456789012

どれも指定しなければ、アクセスできるカタログ全体が対象になります。これがすべてのアナリティクス呼び出しのデフォルトのスコープです。

効くのは 1 つのフィルターだけ

Section titled “効くのは 1 つのフィルターだけ”

4 つのフィルターは release_id、isrc、upc、artist_names[] の固定順で解決され、最初に見つかったものが優先されます。filter[release_id] と filter[upc] を同時に送っても両者の積集合にはならず、UPC は無視されます。意図したフィルターだけを送ってください。

識別子が自分のカタログにない場合

Section titled “識別子が自分のカタログにない場合”

リリース単位の 3 つのフィルターは、識別子が自分のカタログで解決できないときの応答がそれぞれ異なります。

  • filter[release_id] はエラーになります。該当するリリースが存在しなければ 404、存在しても自分のものでなければ 403 です。
  • filter[isrc] と filter[upc] は空のスコープとして解決され、リクエストは成功して data が空になります。

そのため、ユーザーが入力した識別子で API を動かす場合は、404 を待つのではなく data が空かどうかを確認してください。

自分のレーベル 1 つに絞り込む

Section titled “自分のレーベル 1 つに絞り込む”

GET /アナリティクス/summary と GET /アナリティクス/leaderboards は filter[label_id] も受け付けます。リクエストを自分が保有するレーベル 1 つに絞り込むフィルターです。存在しないレーベルは 404、自分が保有していないレーベルは 403 を返します。このフィルターはスコープを狭めることしかできず、広げる値は存在しません。

ストア単位で絞り込みたい場合は filter[platform] を使います。受け付ける値とセクション別プラットフォームのマトリクスについてはアナリティクス API: プラットフォーム・可用性・上限をご覧ください。

スコープ 1 つにつき、シリーズ 1 本

Section titled “スコープ 1 つにつき、シリーズ 1 本”

シリーズと /アナリティクス/summary の各セクションは、解決されたスコープ全体を集計します。日次シリーズは date と platform でグループ化し、スコープ内のすべてのトラックの値を合計します。したがって返る行数を決めるのは、報告のあった日付とプラットフォームの数であって、フィルターに一致したトラックの数ではありません。

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 は、その日付とプラットフォームにおけるスコープ全体の数字であり、アルバムの収録曲が 2 曲でも 20 曲でも同じ値になります。

デモグラフィックエンドポイントも、軸が 1 つ変わるだけで挙動は同じです。/アナリティクス/streams-by-country は国でグループ化してスコープ全体を合計するため、UPC でフィルターするとトラックごとではなくアルバムの国別内訳が返ります。/アナリティクス/summary のすべてのセクションが同じ規則に従い、例外は後述の 2 つだけです。

トラック単位の数字を取得する

Section titled “トラック単位の数字を取得する”
欲しいもの取得先
1 つのトラックのすべてのデータ任意のアナリティクスエンドポイントで filter[isrc]
期間内のトラックごとの合計(ランキング順)GET /アナリティクス/leaderboards?type=tracks
トラックごとの日次シリーズmetrics[]=track-streams-daily を指定した GET /アナリティクス/summary

トラックごとの合計: leaderboards エンドポイント

Section titled “トラックごとの合計: leaderboards エンドポイント”

GET /アナリティクス/leaderboards は、指定したウィンドウでのストリーム数の合計でカタログをランキングします。アナリティクスダッシュボードの Top performers カードに相当する API です。

type は必須で、artists・tracks・albums・all(3 つのリストを 1 回のリクエストで取得)のいずれかを指定します。スコープフィルターはシリーズの場合とまったく同じように働くため、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 は、その行が 1 つの録音だと確実に言える場合に返ります。同じ録音を複数のプラットフォームがそれぞれ独自の identifier で報告している場合も同じで、複数のサービスで配信されているトラックではこれが通常の姿です。行が 1 つの録音を指すと確認できない場合は null になります。カタログ全体を名前で順位付けするフィルターなしの呼び出し、filter[artist_names][] だけで絞り込んだ行、同じタイトルと同じアーティストが 2 つの別々の録音にまたがる行がこれにあたります。null は、その行に結び付けられる録音が 1 つに定まらないという意味であり、その録音に ISRC がないという意味ではありません。isrc と identifier は独立したものとして扱ってください。一方が null でも、もう一方には値が入ることがあります。すべての行に ISRC が必要な場合は、下のトラックごとの日次セクションをお使いください。

あらかじめ見込んでおくべき制限が 2 つあります。

  • limit のデフォルトは 10 で、50 を超えられません。 収録曲が 50 曲を超えるアルバムは、このエンドポイントだけでは全曲を一覧できません。その場合はトラックごとの日次セクションを使い、行を自分で合計してください。
  • ウィンドウは 180 日を超えられません。 シリーズエンドポイントが許す 400 日より狭い上限です。短いウィンドウをつなぎ合わせても長い期間のランキングは再現できません。各月のトップ 10 は、四半期のトップ 10 とは別物だからです。

トラックごとの日次シリーズ: summary の 2 つのセクション

Section titled “トラックごとの日次シリーズ: summary の 2 つのセクション”

GET /アナリティクス/summary には、リリース全体の合計ではなくトラックごとに個別に報告するセクションが 2 つあります。

セクション行の形報告するプラットフォーム
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 が返ります。アーティスト名のフィルターではこの要件を満たせません。

行は date、platform、ISRC の順に並びます。アクティビティのない日はゼロの行ではなく、行そのものがありません。リスナー数は日ごとのカウントであり、日をまたいで合計することはできません。2 日間聴いた同じ人は、それぞれの日で 1 リスナーとして数えられます。

実例: アルバムのトラック別ストリーム数

Section titled “実例: アルバムのトラック別ストリーム数”

UPC が 0123456789012 のアルバムがあり、6 月の数字をトラック別に見たいとします。

トラックごとの合計をランキングで見る場合は、leaderboards エンドポイントにそのアルバムのトラックを問い合わせます。

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 を追加してください。アルバムの中の 1 曲だけを見たいのであれば、UPC ではなくそのトラックの filter[isrc] を渡してください。以降はすべてのアナリティクスエンドポイントが、その録音だけを対象に報告します。

関連

Section titled “関連”

LabelGridはまだお使いではありませんか？

いまお読みいただいた内容は、すべて当社のプラットフォームでご利用いただけます。

LabelGridでできることを見る →