ホテル価格広告レポート API

[アーティクル]
10/04/2023

注:

このベータ版のHotel Price Adsは、一部の参加者のみが利用できます。ベータリリースプログラムへの参加の詳細については、アカウントマネージャーに問い合わせるか、こちらで登録してください。

API とドキュメントは変更される可能性があります。

レポートは非同期プロセスです。レポートを要求するための一般的なフローを次に示します。

レポートパラメーターを使用して要求を作成する
レポートサービスに要求を送信する
サービスは要求を処理できるようになるまでキューに入れます
サービスを定期的にポーリングして、レポートジョブの状態を取得する
状態が [完了] の場合は、サービスが提供する URL を使用してレポートをダウンロードします。

レポートを要求してダウンロードする方法を示す例については、「レポートのコード例」を参照してください。

レポートの要求

レポートを要求するには、HTTP POST 要求を次のエンドポイントに送信します (サンドボックスエンドポイントについては、「エンドポイント」を参照してください)。

https://partner.api.bingads.microsoft.com/Travel/v1/Customers({customerId})/Accounts({accountId})/ReportJobs

要求の本文は ReportJob オブジェクトです。要求では、次のフィールドを指定する必要があります。

StartDate - レポート期間の開始
EndDate - レポート期間の終了
列 - レポートに含める列
ReportType - ダウンロードするレポートまたはエンティティの種類

他のすべてのフィールドは省略可能です。

使用可能な最小粒度は毎日です (時間単位はサポートされていません)。 [日付] 列が含まれている場合Columns、レポートには、ウィンドウと EndDate ウィンドウの各日の行がStartDate含まれます。 Date を含めない場合、レポートデータには、指定した開始日と終了日の合計パフォーマンスの概要が表示されます。

次の例は、パフォーマンスレポートの ReportJob 要求を示しています。

{
    "ReportType":"Performance", 
    "StartDate":"2017-11-06", 
    "EndDate":"2017-11-13", 
    "Columns":[  
        "HotelId", 
        "Clicks" 
    ] 
}

既定では、サービスは非圧縮 CSV 形式でレポートを生成します。レポートを圧縮してダウンロードのパフォーマンスを向上させるには、[ 圧縮 ] フィールドを含め、ZIP に設定します。

POST への応答には、レポートジョブ ID が含まれています ( 「AddResponse」を参照)。例:

{
    "value":"1080"
}

レポートジョブの状態のポーリング

ID を取得した後、それを使用してレポートジョブの状態を取得します。状態を取得するには、HTTP GET 要求を次の送信先に送信します。

https://partner.api.bingads.microsoft.com/Travel/v1/Customers({customerId})/Accounts({accountId})/ReportJobs('{jobId}')

レポートジョブは、完了した後に確定されていない時間に対して有効ですが、通常は少なくとも 7 日間有効です。 7 日後に、新しいレポート要求を送信する必要があります。

応答の本文は ReportJob オブジェクトです。ジョブの状態を確認するには、フィールドに Status アクセスします。ジョブが完了すると、 Status が [完了] に設定され、 Url レポートのダウンロードに使用する URL がフィールドに含まれます。 URL は 7 日間有効です。 URL の有効期限が切れた場合は、新しいジョブ要求を送信する必要があります。

レポートジョブの完了にかかる時間は未定であり、キュー内のジョブ数、データ量、レポート期間のサイズを常に変更している複数の変数に基づいています。一般に、ジョブの状態が [完了] または [失敗] になるまで、ジョブの状態を 5 秒ごとにポーリングする必要があります。

レポートのダウンロード

レポートジョブの状態が [完了] の場合、ジョブの Url フィールドには、レポートのダウンロードに使用する URL が含まれます。レポートをダウンロードするには、指定した URL に HTTP GET 要求を送信します。

ダウンロード URL を使用してレポートをダウンロードする場合は、他のレポート要求と同様に Authorization ヘッダーを指定しないでください。ダウンロード URL を使用するだけです。

