開発者ガイドの概要

Amazon Ads APIの概要

レポート

requestReportオペレーションを使用してパフォーマンスレポートを取得します。キャンペーンデータを取得する方法は複数あり、レポートを使用することが最も効率的な方法であるとは限りません。キャンペーン構造とそのすべてのエンティティ(広告グループ、キーワード、プロダクト広告など)のレコードをダウンロードする場合は、キャンペーンのすべての要素のリストをリクエストするのではなく、エンティティのスナップショットを作成することをおすすめします。詳細については、スナップショットをご覧ください。

**注:**レポートを生成(POST)する場合、広告タイプがスポンサープロダクト広告とスポンサーブランド広告のレポートには別々のエンドポイントがあります。これらのエンドポイントは、各セクションの最初に示されています。レポートIDを取得してレポートをダウンロード(GET)する場合、広告タイプに基づいてエンドポイントを区別する必要はありません。

次の表は、サービス管理リソースによってサポートされるURLスペースとHTTPメソッドに応じたサービスの動作を示しています。

メソッド URL ユースケース
POST /{recordType}/report レポートするパフォーマンスデータがある1つのタイプのすべてのエンティティのパフォーマンスレポートの作成をリクエストします。
GET /reports/{reportId} 以前にリクエストしたパフォーマンスレポートのステータス、メタデータ、場所を取得します。

操作

requestReport

POST /{recordType}/report       

 {                                
   "campaignType": {campaignType},
   "segment": {segment},           
   "reportDate": {reportDate},     
   "metrics": {metrics}             
 }                                

パラメーター

パラメーター名 タイプ 指定対象 説明
recordType string URL レポートを生成する対象となるエンティティのタイプ。campaignsadGroupskeywordsproductAdsasinsのいずれかにする必要があります。
campaignType string POSTボディ パフォーマンスデータを生成する対象となるキャンペーンのタイプ。sponsoredProductsまたはheadlineSearchにする必要があります
segment string POSTボディ オプション。レポートをセグメント化するディメンション。指定する場合は、キーワードレポートの場合はquery、キャンペーンレポートの場合はplacementにする必要があります。
reportDate string POSTボディ パフォーマンスレポートを取得するYYYYMMDD形式の日付。タイムゾーンは、レポートのリクエストに使用されるプロファイルによって指定されます。この日付が今日の場合、パフォーマンスレポートに部分的な情報が含まれている可能性があります。60日より前のデータのレポートは利用できません。データ遅延の詳細については、開発者メモセクションのサービス保証に関する説明をご覧ください。
metrics string POSTボディ レポートに含める指標のカンマ区切りのリスト。

レスポンス

ステータスコード レスポンスオブジェクト
202 - success ReportResponse
401 - unauthorized Error
406 – not acceptable Error(レポート日付が古すぎるため失敗しました)
422 - unprocessable entity Error(パラメーターが正しくないため失敗しました)

getReport

GET /reports/{reportId}

reportIdで識別される、以前にリクエストされたレポートを取得します。

パラメーター

パラメーター名 タイプ 指定対象 説明
reportId number URLパス リクエストされたレポートのID

レスポンス

ステータスコード レスポンスオブジェクト
200 - success ReportResponse
401 - unauthorized Error
404 - report not found Error
404 - not found server Error

ReportResponseにはレポートステータスが含まれます。レポートが 完了すると、locationフィールドにはレポートが含まれるgzipファイルの リダイレクトURLが表示されます。詳細については、レポートのダウンロードをご覧ください。

有効なレポートリクエスト

指定したパラメーターが認識されないか、パラメーターの組み合わせが サポートされていない場合、レポートリクエストは422を返します。特に、 recordTypeの選択により、特定のセグメントの使用が 制限される場合があります。クエリセグメンテーションは、キーワードレポートとの組み合わせでのみ 使用できます。

「404 - Not Found Server」エラーが表示される場合は、entityTypeエンドポイントが正しく入力されていることを確認してください。campaignsadGroupskeywordsasinsproductAdsのずれかにする必要があります。

リソースの表現

ReportResponse

