ライブリニアプログラムデータセットAPI

Access session-level, program-grain viewership data for your Prime Video linear channels.

約17分で読めます 10月 2, 2026

このガイドでは、ライブリニアプログラムデータセットAPI にアクセスして使用するために必要なことをすべて網羅しています

学習内容

  • APIが提供するものと利用可能なフィード。
  • データセットファイルを認証して取得する方法。
  • 完全なデータモデルと列の定義。
  • チェンジログとis_deletedシグナルの仕組み。
  • パイプラインにコピーして使える、重複排除とMERGEのパターン。
  • 推奨取り込み頻度。
  • 一般的な分析用のサンプルSQLクエリ。

概要

ライブリニアプログラムデータセットAPIは、プライムビデオのライブリニアチャンネルとFASTチャンネルの番組単位の視聴データを提供します。各レコードは、1つのチャンネルで予定されている1つの番組の、1回の視聴セッションを表します。

データは、スケジュール修正用のis_deletedシグナルを含む変更ログとして配信されます。次の2つのフィードを使用できます。 チャンネル(linear_program_event_log) と FAST (fast_linear_program_event_log)。

このデータにより、次のことが可能になります。

  • 放送局、地域、デバイス、時間を問わず、番組レベルの視聴者数(視聴時間、セッション)を追跡します。
  • 放送局、番組、シリーズ、コンテンツタイプごとにパフォーマンスを分析します。
  • データに古い行が残っていても、スケジュール修正を正確に追跡します。
  • ライブリニアの視聴者数を社内システムやデータソースと統合します。

ダッシュボードベースの分析については、以下を参照してください。 Slate Analyticsにおけるリニアプログラミング

主要な機能

機能

詳細

プログラムグレインの詳細

視聴セッション、プログラム、スケジュールごとに1行。タイトル、ステーション、シリーズ、放送時間、総再生時間が含まれます。

削除信号

優先または取り消されたスケジュールは is_deleted = 1 で再送信され、無効になったことが通知されます。

安定した一意のキー

すべての行にはsession_program_schedule_idがあります。これを使用して重複排除とMERGEを行います。

取り込みの簡素化

変更ログモデル。定期的な通話をスケジュールしてから、MERGEします。is_deleted=0の場合はアップサートします。is_deleted=1でのハード削除またはソフト削除。

一貫性

単一のソースであらゆる地域にわたる標準化されたフォーマット。地域ごとのディメンションテーブルは必要ありません。

主要概念

概念

説明

セッション-プログラム-スケジュール行

スケジュールされた 1 つのスロットで 1 つの番組を視聴するセッションです。session_program_schedule_idにより識別されます。

変更ログモデル

データは変更履歴です。行の属性が変更されると、同じ session_program_schedule_idとより新しいlast_update_time_utcを持つ新しいバージョンが公開されます。

主要キー

session_program_schedule_idは一意の識別子です。このフィールドでは常に重複排除を行います。

is_deletedシグナル

is_deleted = 0 は、スケジュールが有効であることを意味します。is_deleted = 1 は、スケジュールが有効ではなくなったか、無効になったことを示します。

シグナルの適用

is_deleted = 0: 行を挿入または更新します。is_deleted = 1:現在のデータにその行が表示されないようにします。行を削除するか、フラグを付けたまま残してフィルターで除外します。

はじめに

オンボーディング方法
ライブリニアプログラムデータセットAPIはアナリティクスAPIスイートの一部です。Analytics APIスイートにオンボーディングすると、ライブリニアプログラムデータセット API(オンボーディング時にリクエストされた場合)を含む、そのスイート内で利用可能なすべてのAPIにアクセスできるようになります。詳細なオンボーディング手順については、APIオンボーディングページをご覧ください。

前提条件
API リクエストを行う前に以下が必要です。

  • Amazonでログイン(LWA)セキュリティプロファイル。クライアントIDをCAMに送信して、PV内部管理ページに追加します。
  • トークンをリクエストするための認証コード。
  • すべてのAPIリクエストのトークン。

ベースURL: https://videocentral.amazon.com/apis/v2

すべてのリクエストには、リクエスト認証ヘッダーに有効なLWA認証トークンを含める必要があります。トークンがないか、有効期限が切れている場合、APIは無許可の例外を返します。

ページネーション
すべての回答はページ分割されています。これらのパラメータを使用してページをナビゲートします。

パラメーター

デフォルト

説明

制限

10

1ページあたりに返されるドキュメントの数。最大1000件。

オフセット

0

最初の結果が出るまでにスキップするドキュメントの数。これを自分で計算するのではなく、次の URL に従ってください。