非圧縮レポートの場合、GET 応答の Content-Type ヘッダーにはテキスト/csv が含まれます。圧縮されたレポートの場合、ヘッダーには application/zip が含まれます。

レポートのデータを圧縮するようにサービスに要求した場合 (レポートジョブの Compression フィールドを参照)、サービスはファイルをフォルダーに配置し、ZIP 圧縮を使用してレポートを圧縮します。レポートにアクセスして読み取る前に、フォルダーを圧縮解除してください。レポートファイルの名前は自動生成され、フォームのパフォーマンス要求 ID を>持っています<。

レポートデータのフィルター処理

レポート内のデータをフィルター処理するには、ReportJob オブジェクトの Filter フィールドを使用します。次のディメンション列と任意のメジャー列でレポートをフィルター処理できます。列名は大文字と小文字を区別します。

SubaccountId
SubaccountName
HotelGroupId
HotelGroupName
HotelId
HotelName
ホテルスタタス
PartnerHotelId
DeviceType

フィルターの使用は AND 操作です。たとえば、HotelPartnerId が 123、DeviceType が Mobile と等しい場合、レポートには、パートナーのホテル ID が 123 で、デバイスの種類がモバイルである場合にのみデータが含まれます。

レポートのデータをフィルター処理するには、OData $filter文字列に設定Filterします。次の例は、デスクトップとタブレットに表示される広告のレポートをフィルター処理する方法を示しています。フィルターで使用する列挙値では、大文字と小文字が区別されます。たとえば、デスクトップではなく Desktop を使用します。

{
    "ReportType":"Performance", 
    "StartDate":"2017-11-06", 
    "EndDate":"2017-11-13", 
    "Columns":[  
        "HotelId", 
        "Clicks" 
    ], 
    "Filter":"DeviceType eq Enum.DeviceType'Desktop' or DeviceType eq Enum.DeviceType'Tablet'", 
}

フィールドのFilter使用に加えて、フィールドと HotelGroupId フィールドをSubaccountId使用して、レポートを特定のサブアカウントまたはホテルグループに制限できます。これらのフィールドを使用してスコープを 1 つのサブアカウントまたはホテルグループに制限すると、を使用 Filterするよりもパフォーマンスが向上します。とをHotelGroupId使用SubaccountIdする場合は、フィルターでも指定しないでください。

レポートにパフォーマンスの不履行のホテルを含む

既定では、パフォーマンスレポートには、レポート期間中にインプレッションがあるホテルのみが含まれます。レポート期間中にインプレッションがなかったホテルを含める場合は、レポート要求の IncludeNonPerformingHotels フィールドを true に設定 します。

{
    "ReportType":"Performance", 
    "StartDate":"2017-11-06", 
    "EndDate":"2017-11-13", 
    "Columns":[  
        "HotelId",
        "PartnerHotelId",
        "Clicks",
        "Impressions"
    ],
    "IncludeNonPerformingHotels" : true
}

レポートでパフォーマンスの高くないホテルを要求する場合、プロパティに次のcolumnsディメンション列を含めないようにしてください。

Date
DeviceType
HotelCountry
LengthOfStay
SlotType
UserCountry

プロパティに columns 上記のフィールドのいずれかが含まれている場合、レポートジョブ要求は失敗します。

IncludeNonPerformingHotels は、グループを移動したホテルのレポートにどのような影響がありますか?

既定では、レポートには、ホテル、ホテルグループ、サブアカウントでレポートをセグメント化するかどうかにかかわらず、ホテルのホテルのパフォーマンスデータが含まれます。あるグループから別のグループにホテルを移動しても、既定のレポート動作には影響しません。たとえば、レポートにホテル列が含まれている場合、レポートには、指定された期間中のホテルのすべてのパフォーマンスデータが含まれます。

Date        Hotel ID   Clicks
1-1-2018    5678       12

ホテル列とホテルグループ列を含める場合、レポートには、指定された期間中にホテルグループごとに発生したホテルのパフォーマンスデータが含まれます。

Date       Hotel group ID   Hotel ID   Clicks
1-1-2018   1234             5678       2
2-1-2018   9876             5678       10