{
    "title": "ReportResponse",
    "type": "object",
    "properties": {   
      "reportId": {
           "description": "The ID of the report that was requested.",
           "type": "string"
       },
      "recordType": {
           "description": "The record type of the report.It can be campaigns, adGroups, productAds or keywords.",
           "type": "string"
       },
       "status": {
           "description": "The status of the generation of the report, it can be IN_PROGRESS, SUCCESS or FAILURE.",
           "type": "string"
       },
       "statusDetails": {
           "description": "Description of the status.",
           "type": "string"
       },
       "location": {
           "description": "The URI from the API service from which a redirect to the report can be found.It's only available if status is SUCCESS.",
           "type": "string"
       },
       "fileSize": {
           "description": "The size of the report file in bytes.It's only available if status is SUCCESS.",
           "type": "number"
       }
    }
}

エラー

開発者メモで説明されているエラーオブジェクトの戻り値形式をご覧ください。

レポートファイル形式

レポートファイルには、エンティティごとに1行が含まれ、それぞれにパフォーマンスデータが 存在します。これらのレコードは、 recordTypeに対応するID属性、セグメント(指定されている場合)、 リクエスト内の各指標を含むJSONとして表されます。

たとえば、次の呼び出しでレポートがリクエストされたとします。

POST /keywords/report                

 {                                     

 "campaignType": "sponsoredProducts",
 "segment":"query",                   
 "reportDate":"20180310",             
 "metrics":"impressions,clicks"        

 }                                     |

次のようなレポートが表示されます。

[                                                                                           
 {"keywordId":123, "query": "red iphone case", "impressions": 584920, "clicks": 2989},        
 {"keywordId":123, "query": "blue iphone 6s case", "impressions": 8348230, "clicks": 16483},  
 {"keywordId":456, "query": "chuck taylor all star", "impressions": 83910, "clicks": 2483},   
 {"keywordId":456, "query": "converse chuck taylor", "impressions": 2349190, "clicks": 1238},
 {"keywordId":456, "query": "chuck taylor", "impressions": 291827, "clicks": 1289},           
 {"keywordId":789, "query": "rare earth magnets", "impressions": 99375092, "clicks": 912037},
 {"keywordId":789, "query": "magnets", "impressions": 93894023, "clicks": 238482},            
 {"keywordId":789, "query": "strong magnets", "impressions": 292, "clicks": 1}                 
]

レポートのダウンロード

レポートが完了すると、locationフィールドには生成されたレポートに対するダウンロードアクションの URIが表示されます。このURIに対するリクエストには 認証が必要なので、認証ヘッダーを 渡す必要があります。これらのリクエストへのレスポンスにはボディは含まれず、 locationヘッダーにS3ファイルの場所が入力された307リダイレクトが 返されます。生成されるファイルの保存場所は、有効期間が短くなっています (30秒で期限切れになります)。クライアントでファイルをダウンロードできるようになる前にこの時間が経過した場合、 クライアントはダウンロードアクションURIに対して 別のリクエストを行うことができます。

S3のレポートファイルはgzipで圧縮されていることに注意してください。

レポート指標

次の表は、レポートインターフェイスでリクエストできる レポート指標をまとめたものです。レポートタイプごとに異なる指標を 使用できます。

キャンペーンレポート

次の指標を使用して、campaignsタイプのレポートをリクエストできます。

