アクセス解析エクスポート

管理しているポッドキャストを1番組ずつ指定し、詳細なアクセス解析をCSVとして取得できます。データの種類を1つ選び、ファイルはリクエスト時に動的に生成します。サーバーには保存されません。

利用条件

  • プレミアムゴールド、プレミアムプロ、カスタムプランが対象です。
  • Personal Access Tokenを発行したユーザーが、対象ポッドキャストの確認済みオーナーである必要があります。
  • 画面とAPIを合わせて、1ユーザーにつき1分10回、1日200回まで出力できます。
  • メディア系の集計は30分ごとに更新します。Webアクセスは別系統で毎時取り込み、提供元の処理遅延もあるため、30分以内の反映は保証しません。

1回の出力は1番組・1種類です。上限は番組やAPIトークンごとではなく、同じユーザーの全リクエストで共有します。日次上限は最初のリクエストから24時間でリセットされます。

エンドポイント

GET https://listen.style/api/v1/podcasts/{podcast_id}/analytics/export

データの種類

datasetは必須です。1回のリクエストで、次のいずれか1種類を指定します。

  • episodes: エピソード情報
  • media_plays: 日別メディア再生
  • listen_plays: 日別LISTEN再生
  • web_traffic: 日別Webアクセス
  • audience: 日別メディア再生内訳（旧称：日別リスナー内訳）
  • unique_listeners: 日別推定ユニークリスナー数

期間の指定

start_dateとend_dateをYYYY-MM-DDで指定します。省略時は直近30日です。

開始日・終了日はどちらも含みます。期間とメディア系・LISTEN再生の日付は、取得ユーザーのタイムゾーン設定が日本または未設定ならAsia/Tokyo、それ以外はUTCです。WebアクセスのdateはGoogle Analyticsのプロパティで集計された日付をそのまま出力し、利用者の設定で日界を変換しません。当日分を一律に除外する仕様ではありませんが、取り込み済みの行だけが出力されます。最終行の日付だけでは更新完了や欠落の有無を判断できません。

curl 'https://listen.style/api/v1/podcasts/PODCAST_ID/analytics/export?dataset=media_plays&start_date=2026-08-01&end_date=2026-08-31' \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  --output listen-analytics-media-plays.csv

日数プリセットとしてperiod=30、period=90、period=365、period=allも指定できます。日付指定がある場合は日付を優先します。

CSVの項目

  • episodes: Podcast ID、Episode ID、GUID、タイトル、公開日時、長さ、音声・ビデオの有無、LISTEN URL
  • media_plays: 日付、エピソード、クライアント種別、音声・ビデオ種別、本編・プレビュー、メディア再生数、1分・5分到達数、完了数、合計・平均再生時間、各到達率・完了率
  • listen_plays: 日付、エピソード、LISTEN再生数
  • web_traffic: 日付、エピソード、ページビュー、アクティブユーザー、エンゲージメント
  • audience: 日付、クライアント・端末・国別のメディア再生数。media_play_countを使用してください。既存のlistener_countも互換性のため同じ値で残していますが、人数ではありません。3つの区分は同じ再生を別の観点で集計しているため、区分をまたいで合算しないでください。
  • unique_listeners: 日付、番組、推定ユニークリスナー数、メディア再生数、識別情報不足のメディア再生数、再集計できず旧値を保持したメディア再生数、タイムゾーン、定義バージョン

CSVはUTF-8（BOM付き）です。IPアドレス、User-Agent、生のリファラー、セッションID、緯度・経度、都市は含みません。列は将来追加される場合があるため、連携処理ではヘッダー名を使って読み取ってください。

メディア再生の成立条件（media-v2）

GETによるHTTP 200または206の音声・動画本体の取得を対象にします。HEAD、エラー応答、プレイリストのみの取得、記録上の転送量が0のリクエストは除外します。本文転送量が記録されていれば、その値が正の場合だけを対象にします。本文転送量がない過去ログではヘッダーを含む転送量で判定するため、本文0バイトの完全な除外はできません。

同じIP・User-Agent・正規化したメディアパスで、最後の対象アクセスから5分未満のアクセスを同じセッションにまとめます。HLSの音声・映像セグメントは同じHLSのパスへまとめます。集計ページ境界では区切らず、期間をまたぐ継続セッションも開始時刻を引き継ぎます。MP3とHLSなど異なるアセットのセッションは別件です。ボットと判定したセッションは指標から除外します。