ただし、IncludeNonPerformingHotels 要求プロパティを含める場合、状況は変わります。 true の場合、レポートにはアクティブなホテルとホテルグループの関連付けのパフォーマンスデータのみが含まれます。これは、上記のホテルレポートの例が次に変更されることを意味します。

Date        Hotel ID   Clicks
1-1-2018    5678       10

ホテルグループの例は、次に変更されます。

Date       Hotel group ID   Hotel ID   Clicks
2-1-2018   9876             5678       10

閉じられた書籍

ブックが閉じるタイミングについては、「ブックが閉じるタイミングを決定する」を参照してください。ホテル価格広告の書籍が Microsoft 広告キャンペーンと同じかどうかを判断する場合、次の例外が発生します。

Hotel Price Ads のレポートサービスでは、アカウントのタイムゾーンが使用されます。
Hotel Price Ads のレポートサービスでは、ReturnOnlyCompleteData はサポートされていません。

パフォーマンスレポート列

レポートには、ディメンション列とメジャー列 (メトリック) が含まれます。メトリックデータはディメンション列によってセグメント化されます。つまり、メトリックデータは、レポート要求で指定したディメンション階層内の最下位レベルのディメンションにロールアップされます。

パフォーマンスレポートのディメンション階層を次に示します。

Date
SubaccountId/Name
HotelGroupId/Name
HotelId/Name, PartnerHotelId
HotelCountry
UserCountry
SlotType
LengthOfStay
DeviceType

たとえば、要求に SubaccountId と Clicks が含まれている場合、クリックは SubaccountId にロールアップされます。

Date	Subaccount	クリック
2017-11-16	123	40

要求に SubaccountId、HotelGroupId、および Clicks が含まれている場合、クリックは HotelGroupId にロールアップされます。

Date	Subaccount	ホテルグループ	クリック
2017-11-16	123	987	12
2017-11-16	123	654	13
2017-11-16	123	321	15

要求には、少なくとも 1 つのディメンション列と 1 つのメジャー列が含まれている必要があります。

ディメンション列

列名	レポート列名	説明
AdvancedBookingWindow	Adv. Booking window	ユーザーがホテルの部屋の予約を求めているチェックの日付の前の日数。たとえば、今日が 5 月 3 日で、ユーザーが 5 月 8 日の会議室の予約を求めている場合、列の値は 5 です。
CheckinDay	チェックイン日	ユーザーがホテルにチェックするように求めている曜日。可能な整数値を次に示します。 1 (月曜日) 2 (火曜日) 3 (水曜日) 4 (木曜日) 5 (金曜日) 6 (土曜日) 7 (日曜日)
Date	Date	レポート期間内の日付。指定されていない場合、この列は自動的にレポートに追加されます。形式は YYYY-MM-dd (2017-11-16 など) です。
DateType	日付の種類	ユーザーが特定の日付を使用してホテルを検索したかどうかを示します。使用可能な値を次に示します。 DefaultDate - ユーザーが特定の日付を使用してホテルを検索しませんでした SelectedDate - 特定の日付を使用してホテルを検索したユーザー
DeviceType	デバイスのタイプ	広告が表示されたデバイスの種類。使用可能な値を次に示します。 Desktop Mobile Tablet
HotelCountry	ホテルの国	ホテルがある国または地域の 2 文字の ISO 3116 国コード。たとえば、us for 米国。
HotelGroupId	ホテルグループ ID	ホテルグループを一意に識別する ID。
HotelGroupName	ホテルグループ名	ホテルグループの表示名。
HotelId	ホテル ID	ホテルを一意に識別する ID。
HotelName	ホテル名	ホテルの名前。
LengthOfStay	滞在期間	旅程の滞在期間。
PartnerHotelId	パートナーホテル ID	パートナーがホテルを一意に識別するために使用する ID。
SiteType	サイトの種類	ユーザーがホテルを検索するために使用したBing Web サイト。使用可能な値を次に示します。 LocalUniversal - Bing.com を使用してホテルを検索したユーザー MapResults - Bing.com/maps を使用してホテルを検索したユーザー PropertyPromotionAd - ユーザーはマップ検索に表示される最初の結果ページを確認していました。
SlotType	スロットの種類	結果ページでの広告の配置。使用可能な値を次に示します。 A - 広告が読み込まれるときに結果ページに表示される優先度スロット。 M - ユーザーが [ その他の料金] をクリックした後にのみ広告が表示されるセカンダリスロット。
SubAccountId	サブアカウント ID	サブアカウント (宿泊キャンペーン) を一意に識別する ID。
SubAccountName	サブアカウント名	サブアカウントの表示名。
UserCountry	ユーザーの国	ユーザーが配置されている国または地域の 2 文字の ISO 3116 国コード。たとえば、us for 米国。メモ： 2018 年 8 月 2 日より前の UserCountry には、発行元の国または地域が含まれています。 2018 年 8 月 2 日以降、UserCountry にはユーザーの国または地域が含まれます。