指標 詳細
bidPlus ディメンション指標。開発者メモのプレミアム入札調整をご覧ください。
campaignName キャンペーン固有の名称。
campaignId キャンペーン固有の数値ID。
campaignStatus キャンペーンのステータス。
campaignBudget キャンペーンに割り当てられた予算合計。
impressions 広告の合計インプレッション数。
clicks 広告の合計クリック数。
cost 全クリック数の合計コスト。クリック数で割って平均クリック単価を求めることができます。
attributedConversions1d 広告のクリックから1日以内に発生した広告起因のコンバージョンイベント数。
attributedConversions7d 広告のクリックから7日以内に発生した広告起因のコンバージョンイベント数。
attributedConversions14d 広告のクリックから14日以内に発生した広告起因のコンバージョンイベント数。
attributedConversions30d 広告のクリックから30日以内に発生した広告起因のコンバージョンイベント数。
attributedConversions1dSameSKU 購入されたSKUが広告掲載されたSKUと同じ場合に、広告のクリックから1日以内に発生した広告起因のコンバージョンイベント数。
attributedConversions7dSameSKU 購入されたSKUが広告掲載されたSKUと同じ場合に、広告のクリックから7日以内に発生した広告起因のコンバージョンイベント数。
attributedConversions14dSameSKU 購入されたSKUが広告掲載されたSKUと同じ場合に、広告のクリックから14日以内に発生した広告起因のコンバージョンイベント数。
attributedConversions30dSameSKU 購入されたSKUが広告掲載されたSKUと同じ場合に、広告のクリックから30日以内に発生した広告起因のコンバージョンイベント数。
attributedUnitsOrdered1d 広告のクリックから1日以内に注文された広告起因の商品点数。
attributedUnitsOrdered7d 広告のクリックから7日以内に注文された広告起因の商品点数。
attributedUnitsOrdered14d 広告のクリックから14日以内に注文された広告起因の商品点数。
attributedUnitsOrdered30d 広告のクリックから30日以内に注文された広告起因の商品点数。
attributedSales1d 広告のクリックから1日以内に発生した広告起因の売上数。
attributedSales7d 広告のクリックから7日以内に発生した広告起因の売上数。
attributedSales14d 広告のクリックから14日以内に発生した広告起因の売上数。
attributedSales30d 広告のクリックから30日以内に発生した広告起因の売上数。
attributedSales1dSameSKU 購入されたSKUが広告掲載されたSKUと同じ場合に、広告のクリックから1日以内に発生した広告起因の売上の合計数。
attributedSales7dSameSKU 購入されたSKUが広告掲載されたSKUと同じ場合に、広告のクリックから7日以内に発生した広告起因の売上の合計数。
attributedSales14dSameSKU 購入されたSKUが広告掲載されたSKUと同じ場合に、広告のクリックから14日以内に発生した広告起因の売上の合計。
attributedSales30dSameSKU 購入されたSKUが広告掲載されたSKUと同じ場合に、広告のクリックから30日以内に発生した広告起因の売上の合計数。

広告グループレポート

次の指標を使用して、adGroupsタイプのレポートをリクエストできます。

指標 詳細
campaignName キャンペーン固有の名称。
campaignId キャンペーン固有の数値ID。
adGroupName 広告グループの固有の名称。
adGroupId 広告グループ固有の数値ID
impressions 広告の合計インプレッション数。
clicks 広告の合計クリック数。
cost 全クリック数の合計コスト。クリック数で割って平均クリック単価を求めることができます。
attributedConversions1d 広告のクリックから1日以内に発生した広告起因のコンバージョンイベント数。
attributedConversions7d 広告のクリックから7日以内に発生した広告起因のコンバージョンイベント数。
attributedConversions14d 広告のクリックから14日以内に発生した広告起因のコンバージョンイベント数。
attributedConversions30d 広告のクリックから30日以内に発生した広告起因のコンバージョンイベント数。
attributedConversions1dSameSKU 購入されたSKUが広告掲載されたSKUと同じ場合に、広告のクリックから1日以内に発生した広告起因のコンバージョンイベント数。
attributedConversions7dSameSKU 購入されたSKUが広告掲載されたSKUと同じ場合に、広告のクリックから7日以内に発生した広告起因のコンバージョンイベント数。
attributedConversions14dSameSKU 購入されたSKUが広告掲載されたSKUと同じ場合に、広告のクリックから14日以内に発生した広告起因のコンバージョンイベント数。
attributedConversions30dSameSKU 購入されたSKUが広告掲載されたSKUと同じ場合に、広告のクリックから30日以内に発生した広告起因のコンバージョンイベント数。
attributedUnitsOrdered1d 広告のクリックから1日以内に注文された広告起因の商品点数。
attributedUnitsOrdered7d 広告のクリックから7日以内に注文された広告起因の商品点数。
attributedUnitsOrdered14d 広告のクリックから14日以内に注文された広告起因の商品点数。
attributedUnitsOrdered30d 広告のクリックから30日以内に注文された広告起因の商品点数。
attributedSales1d 広告のクリックから1日以内に発生した広告起因の売上数。
attributedSales7d 広告のクリックから7日以内に発生した広告起因の売上数。
attributedSales14d 広告のクリックから14日以内に発生した広告起因の売上数。
attributedSales30d 広告のクリックから30日以内に発生した広告起因の売上数。
attributedSales1dSameSKU 購入されたSKUが広告掲載されたSKUと同じ場合に、広告のクリックから1日以内に発生した広告起因の売上の合計数。
attributedSales7dSameSKU 購入されたSKUが広告掲載されたSKUと同じ場合に、広告のクリックから7日以内に発生した広告起因の売上の合計数。
attributedSales14dSameSKU 購入されたSKUが広告掲載されたSKUと同じ場合に、広告のクリックから14日以内に発生した広告起因の売上の合計。
attributedSales30dSameSKU 購入されたSKUが広告掲載されたSKUと同じ場合に、広告のクリックから30日以内に発生した広告起因の売上の合計数。