自動ダウンロードや先読みは含まれ得ます。到達時間・完了数も取得位置からの推定であり、実際の視聴時間を測定したものではありません。LISTEN再生数やApple Podcasts ConnectのPlaysとは合算・差し引きできません。

日別推定ユニークリスナー数（daily-media-ip-ua-v1）

画面での確認とCSV・APIの違い

ダッシュボードで対象番組を選び、「分析」の「日別推定ユニークリスナー数」から確認できます。画面での閲覧は、確認済みの番組オーナーであれば無料を含むすべてのプランで利用できます。メディア再生数との日別比較と、選択期間の1日あたり平均を表示します。30日・90日・全期間・カスタムの期間指定に連動します。

平均は、選択期間に集計データがある場合、セッションが記録されていない日を0として、開始日・終了日を含む日数で計算します。当日分は暫定値で、日別値の合計を期間全体のユニーク人数としては表示しません。集計は30分ごとに更新し、グラフは最大5分間キャッシュします。識別情報が不足する場合は注意書きを表示し、取得障害は0人と区別します。

詳細CSVのダウンロードと、このAPIからの取得は、引き続きプレミアムゴールド・プレミアムプロ・カスタムプラン限定です。既存の基本CSVの利用条件は変更しません。

指標の定義

dataset=unique_listenersのestimated_unique_listener_countは、その日に開始した対象メディア再生セッションを、同じ番組・同じIPアドレス・同じUser-Agentで重複排除した数です。同じ日・番組での複数エピソードや音声・動画をまたぐ取得も1件にまとめます。本編とプレビューの両方を含み、日付はセッションの最初の対象アクセスに帰属します。日をまたいで継続しただけのセッションを翌日の新規利用としては数えません。

実人数の保証はありません。同じネットワーク・アプリを使う別人がまとまったり、同じ人でも回線・アプリの変更で別件になったりします。LISTENが配信していない外部メディアへのアクセスは含みません。日別値を合算しても期間全体のユニーク人数にはなりません。

IPまたはUser-Agentが空・不明のセッションはユニーク数から除外し、unidentified_media_play_countに記録します。これは推定人数ではなくセッション数です。識別キーそのものはCSV・APIに出力しません。

削除済みエピソードなど、現在の情報では安全に再集計できず旧値を保持した分は、unreprocessed_media_play_countで区別します。この分には新しい成立条件を適用できておらず、推定ユニーク数には含みません。メディア再生数には含まれ、unidentified_media_play_countの内数になります。両列を足し合わせないでください。

集計仕様・訂正の更新履歴

今後、集計定義や過去値を変更した際は、この節に対象指標・対象期間・反映日時・再取得の要否を記載します。現時点の値を返すAPIのため、過去値の訂正後は対象期間を再取得して置き換えてください。差分専用APIはありません。

  • 2026-09-14：audienceの名称を「日別メディア再生内訳」に訂正し、同義のmedia_play_count列を追加。従来のlistener_countの意味は変更しません。unique_listenersを追加。
  • 2026-09-14 20:16 JST：2023-07-09～2026-09-14の取り込み済み保存ログを対象に、media-v2で再集計した値へ切り替えました。メディア再生数と、その音声・動画、クライアント・端末・国、到達時間・完了などの内訳が対象です。削除済みの配信データなど再集計できない分は旧値を保持し、unreprocessed_media_play_countで区別します。過去ログの本文転送量の制約は上記のとおりです。対象期間のmedia_plays・audienceを再取得して置き換え、必要に応じてunique_listenersも取得してください。LISTEN再生数・Webアクセスは今回の再集計では変更していません。以降も新しいログを通常の更新周期で反映します。

エラー

  • 401 Unauthorized: トークンがないか無効です。
  • 403 Forbidden: 対象プランではないか、対象ポッドキャストの確認済みオーナーではありません。
  • 422 Unprocessable Entity: データの種類または期間指定が不正です。
  • 429 Too Many Requests: 1分または1日の出力上限を超えています。Retry-Afterヘッダーの秒数が経過してから再試行してください。
  • 503 Service Unavailable: 解析データを一時的に取得できません。空のデータとして扱わず、Retry-Afterヘッダーの秒数が経過してから再試行してください。