メジャー列

列名	レポート列名	説明
AverageCPC	平均クリック単価	クリックあたりの平均コスト。これは、すべてのクリックの合計コストをクリック数で割って計算されます。コストは、アカウントの通貨で行われます。データは 2017 年 12 月 6 日から入手できます。
AverageCPCUSD	平均 CPC USD	クリックあたりの平均コスト。これは、すべてのクリックの合計コストをクリック数で割って計算されます。コストは米ドルです。
AveragePosition	Avg. pos。	結果ページでの広告の平均掲載位置。位置は、すべてのスロットの他のすべての広告に対するページ上の広告の順序を指します。
AverageSlotPosition	平均スロット pos。	スロットタイプの広告の平均位置。このメトリックを含める場合は、SlotType ディメンション列も含める必要があります。
AvgBookedABW	平均予約 ABW	ホテルの平均高度な予約期間。平均は (予約された ABW/変換) として計算されます。続きを読む。
AvgBookedNights	平均予約日数	ホテルの平均宿泊日数。平均はとして計算されます (予約された宿泊数/コンバージョン数の合計)。続きを読む。
BookedABW	予約済み ABW	ホテルの詳細な予約期間の合計日数。続きを読む。
クリック	クリック	広告がクリックされた回数。
ClickShare	[共有] をクリックします	広告に対して行われたクリックの割合。ターゲットとした市場でのクリックの総数に対する割合。たとえば、対象市場でこの日に発生した推定 1,000 回のクリックのうち、約 230、つまり 23% でした。値の範囲は 0.0 から 1.0 です。続きを読む。
変換	変換	ホテル予約。続きを読む。
ConversionRate	コンバージョン率	コンバージョン率。レートは(コンバージョン/クリック数)*100として計算されます。続きを読む。
公認会計士	公認会計士	取得あたりのコスト。コストは (支出/コンバージョン) として計算されます。
Ctr	Ctr	広告のクリック率。 CTR は、広告がクリックされた回数をインプレッション数で割って計算されます。続きを読む。
EligibleImpressions	対象となる impr。	実現されたインプレッションと未実現インプレッションの合計数 (インプレッション数と見逃したインプレッション数)。続きを読む。
インプレッション	Impr。	広告が表示された回数。
GrossRevenue	総収益	税金を含む合計収益。続きを読む
GrossRevenuePerClick	総収益 / クリック	クリックあたりの総収益。クリックあたりの収益は、(総収益/クリック数) として計算されます。続きを読む。
GrossRevenuePerConv	総収益/コンバージョン数	コンバージョンあたりの総収益。コンバージョンごとの収益は、(総収益/換算) として計算されます。続きを読む。
GrossROAS	総広告費用対効果	広告費用の総収益。 ROAS は、(総収益/支出) * 100 として計算されます。続きを読む。
ImpressionShare	Impr。 share	ターゲットとした市場で使用可能なインプレッションの合計のうち、インプレッションの割合。たとえば、ターゲット市場でこの日に発生した推定 59,000 インプレッションのうち、2,300 または 3% を受け取りました。値の範囲は 0.0 から 1.0 です。続きを読む。
MissedImpressions	見逃した impr。	失われたインプレッションの合計数。これは、次の列の合計です。 MissedImpressionsInsufficientBid MissedImpressionsNoTax MissedImpressionsOther MissedImpressionsSpendingCapReached 続きを読む。
MissedImpressionsInsufficientBid	見逃した impr。入札が不十分	入札額が低く、オークションマーケットプレースでうまく競合していないために失われたインプレッションの数。続きを読む。
MissedImpressionsNoTax	見逃した impr。税金なし	ホテルが税金を指定していないために失われたインプレッションの数。続きを読む。
MissedImpressionsOther	見逃した impr。他	他のすべての理由で失われたインプレッションの数。通常、[ その他のレート ] セクションでは低いランク付けまたはレートを使用できますが、ユーザーはセクションを展開してレートを表示しませんでした。続きを読む。
MissedImpressionsSpendingCapReached	見逃した impr。支出上限に達しました	1 日の使用制限に達したために失われたインプレッションの数。続きを読む。
NetRevenue	純収益	税を除く合計収益。続きを読む。
NetRevenuePerClick	純収益/クリック	クリックあたりの純収益。クリックあたりの収益は (純収益/クリック数) として計算されます。続きを読む。
NetRevenueConv	純収益/コンバージョン数	コンバージョンあたりの純収益。コンバージョンごとの収益は、(純収益/換算) として計算されます。続きを読む。
NetROAS	Net ROAS	広告費用の純収益。 ROAS は、(純収益/支出) * 100 として計算されます。
過ごす	過ごす	すべてのクリックの合計コスト。コストは、アカウントの通貨で行われます。データは 2017 年 12 月 6 日から入手できます。続きを読む。
SpendUSD	USD を使う	すべてのクリックの合計コスト。コストは米ドルです。
TotalBookedNights	予約された滞在期間	ホテルの予約済みの合計宿泊日数。続きを読む。