ページ分割されたすべての応答には次のフィールドが含まれます。

フィールド

説明

合計

全ページの合計文書数。

次へ

次のページへのURL。これが最後のページの場合はNULL。

データセットファイルの取得

エンドポイント
このcurl コマンドを使用して、ダウンロード可能なデータセットファイルリンクのリストを取得します。


注意: このエンドポイントは、行を直接返すのではなく、ダウンロード可能なgzip圧縮されたCSVファイルへのリンクを返します。

パラメーター

パラメーター

説明

ACADIA_ID

あなたのSlateアカウントID。/v2/アカウントで見つけてください。

REPORT_GROUP

ビジネスラインセグメント。チャンネルフィードにはチャンネルを使用し、FASTフィードには高速を使用します。GET /v2/accounts/{ACADIA_ID}で自分のものを見つけます。

ID

識別子のエンドポイントから返されるID値。チャンネルの場合、不透明なハッシュとなります。与えられたidフィールドを使用してください。FAST の場合、これはベンダーコードであり、ハッシュ化されずに返されます。

REPORT_ID

どのレポートを取得するか。チャンネルには linear_program_event_log を使用し、FASTには fast_linear_program_event_log を使用してください。

startDateTime

前回取得した時点に設定されます。形式: YYYY-MM-DDThh:mm:ssZ (UTC)。

endDateTime

現在の時刻に設定します。形式: YYYY-MM-DDThh:mm:ssZ (UTC)。

制限

1ページあたり最小1、最大1,000リンク。

利用可能なレポート
2つのレポートを使用できます。{REPORT_ID}datasets/path セグメントにレポートIDを入力して、それぞれを個別に取得します。

レポート

レポートID

目次

チャンネル

linear_program_event_log

SVOD/サブスクリプションリニア(3P_SUBS、および該当する場合は無料/プライム)。

FAST

fast_linear_program_event_log

無料広告対応テレビ/広告対応(AVOD)リニアチャンネル

注意: 最大データ保持期間は2年です。2年以上前のリクエストには結果は返されません。

ディスカバリーエンドポイント

以下のエンドポイントを使用して、アカウントID、レポートグループ、識別子、および利用可能なデータセットを検索してください。

エンドポイント

返品

GET /v2/accounts

アクセスできるSlateアカウントのリスト。

GET /v2/accounts/{ACADIA_ID}

利用可能なビジネスライン(例:チャンネル、FASTなど)。

GET /v2/accounts/{ACADIA_ID}/channels

利用可能なレポート識別子。各エントリにはIDとわかりやすい名前があります。

GET /v2/accounts/{ACADIA_ID}/channels/{IDENTIFIER_ID}/datasets

その識別子で利用可能なデータセット。

データ列

linear_program_event_log (チャンネル)フィードには次の列があります。fast_linear_program_event_log(FAST)フィードの構造は同じですが、ベンダーコードが追加され、サブスクリプション列がNULLとして配信されます。

列

タイプ

無効化可能

説明

session_program_schedule_id

文字列

いいえ

主要キー。一意のID(セッション、プログラム、放送枠がエンコードされている)。このフィールドで重複排除とMERGEを行います。EPGメタデータの更新により、番組または放送時間が変更されると変更されます。

session_id

文字列

いいえ

匿名化された一意の視聴セッション識別子。

is_deleted

INT

いいえ

ステータスシグナル。0=スケジュールは有効。1=スケジュールはもはや有効ではない(優先または取り消された)。現在のデータからis_deleted=1の行を除外します。

last_update_time_utc

タイムスタンプ

いいえ

バージョン時間を記録します。重複排除には必ず使用してください。特定のIDの最新値を含む行を保持します。

create_time_utc

タイムスタンプ

いいえ

行が最初に作成された日時。

program_id

文字列

いいえ

プログラム識別子(例:TMS ID)

pv_title_id

文字列

はい

プログラムのプライムビデオグローバルタイトル識別子(GTI)。TVODフィードのpv_title_idと同じです。

program_title

文字列

はい

プログラムのタイトル。

station_name

文字列

はい

チャンネル名または放送局名。

content_type

文字列

いいえ

live_broadcastまたはscheduled_tv.

airing_start_utc

タイムスタンプ

いいえ

番組放送開始 (UTC)。

airing_end_utc

タイムスタンプ

いいえ

番組放送停止(UTC)。

start_segment_utc

タイムスタンプ

いいえ

セッション開始時間 (UTC) を表示します。

end_segment_utc

タイムスタンプ

いいえ

