開発者ガイドの概要

Amazon Ads APIの概要

戦略推奨APIの使用を開始する

エンドポイント

戦略推奨APIでは、次の3つのAPIエンドポイントを利用できます。

  1. POST /recommendations/list - 広告主のキャンペーンに関するすべての推奨事項を一覧表示します。パートナー様と広告主様は、フィルター（広告商品、推奨タイプなどを含む）を使用して検索結果をフィルタリングできます。
  2. PUT /recommendations/{recommendationId} - 推奨事項の値を更新します。
  3. POST /recommendations/apply - 一度に1件以上の推奨事項を（最大100件）適用します。

始める前に

3つのエンドポイントはどれも、次の認可用ヘッダーが呼び出しに必要になります。

パラメーター 説明
Amazon-Advertising-API-ClientId Login with Amazonアプリケーションに紐付けられているクライアントID。認証に使用されます。
Authorization アクセストークン。認証に使用されます。
Amazon-Advertising-API-Scope 特定のマーケットプレイスの広告アカウントに紐づけられたプロフィールID。必ず、プロフィールに紐づけられたマーケットプレイスの正しいベースURLを使用してください。

出品情報に関する推奨事項

推奨事項が利用可能な場合、広告主様とパートナー様は、POST /recommendations/listエンドポイントを使用して推奨事項のリストをリクエストできます。このエンドポイントでは、返される推奨事項のカスタマイズに使用可能なさまざまなフィルターに対応しています。

対応しているフィルター値

これらのフィルターの組み合わせを1つ以上使用して、特定の推奨事項を絞り込むことができます。

| フィールド | 指定できる値 | |--- |--- | | RECOMMENDATION_ID | 文字列 | | AD_PRODUCT | [SP、SB、SD]のいずれか | | RECOMMENDATION_TYPE | すべての推奨事項タイプの説明を表示します。[NEW_CAMPAIGN、NEW_VIDEO_CAMPAIGN、NEW_AD_GROUP、CAMPAIGN_BIDDING_STRATEGY、CAMPAIGN_BUDGET、CAMPAIGN_END_DATE、CAMPAIGN_TOP_PLACEMENT、CAMPAIGN_PRODUCT_PLACEMENT、CAMPAIGN_STATE、NEW_CAMPAIGN_BIDDING_RULE、CAMPAIGN_BIDDING_RULE、NEW_CAMPAIGN_BUDGET_RULE、CAMPAIGN_BUDGET_RULE、AD_GROUP_STATE、AD_GROUP_DEFAULT_BID、AD_GROUP_BID_OPTIMIZATION、 NEW_KEYWORD、KEYWORD_BID、KEYWORD_STATE、NEW_NEGATIVE_KEYWORD、NEGATIVE_KEYWORD_STATE、NEW_PRODUCT_AD、PRODUCT_AD_STATE、NEW_PAT、PAT_STATE、PAT_BID、NEW\ _NEGATIVE_PAT、NEGATIVE_PAT_STATE、NEW_AUDIENCE_TARGETING、AUDIENCE_TARGETING_STATE、AUDIENCE_TARGETING_BID、NEW_NEGATIVE_AUDIENCE_TARGETING、NEGATIVE_AUDIENCE_TARGETING_STATE]のいずれか | | ステータス | [PUBLISHED、APPLY\IN\PROGRESS、APPLY_SUCCESS、APPLY\FAILED、REJECTED]のいずれか | | GROUPING_TYPE | [CAMPAIGN_INCREASE_CLICKS、UNDERPERFORMING_CAMPAIGN_INCREASE_CLICKS]のいずれか |

例

推奨事項をすべて取得する

プロフィールに紐づけられているすべての推奨事項を表示するには、空のリクエスト本文を使用して呼び出しを行います。

リクエスト

curl --location 'https://advertising-api.amazon.com/recommendations/list' \
--header 'Amazon-Advertising-API-ClientId: amzn1.application-oa2-client.xxxxxxxxx' \
--header 'Authorization: Bearer Atza|xxxxxxx' \
--header 'Amazon-Advertising-API-Scope: xxxxxxxxxx' \
--data '{
}'

