プラットフォームでフィルターするとアナリティクスの指標が空になるのはなぜですか?

すべてのプラットフォームがすべての指標を報告するわけではありません。アナリティクスのリクエストをプラットフォームでフィルターすると、レスポンスに availability フィールドが含まれます。not_available_for_platform の場合、そのプラットフォームはその指標を報告しておらず、データは空になります。これは想定どおりの動作でエラーではありません。GET /アナリティクス/availability を呼び出すと、セクションとプラットフォームの完全なマトリクスを確認できます。

プラットフォームが API でどのアナリティクス指標に対応しているかを知るには?

GET /アナリティクス/availability を呼び出してください。各アナリティクスセクションと各プラットフォームの完全なマトリクスと、各プラットフォームの報告サイクルを、キャッシュ可能な 1 回の静的な呼び出しで返します。プラットフォームでフィルターしたリクエストでは、同じ情報が data の隣の availability フィールドとして現れます。

プラットフォームのアナリティクスデータポイントが週に 1 つしか表示されないのはなぜですか?

Kugou・Kuwo・QQ Music は日次ではなく週次で報告します。毎週、レポート対象日の日付が付き、週全体の合計を持つトラックごとのデータポイントが 1 つ生成されます。週次ポイント間の空白はデータの欠落ではなく、ポイントを合計すれば範囲の正しい合計が得られます。どのプラットフォームが週次報告かは meta.platform_cadence か GET /アナリティクス/availability で確認してください。

アナリティクス API: プラットフォーム・可用性・上限

LabelGrid のパブリック API は、GET /アナリティクス/summary(選択したセクションを返す複合エンドポイント)と、GET /アナリティクス/streams のような単独のシリーズエンドポイントでストリーミングアナリティクスを提供します。このページでは、プラットフォームの一覧、各プラットフォームが報告する内容の調べ方、報告サイクル、リクエストの上限を説明します。

対応プラットフォーム

filter[platform] は 9 ストアをカバーする 10 個の値を受け付けます。

SPOTIFY・APPLE_MUSIC(ITUNES は同じストアのエイリアスとして受け付けられます)・DEEZER・BOOMPLAY・AWA・AUDIOMACK・KUGOU・KUWO・QQMUSIC

filter[platform] を省略すると、アカウントにデータのあるすべてのプラットフォームを合算したビューが返されます。

可用性を調べる: `GET /アナリティクス/availability`

すべてのプラットフォームがすべての指標を報告するわけではありません。可用性ディスカバリーエンドポイントは、全体像を 1 回の呼び出しで返します。

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 は空です。想定どおりの動作でエラーではありません。

単独エンドポイントはトップレベルの値を 1 つ持ち、/アナリティクス/summary はリクエストしたセクションごとに 1 エントリのマップを持ちます。プラットフォームフィルターのないリクエストには availability フィールドは付きません。空の data を「アクティビティなし」と解釈する前に、必ず availability を確認してください。

プラットフォームが報告する内容

マトリクスの概要です(正となる最新版はエンドポイントを呼び出して確認してください)。

セクション	報告するプラットフォーム
`streams`	9 プラットフォームすべて
`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 — 1 日 1 回の報告: SPOTIFY・APPLE_MUSIC・DEEZER・BOOMPLAY・AWA・AUDIOMACK
weekly — 週 1 回の報告: KUGOU・KUWO・QQMUSIC

週次プラットフォームは、レポート対象日の日付が付き、その週全体の合計を持つトラックごと週 1 つのデータポイントを生成します。合計が 7 日間に分割されることはありません。日次シリーズでは週に 1 つの日付だけが埋まり、その間の日付には行がありません。

日付の間隔からサイクルを推測するのではなく、platform_cadence を読んで対応してください。

週次ポイント間の空白を欠損データとして扱わないでください。
週次ポイントを日次平均に分割しないでください。
ポイントをそのまま合計すれば、どの範囲でも正しい合計が得られます。

サイクルは meta.section_granularity とは別物です。後者は返されたシリーズのポイントがどう日付付けされているか(day または week)を示します。1 つのレスポンスが粒度 "day" とサイクル "weekly" を同時に持つことがあります。日付は日単位で、ポイントは週 1 つという意味です。

セクションを選ぶ: `/アナリティクス/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 回のリクエストで丸 1 年と比較期間をカバーできます。上限を超える範囲は 422 を返し、エラーメッセージに上限が示されます。

エンドポイントファミリー	最大範囲
`/アナリティクス/summary` と単独シリーズ/デモグラフィックエンドポイント	400 日
`/アナリティクス/leaderboards`・`/アナリティクス/placements`	180 日

ランキングエンドポイントは独自の 180 日上限を維持します。短い top-N ウィンドウを複数組み合わせても、より長い期間の top-N は再構築できない点に注意してください。

400 日ウィンドウとともに、さらに 2 つの挙動が加わります。

90 日を超えるリクエストは、標準のアナリティクス上限に加えて、2 つ目のより低いレート制限の対象になります(アカウントあたり毎分 30。標準は 60。パートナーの egress IP 予算も同様に半分になります)。90 日以下のリクエストは影響を受けません。どちらかの上限を超えると、通常の Retry-After と X-RateLimit-* ヘッダー付きで 429 が返ります。
上限内の範囲でも計算が重すぎることがあります。 たとえば非常に大きなカタログでフルウィンドウ、多数の metrics[] を指定した場合です。この場合は「日付範囲を狭めてください」というメッセージ付きの 422 が返ります。リトライ可能として扱い、より短い範囲か少ないセクションで再試行してください。無関係なサーバーエラーは引き続き 500 を返すため、ここでの 422 は「このリクエストが大きすぎた」ことを確実に意味します。