セッション終了(UTC)を表示します。

seconds_viewed

ロング

いいえ

このセッションで閲覧された秒数。

vendor_sku

文字列

はい

コンテンツSKU(例: Gracenote識別子など)。

parent_channel_label

文字列

はい

ハッシュ化された親チャンネル識別子。

cid

文字列

はい

チャンネルID(有効)。

benefit_id

文字列

はい

資格/特典識別子。

subscription_offer_id

文字列

はい

サブスクリプションオファー識別子。

subscription_event_id

文字列

はい

サブスクリプションイベント識別子。

subscription_offer_time_zone

文字列

はい

サブスクリプションオファーのタイムゾーン。

marketplace_id

INT

いいえ

マーケットプレイス識別子。

marketplace_desc

文字列

はい

マーケットプレイス詳細。

地域

文字列

はい

地域または国コード(米国、英国、ドイツ、オーストラリアなど)。

device_class

文字列

はい

デバイスのカテゴリ。

device_sub_class

文字列

はい

デバイスのサブカテゴリ。

connection_type

文字列

はい

接続タイプ(wifi、有線、その他)。

playback_method

文字列

はい

セッションがどのように消費されたか。 オンライン(ストリーミング)またはオフライン(ダウンロード)。ライブリニア配信は事実上常にオンラインの状態です。

geo_dma

文字列

はい

地理的データ管理システム。

stream_type

文字列

いいえ

常にLINEAR_TV。

FASTフィードに関する注記: fast_linear_program_event_logフィードは同じ構造です。vendor_code (パートナーコード)列が表示されます。サブスクリプション列(サブスクリプション_オファーID、サブスクリプション_イベントID、サブスクリプション_オファー_タイムゾーン)は NULL として配信されます。

理解はis_deleted

すべての行に is_deleted が入っています。スケジュールのステータスに関するシグナルです。次の 2 つの値があります。

値

意味

適用方法

0

スケジュールはアクティブです(現在のバージョン)。

挿入するか、このキーの既存の行を上書きしてください。

1

スケジュールはもはや有効ではありません(優先または取り消された)。

現在のデータに表示されないようにしてください。行を削除するか、フラグを付けたまま残してフィルターで除外します。

is_deleted = 1が発生するのはどのような場合ですか?

  • スケジュール修正。 番組または放送時間が修正されました。古い session_program_schedule_idは is_deleted =1 として届きます。is_deleted=0 という名前で新しい ID が届きます。古いものをもう有効ではないとして適用し、新しいものを挿入します。
  • 放映が削除されました。 放映は完全に取り消されました。そのIDは is_deleted=1として届きます。

重要な注意事項

  • 指定されたsession_program_schedule_idが同じバッチで0と1の両方になることはありません。訂正された放送は、別のキーになります。
  • フィードの対象条件を満たさない行は配信されません。一度も受け取っていない行がis_deleted =1になると期待しないでください。

重複排除

同じsession_program_schedule_idを複数回受け取ることがあります。これらは同じ行の更新されたバージョンです。重複排除は次の3つのステップで処理します。

  1. 各IDの最新バージョンを保管してください。 IDごとに、最新のlast_update_time_utcを含む行のみを保持し、古い行は削除します。この値は前に進むだけなので、常に最新の値が優先されます。


  1. 重複排除された行をテーブルにMERGEします。 以下のMERGEパターンを使用してください。データを読み込むたびに is_deletedを処理します。

一括挿入ではなくMERGEを使用してください。すべてのファイルを新しい行として読み込む場合、is_deleted=1の行は適用されず、有効なデータとしてテーブルに保存されます。常にフラグに従って処理するしてください。

  1. ソフト削除の代替手段。 DELETEの分岐をUPDATE SETis_deleted=1に置き換え、その後クエリでWHERE is_deleted = 0で絞り込んでください。どちらの方法でも同じ結果が得られます。

推奨取り込み頻度

新しいデータセットは1日を通して段階的に公開されます。

推奨事項

詳細

推奨頻度

1日に1〜4回で、常に最新の状態に保たれます。

増分戦略

startDateTimeを最後に取得したタイムスタンプに設定し、endDateTimeを現在の時刻に設定します。返されたすべてのファイルをダウンロードして処理し、MERGEします。

日次/週次消費者

日次または週次で取得する場合は、その期間のすべてのファイルを処理します。これにより、更新や削除を見逃すことがなくなります。

注意: 各バッチでは、有効な行(is_deleted=0)と有効でなくなった行(is_deleted=1)が混在します。これらは個別のファイルでは配信されません。is_deletedカラムはそれらを区別します。