キーワードレポート

次の指標を使用して、keywordsタイプのレポートをリクエストできます。

指標 詳細
campaignName キャンペーン固有の名称。
campaignId キャンペーン固有の数値ID。
keywordId 入札に使用されたキーワードのID。
keywordText 入札に使用されたキーワードまたはフレーズのテキスト。
matchType 入札に使用されたキーワードまたはフレーズのマッチタイプ。broadphraseexactのいずれかにする必要があります。
impressions 広告の合計インプレッション数。
clicks 広告の合計クリック数。
cost 全クリック数の合計コスト。クリック数で割って平均クリック単価を求めることができます。
attributedConversions1d 広告のクリックから1日以内に発生した広告起因のコンバージョンイベント数。
attributedConversions7d 広告のクリックから7日以内に発生した広告起因のコンバージョンイベント数。
attributedConversions14d 広告のクリックから14日以内に発生した広告起因のコンバージョンイベント数。
attributedConversions30d 広告のクリックから30日以内に発生した広告起因のコンバージョンイベント数。
attributedConversions1dSameSKU 購入されたSKUが広告掲載されたSKUと同じ場合に、広告のクリックから1日以内に発生した広告起因のコンバージョンイベント数。
attributedConversions7dSameSKU 購入されたSKUが広告掲載されたSKUと同じ場合に、広告のクリックから7日以内に発生した広告起因のコンバージョンイベント数。
attributedConversions14dSameSKU 購入されたSKUが広告掲載されたSKUと同じ場合に、広告のクリックから14日以内に発生した広告起因のコンバージョンイベント数。
attributedConversions30dSameSKU 購入されたSKUが広告掲載されたSKUと同じ場合に、広告のクリックから30日以内に発生した広告起因のコンバージョンイベント数。
attributedUnitsOrdered1d 広告のクリックから1日以内に注文された広告起因の商品点数。
attributedUnitsOrdered7d 広告のクリックから7日以内に注文された広告起因の商品点数。
attributedUnitsOrdered14d 広告のクリックから14日以内に注文された広告起因の商品点数。
attributedUnitsOrdered30d 広告のクリックから30日以内に注文された広告起因の商品点数。
attributedSales1d 広告のクリックから1日以内に発生した広告起因の売上数。
attributedSales7d 広告のクリックから7日以内に発生した広告起因の売上数。
attributedSales14d 広告のクリックから14日以内に発生した広告起因の売上数。
attributedSales30d 広告のクリックから30日以内に発生した広告起因の売上数。
attributedSales1dSameSKU 購入されたSKUが広告掲載されたSKUと同じ場合に、広告のクリックから1日以内に発生した広告起因の売上の合計数。
attributedSales7dSameSKU 購入されたSKUが広告掲載されたSKUと同じ場合に、広告のクリックから7日以内に発生した広告起因の売上の合計数。
attributedSales14dSameSKU 購入されたSKUが広告掲載されたSKUと同じ場合に、広告のクリックから14日以内に発生した広告起因の売上の合計。
attributedSales30dSameSKU 購入されたSKUが広告掲載されたSKUと同じ場合に、広告のクリックから30日以内に発生した広告起因の売上の合計数。