応答

この例では、スポンサーブランド広告キャンペーンへの新しいキーワード2件の追加に関する推奨事項が返されています。

"recommendations": [
        {
            "adGroupId": "2223334444",
            "adId": null,
            "adProduct": "SB",
            "applyFailureReason": null,
            "asin": null,
            "asinGroupTemplateId": null,
            "budgetRecommendation": null,
            "budgetRule": null,
            "campaignId": "11122223333",
            "campaignTemplateId": null,
            "consolidatedRecommendation": null,
            "currentValue": null,
            "estimatedImpact": null,
            "groupingType": null,
            "keywordSortingDimension": null,
            "keywordSortingRank": null,
            "recommendationId": "xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxx1",
            "recommendationType": "NEW_KEYWORD",
            "recommendedValue": "1.44",
            "resolvedTargeting": "mens shoes",
            "ruleBasedBidding": null,
            "sku": null,
            "status": "PUBLISHED",
            "targetId": null,
            "targeting": "mens shoes",
            "targetingMatchType": "EXACT"
        },
        {
            "adGroupId": "2223334444",
            "adId": null,
            "adProduct": "SB",
            "applyFailureReason": null,
            "asin": null,
            "asinGroupTemplateId": null,
            "budgetRecommendation": null,
            "budgetRule": null,
            "campaignId": "11122223333",
            "campaignTemplateId": null,
            "consolidatedRecommendation": null,
            "currentValue": null,
            "estimatedImpact": null,
            "groupingType": null,
            "keywordSortingDimension": null,
            "keywordSortingRank": null,
            "recommendationId": "xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxx2",
            "recommendationType": "NEW_KEYWORD",
            "recommendedValue": "2.02",
            "resolvedTargeting": "men socks",
            "ruleBasedBidding": null,
            "sku": null,
            "status": "PUBLISHED",
            "targetId": null,
            "targeting": "men socks",
            "targetingMatchType": "EXACT"
        }
]

すべてのスポンサープロダクト広告の推奨事項を取得する

この例では、スポンサープロダクト広告キャンペーンのみに関連する推奨事項をリクエストする方法を示します。

リクエスト

{
    "maxResults": 10,
    "filters": [
            {
                "include": true,
                "field": "AD_PRODUCT",
                "values": [
                        "SP"
          ],
                "operator": "EXACT"
            }
   ]
}

応答

この応答は、既存のスポンサープロダクト広告キャンペーンの予算を増やすことをすすめる推奨事項の例を示しています。


"recommendations": [
{
    "nextToken": null,
    "recommendations": [{
        "adGroupId": null,
        "adId": null,
        "adProduct": "SP",
        "applyFailureReason": null,
        "asin": null,
        "asinGroupTemplateId": null,
        "budgetRecommendation": {
            "sevenDaysMissedOpportunities": {
                "endDate": "2023-05-13",
                "estimatedMissedClicksLower": 310,
                "estimatedMissedClicksUpper": 937,
                "estimatedMissedImpressionsLower": 21856,
                "estimatedMissedImpressionsUpper": 65585,
                "estimatedMissedSalesLower": 391.0,
                "estimatedMissedSalesUpper": 1180.0,
                "percentTimeInBudget": 0.7434,
                "startDate": "2023-05-07"
            }
        },
        "budgetRule": null,
        "campaignId": "111222333344",
        "campaignTemplateId": null,
        "consolidatedRecommendation": null,
        "currentValue": "33.0",
        "estimatedImpact": null,
        "groupingType": null,
        "keywordSortingDimension": null,
        "keywordSortingRank": null,
        "recommendationId": "xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxx2",
        "recommendationType": "CAMPAIGN_BUDGET",
        "recommendedValue": "100.0",
        "resolvedTargeting": null,
        "ruleBasedBidding": null,
        "sku": null,
        "status": "PUBLISHED",
        "targetId": null,
        "targeting": null,
        "targetingMatchType": null
    }],
    "totalResults": 1
}
]

応答に含まれているrecommendIdを使用すると、推奨事項を更新または適用できます。

推奨事項の更新