APIの使用例

アカウントを検索し、レポートグループと識別子を特定し、データセットファイルを取得するには、次の手順に従ってください。

ステップ0: アカウントを一覧表示
GET /v2/accountsを呼び出して、アクセスできるSlateアカウントを一覧表示します。

ステップ1: アカウントのビジネスライン
GET /v2/accounts/12345678 に電話をして、利用可能なビジネスラインを確認してください。

idフィールドは、その後の呼び出しで使用する{REPORT_GROUP}パスセグメントです。

ステップ2a: チャンネル識別子
GET /v2/accounts/12345678/channels?offset=0&limit=100 を呼び出し、チャンネル識別子を一覧表示してください。

ステップ2b: FAST識別子
GET /v2/accounts/12345678/fast?offset=0&limit=100 を呼び出し、FAST識別子を一覧表示します。

ステップ2c: 識別子に使用できるデータセット
GET /v2/Accounts/12345678/Fast/ABC123/Datasetsを呼び出して、利用可能なデータセットを一覧表示してください。

ステップ3a: チャンネルデータセットファイル
チャンネル識別子のデータセットファイルエンドポイントを呼び出します。レスポンスは、gzipで圧縮されたCSVファイルのダウンロードURLのリストを返します。

ステップ3b: FASTデータセットファイル
FAST識別子のデータセットファイルのエンドポイントを呼び出します。

サンプルクエリ

これらのクエリは、データがすでにマージされていることを前提としています。is_deleted行を生テーブルに保存する場合は、各クエリに WHERE is_deleted = 0 を追加してください。

ある期間における放送局別の視聴時間

視聴時間別の上位X番組

日次視聴概要

地域別の視聴時間

ETLパイプライン

この4ステップのパターンを使用して、ライブリニアプログラムデータセットの ETLパイプラインを構築します。

  1. 初期データ取得。 APIエンドポイントを使用して、目的の時間範囲内にチャンネルのすべてのファイルを取得します。返されたファイルをすべてダウンロードします。各行にはgzip圧縮されたCSV形式の行が含まれます。
  2. 重複排除。 取得したファイル間で同じsession_program_schedule_idのレコードが複数存在する場合は、最新のlast_update_time_utcを含む行のみを保持してください。 SQLパターン全体については、重複排除セクションを参照してください。
  3. 目的地に適用。 重複排除されたレコードを、session_program_schedule_i dをキーとする目的地のターゲットテーブルにMERGEします。is_deleted=0の場合はアップサートします。is_deleted=1になったら、現在のデータにIDが表示されないようにします。行を完全に削除するか、行にフラグを付けたままフィルターで除外します。
  4. 増分処理。 継続的な読み込みの場合は、最後に取得した時刻と EndDateTimeを現在の時刻に設定します。返されたファイルをすべて処理し、目的地にMERGEします。


クイックヒント

APIをパイプラインに統合するときは、次のヒントを念頭に置いてください。

  1. session_program_schedule_idはあなた固有のキーです。必ずlast_update_time_utcを使用して重複排除を行います。
  2. 一括挿入ではなくMERGEを使用してください。データを読み込むびに is_deleted シグナルを処理します。
  3. 最新データを取得するには、1 日に1~4回取得します。
  4. 増分ロードの場合は、 startDateTimeを最後に正常に完了した取得タイムスタンプに設定してください。
  5. ディスカバリーエンドポインを使用して、アカウント、識別子、および利用可能なデータセットを検索します。
  6. パートナーシップでチャンネルとFASTフィードの両方が網羅されている場合は、両方を取得してください。
  7. ソフト削除アプローチを使用する場合は、すべてのクエリにWHERE is_deleted=0を追加してください。
  8. 最大データ保持期間は2年です。それに応じて過去のデータの取得を計画してください。

ご存じでしたか?

番組単位の視聴データにプログラムからアクセスすることで、カスタムレポートの作成、スケジューリングシステムへの取り込み、またリニアデータにその他のビジネスデータを組み合わせることが可能になります。このAPIを自社のワークフローに統合したパートナーは、番組編成やとコンテンツ調達について、より多くの情報に基づいた意思決定をより迅速に行うことができます。

視覚的な分析と迅速な洞察については、Slate Analyticsのリニアプログラミングダッシュボードをご覧ください。

よくある質問

ライブリニアプログラムデータセット API よくある質問

まだヘルプが必要ですか?

お問い合わせ

このガイドの内容



インターナルサーバーエラー、もう一度お試しください。
セッションがタイムアウトしました

続行するにはサインインしてください

サインイン
edit