プロダクト広告レポート

次の指標を使用して、productAdsタイプのレポートをリクエストできます。

指標 詳細
campaignName キャンペーン固有の名称。
campaignId キャンペーン固有の数値ID。
adGroupName 広告グループの固有の名称。
adGroupId 広告グループ固有の数値ID
impressions 広告の合計インプレッション数。
clicks 広告の合計クリック数。
cost 全クリック数の合計コスト。クリック数で割って平均クリック単価を求めることができます。
currency ディメンション指標。
asin 広告掲載されるASIN。出品者様とお取引企業様の両方でこれを利用できます。
sku 広告掲載されるSKU。お取引企業様はご利用いただけません。
attributedConversions1d 広告のクリックから1日以内に発生した広告起因のコンバージョンイベント数。
attributedConversions7d 広告のクリックから7日以内に発生した広告起因のコンバージョンイベント数。
attributedConversions14d 広告のクリックから14日以内に発生した広告起因のコンバージョンイベント数。
attributedConversions30d 広告のクリックから30日以内に発生した広告起因のコンバージョンイベント数。
attributedConversions1dSameSKU 購入されたSKUが広告掲載されたSKUと同じ場合に、広告のクリックから1日以内に発生した広告起因のコンバージョンイベント数。
attributedConversions7dSameSKU 購入されたSKUが広告掲載されたSKUと同じ場合に、広告のクリックから7日以内に発生した広告起因のコンバージョンイベント数。
attributedConversions14dSameSKU 購入されたSKUが広告掲載されたSKUと同じ場合に、広告のクリックから14日以内に発生した広告起因のコンバージョンイベント数。
attributedConversions30dSameSKU 購入されたSKUが広告掲載されたSKUと同じ場合に、広告のクリックから30日以内に発生した広告起因のコンバージョンイベント数。
attributedUnitsOrdered1d 広告のクリックから1日以内に注文された広告起因の商品点数。
attributedUnitsOrdered7d 広告のクリックから7日以内に注文された広告起因の商品点数。
attributedUnitsOrdered14d 広告のクリックから14日以内に注文された広告起因の商品点数。
attributedUnitsOrdered30d 広告のクリックから30日以内に注文された広告起因の商品点数。
attributedSales1d 広告のクリックから1日以内に発生した広告起因の売上数。
attributedSales7d 広告のクリックから7日以内に発生した広告起因の売上数。
attributedSales14d 広告のクリックから14日以内に発生した広告起因の売上数。
attributedSales30d 広告のクリックから30日以内に発生した広告起因の売上数。
attributedSales1dSameSKU 購入されたSKUが広告掲載されたSKUと同じ場合に、広告のクリックから1日以内に発生した広告起因の売上の合計数。
attributedSales7dSameSKU 購入されたSKUが広告掲載されたSKUと同じ場合に、広告のクリックから7日以内に発生した広告起因の売上の合計数。
attributedSales14dSameSKU 購入されたSKUが広告掲載されたSKUと同じ場合に、広告のクリックから14日以内に発生した広告起因の売上の合計。
attributedSales30dSameSKU 購入されたSKUが広告掲載されたSKUと同じ場合に、広告のクリックから30日以内に発生した広告起因の売上の合計数。

ASINレポート

次の指標を使用して、asinsタイプのレポートをリクエストできます。

指標 詳細
campaignName キャンペーン固有の名称。
campaignId キャンペーン固有の数値ID。
adGroupName 広告グループの固有の名称。
adGroupId 広告グループ固有の数値ID
keywordId キーワード固有の数値ID
keywordText 入札に使用されたキーワードまたはフレーズ。
asin 広告掲載対象のASIN。
otherAsin 広告掲載対象以外のASINの非ディメンション指標。
sku 広告掲載対象の固有のSKU。
currency ディメンション指標。
matchType broadphraseexactのいずれか。
attributedUnitsOrdered1dOtherSKU 注文された他のASIN(SKU)点数。1日。
attributedUnitsOrdered7dOtherSKU 注文された他のASIN(SKU)点数。7日。
attributedUnitsOrdered14dOtherSKU 注文された他のASIN(SKU)点数。14日。
attributedUnitsOrdered30dOtherSKU 注文された他のASIN(SKU)点数。30日。
attributedSales1dOtherSKU 別のASIN(SKU)の売上。1日。
attributedSales7dOtherSKU 別のASIN(SKU)の売上。7日。
attributedSales14dOtherSKU 別のASIN(SKU)の売上。14日。
attributedSales30dOtherSKU 別のASIN(SKU)の売上。30日。