APIから返された推奨事項を更新する場合は、PUT /recommendations/{recommendationId}を使用します。編集可能なフィールドは、推奨事項のタイプによって異なります。

推奨値の組み合わせを更新する

| 推奨事項のタイプ | データ型 | |--- |--- | | CAMPAIGN_BUDGET、CAMPAIGN_TOP_PLACEMENT、CAMPAIGN_PRODUCT_PLACEMENT、AD_GROUP_DEFAULT_BID、NEW_KEYWORD、KEYWORD_BID、NEW_PRODUCT_TARGETING、PRODUCT_TARGETING_BID、NEW_AUDIENCE_TARGETING、AUDIENCE_TARGETING_BID | 数値 | | CAMPAIGN_END_DATE | 文字列(YYYY-MM-DD) | | AD_GROUP_BID_OPTIMIZATION | [CLICKS、CONVERSIONS、REACH]のいずれか | | CAMPAIGN_BIDDING_STRATEGY | [LEGACY_FOR_SALES、AUTO_FOR_SALES、MANUAL]のいずれか | | CAMPAIGN_STATE、AD_GROUP_STATE、KEYWORD_STATE、NEGATIVE_KEYWORD_STATE、PRODUCT_AD_STATE、PRODUCT_TARGETING_STATE、NEGATIVE_PRODUCT_TARGETING_STATE、AUDIENCE_TARGETING_STATE、NEGATIVE_AUDIENCE_TARGETING_STATE | [ENABLED、PAUSED、ARCHIVED]のいずれか |

例

この例では、予算を1000ではなく998に更新します。

リクエスト

PUT recommendations/xxxxxxx-xxxx-xxxxx-xxxx-xxxxx
{
    "recommendedValue":"998"
}

応答

{
    "recommendation": {
        "adGroupId": null,
        "adId": null,
        "adProduct": "SP",
        "applyFailureReason": null,
        "asin": null,
        "asinGroupTemplateId": null,
        "budgetRecommendation": null,
        "budgetRule": null,
        "campaignId": "11122333444",
        "campaignTemplateId": null,
        "consolidatedRecommendation": null,
        "currentValue": "1000",
        "estimatedImpact": null,
        "groupingType": null,
        "keywordSortingDimension": null,
        "keywordSortingRank": null,
        "recommendationId": "xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxx",
        "recommendationType": "CAMPAIGN_BUDGET",
        "recommendedValue": "998",
        "resolvedTargeting": null,
        "ruleBasedBidding": null,
        "sku": null,
        "status": "PUBLISHED",
        "targetId": null,
        "targeting": null,
        "targetingMatchType": null
    }
}

推奨事項の適用

推奨事項を確認したら、POST /recommendations/applyエンドポイントを使用して自動的に適用できます。このエンドポイントを使用すると、推奨事項を1件以上適用できます。

例

この例では、1つの推奨事項IDを適用しています。

リクエスト

POST recommendations/apply

{
    "recommendationIds": [
        "xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxx"
    ]
}

応答

{
    "failures": [],
    "successes": [{
        "index": 0,
        "recommendation": {
            "adGroupId": null,
            "adId": null,
            "adProduct": "SP",
            "applyFailureReason": null,
            "asin": null,
            "asinGroupTemplateId": null,
            "budgetRecommendation": null,
            "budgetRule": null,
            "campaignId": "11122333444",
            "campaignTemplateId": null,
            "consolidatedRecommendation": null,
            "currentValue": "1000",
            "estimatedImpact": null,
            "groupingType": null,
            "keywordSortingDimension": null,
            "keywordSortingRank": null,
            "recommendationId": "xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxx",
            "recommendationType": "CAMPAIGN_BUDGET",
            "recommendedValue": "998",
            "resolvedTargeting": null,
            "ruleBasedBidding": null,
            "sku": null,
            "status": "APPLY_SUCCESS",
            "targetId": null,
            "targeting": null,
            "targetingMatchType": null
        },
        "recommendationId": "xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxx",
        "success": {
            "code": "OK",
            "message": "Success."
        }
    }]
}
Amazon Advertising logo