要求に少なくとも 1 つのディメンション列と 1 つのメジャー列を含める必要があるルールに加えて、音声共有 (SOV) 列を含むレポートには、次のディメンション列の少なくとも 1 つが含まれている必要があります。

HotelGroupId
HotelId
PartnerHotelId
SubAccountId

SOV 列を次に示します。

ClickShare
EligibleImpressions
ImpressionShare
MissedImpressions
MissedImpressionsInsufficientBid
MissedImpressionsNoTax
MissedImpressionsOther
MissedImpressionsSpendingCapReached

注:

SOV データは、2018 年 5 月 1 日から入手できます。 2018 年 5 月 1 日より前の日付を含むレポート期間を指定した場合、SOV フィールドには 5 月 1 日より前の日付の 0 (0) の値が含まれます。

サンプルパフォーマンスレポート

次に、レポートのヘッダー行と列の例を示します。

"Performance report (October 30, 2017 - November 29, 2017)"
Request Id: f11b6610-5b85-4d7f-97ad-69668eb9da11

Date,Subaccount ID,Hotel group ID,Clicks,CTR,Impr.,Spend,User country

最初のヘッダー行には、レポートの名前と要求されたレポート期間が含まれます。 2 番目のヘッダー行には、レポートの要求 ID が含まれています。レポートに問題がある場合は、サポートに問い合わせて問題に関するヘルプを取得するときに ID を使用します。

注:

ホテル ID や広告グループ ID などの ID は、角かっこ ([1234567890] など) で囲まれます。

ホテル価格広告レポート API

レポートの要求

レポート ジョブの状態のポーリング

レポートのダウンロード

レポート データのフィルター処理

レポートにパフォーマンスの不履行のホテルを含む

IncludeNonPerformingHotels は、グループを移動したホテルのレポートにどのような影響がありますか?

閉じられた書籍

パフォーマンス レポート列

ディメンション列

メジャー列

音声の共有

サンプル パフォーマンス レポート

その他のリソース

レポートジョブの状態のポーリング

レポートデータのフィルター処理

パフォーマンスレポート列

サンプルパフォーマンスレポート