このガイドでは、ライブリニアプログラムデータセットAPI にアクセスして使用するために必要なことをすべて網羅しています
学習内容 |
|
概要
ライブリニアプログラムデータセット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 コマンドを使用して、ダウンロード可能なデータセットファイルリンクのリストを取得します。
curl -X GET \
-H "Authorization: Bearer Atza|auth_token" \
"https://videocentral.amazon.com/apis/v2/accounts/{ACADIA_ID}/{REPORT_GROUP}/{IDENTIFIER_ID}/datasets/{REPORT_ID}\
?startDateTime=YYYY-MM-DDThh:mm:ssZ\
&endDateTime=YYYY-MM-DDThh:mm:ssZ\
&offset=0&limit=1000"
注意: このエンドポイントは、行を直接返すのではなく、ダウンロード可能な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つのステップで処理します。
- 各IDの最新バージョンを保管してください。 IDごとに、最新のlast_update_time_utcを含む行のみを保持し、古い行は削除します。この値は前に進むだけなので、常に最新の値が優先されます。
SELECT *
FROM (
SELECT *,
ROW_NUMBER() OVER (
PARTITION BY session_program_schedule_id
ORDER BY last_update_time_utc DESC
) AS rn
FROM your_staging_table
) t
WHERE rn = 1;
- 重複排除された行をテーブルにMERGEします。 以下のMERGEパターンを使用してください。データを読み込むたびに is_deletedを処理します。
MERGE INTO your_table AS target USING dedup_staging AS source ON target.session_program_schedule_id = source.session_program_schedule_id WHEN MATCHED AND source.is_deleted = 1 AND source.last_update_time_utc > target.last_update_time_utc THEN DELETE WHEN MATCHED AND source.is_deleted = 0 AND source.last_update_time_utc > target.last_update_time_utc THEN UPDATE SET program_title = source.program_title, seconds_viewed = source.seconds_viewed, airing_start_utc = source.airing_start_utc, airing_end_utc = source.airing_end_utc, last_update_time_utc = source.last_update_time_utc -- ... all other columns WHEN NOT MATCHED AND source.is_deleted = 0 THEN INSERT (session_program_schedule_id, session_id, program_id, ..., last_update_time_utc) VALUES (source.session_program_schedule_id, source.session_id, source.program_id, ..., source.last_update_time_utc);
一括挿入ではなくMERGEを使用してください。すべてのファイルを新しい行として読み込む場合、is_deleted=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アカウントを一覧表示します。{
"total": 1,
"next": null,
"data": [
{ "id": "12345678", "name": "MGM" }
]
}
ステップ1: アカウントのビジネスライン
GET /v2/accounts/12345678 に電話をして、利用可能なビジネスラインを確認してください。{
"total": 2,
"next": null,
"data": [
{ "id": "channels", "name": "Channels" },
{ "id": "fast", "name": "FAST" }
]
}
idフィールドは、その後の呼び出しで使用する{REPORT_GROUP}パスセグメントです。
ステップ2a: チャンネル識別子
GET /v2/accounts/12345678/channels?offset=0&limit=100 を呼び出し、チャンネル識別子を一覧表示してください。{
"total": 2,
"next": null,
"data": [
{ "id": "3f6c1b9d-8a2d-4e7f-9c31-0d5b7b2e6f14", "name": "MGM+" },
{ "id": "a91d4c21-57e0-4b8a-b6f3-2e9c0e1f8b77", "name": "MGM+ Espanol" }
]
}
ステップ2b: FAST識別子
GET /v2/accounts/12345678/fast?offset=0&limit=100 を呼び出し、FAST識別子を一覧表示します。{
"total": 1,
"next": null,
"data": [
{ "id": "ABC123", "name": "MGM FAST" }
]
}
ステップ2c: 識別子に使用できるデータセット
GET /v2/Accounts/12345678/Fast/ABC123/Datasetsを呼び出して、利用可能なデータセットを一覧表示してください。{
"total": 1,
"next": null,
"data": [
{ "id": "fast_linear_program_event_log", "name": "FAST Linear Program Event Log" }
]
}
ステップ3a: チャンネルデータセットファイル
チャンネル識別子のデータセットファイルエンドポイントを呼び出します。レスポンスは、gzipで圧縮されたCSVファイルのダウンロードURLのリストを返します。GET /v2/accounts/12345678/channels/3f6c1b9d-8a2d-4e7f-9c31-0d5b7b2e6f14
/datasets/linear_program_event_log
?startDateTime=2026-09-14T00:00:00Z&endDateTime=2026-09-15T00:00:00Z&offset=0&limit=1000
{
"total": 3,
"next": null,
"data": [
{ "downloadUrl": "https://pvreporting-datasets-prod.s3.amazonaws.com/linear_program_event_log/
3f6c1b9d.../2026/09/14/06/...linear_2f0c...e91a.csv.gz?X-Amz-Algorithm=..." },
{ "downloadUrl": "https://pvreporting-datasets-prod.s3.amazonaws.com/linear_program_event_log/
3f6c1b9d.../2026/09/14/14/...linear_7b41...03cd.csv.gz?..." },
{ "downloadUrl": "https://pvreporting-datasets-prod.s3.amazonaws.com/linear_program_event_log/
3f6c1b9d.../2026/09/14/22/...linear_c8d9...5e60.csv.gz?..." }
]
}
ステップ3b: FASTデータセットファイル
FAST識別子のデータセットファイルのエンドポイントを呼び出します。GET /v2/accounts/12345678/fast/ABC123/datasets/fast_linear_program_event_log
?startDateTime=2026-09-14T00:00:00Z&endDateTime=2026-09-15T00:00:00Z&offset=0&limit=1000
{
"total": 1,
"next": null,
"data": [
{ "downloadUrl": "https://pvreporting-datasets-prod.s3.amazonaws.com/fast_linear_program_event_log/
ABC123/2026/09/14/15/...fast_linear_c258fb25...758add.csv.gz?X-Amz-Algorithm=..." }
]
}
サンプルクエリ
これらのクエリは、データがすでにマージされていることを前提としています。is_deleted行を生テーブルに保存する場合は、各クエリに WHERE is_deleted = 0 を追加してください。
ある期間における放送局別の視聴時間 SELECT station_name,
COUNT(*) AS sessions,
SUM(seconds_viewed) / 3600.0 AS hours_viewed
FROM your_table
WHERE start_segment_utc BETWEEN '[START_DATE]' AND '[END_DATE]'
GROUP BY station_name
ORDER BY hours_viewed DESC;
視聴時間別の上位X番組SELECT program_title, station_name,
SUM(seconds_viewed) / 3600.0 AS hours_viewed
FROM your_table
WHERE start_segment_utc BETWEEN '[START_DATE]' AND '[END_DATE]'
GROUP BY program_title, station_name
ORDER BY hours_viewed DESC
LIMIT [X];
日次視聴概要 SELECT DATE(start_segment_utc) AS view_date,
COUNT(*) AS sessions,
SUM(seconds_viewed) / 3600.0 AS hours_viewed
FROM your_table
WHERE start_segment_utc BETWEEN '[START_DATE]' AND '[END_DATE]'
GROUP BY DATE(start_segment_utc)
ORDER BY view_date DESC;
地域別の視聴時間 SELECT territory,
SUM(seconds_viewed) / 3600.0 AS hours_viewed
FROM your_table
WHERE start_segment_utc BETWEEN '[START_DATE]' AND '[END_DATE]'
GROUP BY territory
ORDER BY hours_viewed DESC;
ETLパイプライン
この4ステップのパターンを使用して、ライブリニアプログラムデータセットの ETLパイプラインを構築します。
- 初期データ取得。 APIエンドポイントを使用して、目的の時間範囲内にチャンネルのすべてのファイルを取得します。返されたファイルをすべてダウンロードします。各行にはgzip圧縮されたCSV形式の行が含まれます。
- 重複排除。 取得したファイル間で同じsession_program_schedule_idのレコードが複数存在する場合は、最新のlast_update_time_utcを含む行のみを保持してください。 SQLパターン全体については、重複排除セクションを参照してください。
- 目的地に適用。 重複排除されたレコードを、session_program_schedule_i dをキーとする目的地のターゲットテーブルにMERGEします。is_deleted=0の場合はアップサートします。is_deleted=1になったら、現在のデータにIDが表示されないようにします。行を完全に削除するか、行にフラグを付けたままフィルターで除外します。
- 増分処理。 継続的な読み込みの場合は、最後に取得した時刻と EndDateTimeを現在の時刻に設定します。返されたファイルをすべて処理し、目的地にMERGEします。
startDateTime = {last_successful_pull_timestamp}
endDateTime = {current_utc_timestamp}
クイックヒント
APIをパイプラインに統合するときは、次のヒントを念頭に置いてください。
- session_program_schedule_idはあなた固有のキーです。必ずlast_update_time_utcを使用して重複排除を行います。
- 一括挿入ではなくMERGEを使用してください。データを読み込むびに is_deleted シグナルを処理します。
- 最新データを取得するには、1 日に1~4回取得します。
- 増分ロードの場合は、 startDateTimeを最後に正常に完了した取得タイムスタンプに設定してください。
- ディスカバリーエンドポインを使用して、アカウント、識別子、および利用可能なデータセットを検索します。
- パートナーシップでチャンネルとFASTフィードの両方が網羅されている場合は、両方を取得してください。
- ソフト削除アプローチを使用する場合は、すべてのクエリにWHERE is_deleted=0を追加してください。
- 最大データ保持期間は2年です。それに応じて過去のデータの取得を計画してください。
ご存じでしたか? |
番組単位の視聴データにプログラムからアクセスすることで、カスタムレポートの作成、スケジューリングシステムへの取り込み、またリニアデータにその他のビジネスデータを組み合わせることが可能になります。このAPIを自社のワークフローに統合したパートナーは、番組編成やとコンテンツ調達について、より多くの情報に基づいた意思決定をより迅速に行うことができます。 視覚的な分析と迅速な洞察については、Slate Analyticsのリニアプログラミングダッシュボードをご覧ください。 |