スポンサーブランド広告レポート

スポンサーブランド広告(SB)(旧称はヘッドライン検索広告)は、スポンサープロダクト広告とは異なる特徴やページの掲載枠オプションを持つ 広告プロダクトの一種です。スポンサーブランド広告のレポート機能は、APIを介してSBキャンペーンの レポート情報のみを提供するように設計されています。SB広告とキャンペーンを作成または変更するには、 引き続きWebインターフェイスを使用します。スポンサープロダクト広告と スポンサーブランド広告を区別するオブジェクトは、campaignTypeオブジェクトです。

レポートエンドポイント

スポンサーブランド広告のレポートデータは、以下のエンドポイントからのみ利用できます。

スポンサーブランド広告のレポートの制約

スポンサーブランド広告のレポートデータをスポンサープロダクト広告のデータと組み合わせて1つのレポートに することはできません。SBキャンペーンのレポートデータを取得するには、campaignTypeheadlineSearch を使用します。SBには14日間のデータのみ使用できます。 1、7、30日間隔のアトリビューションウィンドウは利用できません。スポンサーブランド広告では、 クエリセグメンテーションまたは検索ワードレポートはサポートされません。

**注:**モックデータは、提供されているサンドボックステスト環境で使用され、 14日以外の追加レポート間隔はサンドボックスでのみ 利用できます。実稼働環境では、14日間の売上 レポートデータのみが利用可能です。

スポンサーブランド広告の新しいレポートフィールド

SBのレポートには次のフィールドが追加されています。

レポートタイプ 新しいフィールド
キャンペーン campaignTypecampaignBudgetcampaignBudgetTypecampaignStatus
広告グループ campaignIdcampaignNamecampaignTypecampaignBudgetcampaignBudgetTypecampaignStatusadGroupNameadGroupId
キーワード campaignIdcampaignNameadGroupIdadGroupNamecampaignBudgetTypecampaignStatuskeywordTextmatchType

スポンサーブランド広告のエンティティは、スナップショットレポートには含まれません。SBキャンペーンに関する レポートを取得するには、次のセクションに記載されているSBレポートの指標を 使用します。 次の指標を使用して、headlineSearchタイプのレポートをリクエストできます。

*** **注:**特定の指標をレポートリクエストに含めると、インプレッションやクリックのないものも含め、すべてのSBキャンペーンのデータが返されます。

スポンサーブランド広告レポートの指標

指標 詳細
campaignName*** 広告主様が作成したキャンペーン名。
campaignId 固有のキャンペーンID
campaignType headlineSearchまたはsponsoredProductsのいずれか。
campaignStatus*** キャンペーンの現在のステータス。
campaignBudget*** キャンペーン予算。
campaignBudgetType*** dailyまたはlifetimeのいずれか。
adGroupName*** 固有の広告グループ名
adGroupId 固有の広告グループID。
keywordText 入札に使用されたキーワードまたはフレーズ。
matchType broadphraseexactのいずれか。
impressions 広告の合計インプレッション数。
clicks 広告の合計クリック数。
cost 全クリック数の合計コスト。クリック数で割って平均クリック単価を求めることができます。
attributedSales14d 広告のクリックから14日以内に発生した広告起因の売上数。
attributedSales14dSameSKU 購入されたSKUが広告掲載されたSKUと同じ場合に、広告のクリックから14日以内に発生した広告起因の売上の合計。
attributedConversions14d 広告のクリックから14日以内に発生した広告起因のコンバージョンイベント数。
attributedConversions14dSameSKU 購入されたSKUが広告掲載されたSKUと同じ場合に、広告のクリックから14日以内に発生した広告起因のコンバージョンイベント数。