◀ 2.

旧PA-API 5のリクエスト構造とCreators API移行の注意点

▶

旧PA-API 5の要求構造と、現在の商品APIへ移行するときの確認点を整理します。旧JSONを小文字へ置換するだけで移行できるわけではなく、送信先・認証・Resourcesを別々に確認します。

旧ItemSearchとPA-API5、後継Creators APIの違い

先に確認: 旧PA-APIと現在のCreators API

2026年10月確認。PA-API 5.0も公式の廃止案内の対象です。このページの旧PA-API例は保守・比較用で、現在の新規導入手順ではありません。旧APIの403をキー再発行や再試行だけで直そうとしないでください。

後継への移行は公式移行ガイドを確認します。旧AWSキーとSigV4ではなく、Creators API用のCredential ID / Secret / VersionとOAuth 2.0を使います。本文の旧フィールド名・旧SDKをそのまま現行APIへ適用しないでください。親のPA-APIの関連資料から各子ページも選択できます。

現行要求へ移すときの照合表

確認対象移行時に見ること
認証と送信先旧SigV4とwebservicesではなく、現行OAuthとCreators APIの送信先・必要ヘッダー
キーと値PartnerTagからpartnerTagなどの項目名だけでなく、値の型・操作・対象地域の制約
取得項目旧Offersをそのまま使わずOffersV2を確認。Resourcesを指定しても全商品で全項目が返る保証ではない
失敗の扱い通信失敗・HTTP失敗・本文内エラー・0件を分ける。秘密値やAuthorizationをログへ出さない

現行SearchItems仕様は操作と地域の対応を確認する入口です。価格単位など説明内に不一致がある数値は推測で補わず、対象地域の公式案内・SDK・検証環境で照合してください。旧応答の構造と解析の注意も参照できます。

この記事の要点
  • PA-API 5.0 は JSON-RPC 風、エンドポイントは POST https://webservices.amazon.co.jp/paapi5/<operation>
  • 主要 3 オペレーション: SearchItems(キーワード検索)、GetItems(ASIN 直接取得)、GetVariations(親 ASIN 配下のバリエーション)
  • 必須 body フィールド: PartnerTag / PartnerType: "Associates" / Marketplace
  • Resources 配列で取得したい項目を明示指定(ItemInfo.Title, Offers.Listings.Price, Images.Primary.Medium ...)
  • 認証は AWS V4 署名(Authorization ヘッダ)、IAM ではなくアソシエイト発行のキー
  • レートは対象APIの現行枠を確認。429と、廃止/資格による403を区別し、すべてを再試行しない

PA-API 5.0 リクエストの全体像

ここからのエンドポイント・PascalCaseの項目・署名方式は旧PA-API 5の資料です。JSON例は構造の比較用で、記載ASIN・Resources・数値の実通信成功を検証していません。

PA-API 5.0 は HTTP POST + JSON body + AWS V4 署名の API です。URL のパスがオペレーション名と対応します:

POST https://webservices.amazon.co.jp/paapi5/searchitems     ← キーワード検索
POST https://webservices.amazon.co.jp/paapi5/getitems        ← ASIN 直接取得(最大 10)
POST https://webservices.amazon.co.jp/paapi5/getvariations   ← 親 ASIN のバリエーション
POST https://webservices.amazon.co.jp/paapi5/getbrowsenodes  ← カテゴリ(BrowseNode)情報

SearchItems: キーワード検索

{
  "Keywords": "ルアー",
  "SearchIndex": "SportingGoods",
  "ItemCount": 10,
  "ItemPage": 1,
  "MinPrice": 50000,
  "MaxPrice": 500000,
  "SortBy": "Featured",
  "PartnerTag": "myassoc-22",
  "PartnerType": "Associates",
  "Marketplace": "www.amazon.co.jp",
  "Resources": [
    "Images.Primary.Large",
    "ItemInfo.Title",
    "ItemInfo.Features",
    "Offers.Listings.Price",
    "Offers.Listings.DeliveryInfo.IsPrimeEligible"
  ]
}
パラメータ意味例
Keywords検索キーワード"ノートPC"
SearchIndexカテゴリ(All / Books / Electronics 等)"All"
ItemCount1 ページ件数(最大 10)10
ItemPageページ番号(最大 10)1~10
MinPrice / MaxPrice旧APIの価格フィルタ。単位は対象API/地域の仕様を照合し、通貨名から推測しない例の50000を日本円500円と断定しない
SortByFeatured, NewestArrivals, Price:LowToHigh 等"Price:LowToHigh"
Brandブランド名フィルタ"Sony"
BrowseNodeIdカテゴリ ID(数値)"3210981"

GetItems: ASIN 直接取得

{
  "ItemIds": ["B08XXXXX1", "B09YYYYY2", "B0AZZZZZ3"],
  "ItemIdType": "ASIN",
  "PartnerTag": "myassoc-22",
  "PartnerType": "Associates",
  "Marketplace": "www.amazon.co.jp",
  "Resources": [
    "ItemInfo.Title",
    "ItemInfo.ByLineInfo",
    "Offers.Listings.Price",
    "Offers.Listings.Availability.Message",
    "CustomerReviews.StarRating",
    "CustomerReviews.Count"
  ]
}

ItemIds は最大 10 個まで。商品詳細ページ表示用に最適。

GetVariations: 親 ASIN のバリエーション

1 つの商品(例: Tシャツ)の色・サイズ違い ASIN を一括取得:

{
  "ASIN": "B0PARENT001",
  "VariationCount": 10,
  "VariationPage": 1,
  "PartnerTag": "myassoc-22",
  "PartnerType": "Associates",
  "Marketplace": "www.amazon.co.jp",
  "Resources": [
    "ItemInfo.Title",
    "VariationSummary.Price.HighestPrice",
    "VariationSummary.Price.LowestPrice",
    "VariationSummary.VariationDimension",
    "Offers.Listings.Price"
  ]
}

Resources の指定(主要なもの)

Resourcesは欲しい情報を明示する指定です。省略時の既定値は対象API・操作の仕様で確認し、すべてのフィールドが省略されるとは断定しません。

カテゴリ主要 Resources
商品情報ItemInfo.Title, ItemInfo.ByLineInfo, ItemInfo.Features, ItemInfo.ProductInfo, ItemInfo.TechnicalInfo
画像Images.Primary.Small / Medium / Large, Images.Variants.*
価格Offers.Listings.Price, Offers.Listings.SavingBasis, Offers.Summaries.LowestPrice
在庫Offers.Listings.Availability.Message, Offers.Listings.Availability.Type
配送Offers.Listings.DeliveryInfo.IsPrimeEligible, ...IsFreeShippingEligible
レビューCustomerReviews.StarRating, CustomerReviews.Count
BrowseNodeBrowseNodeInfo.BrowseNodes, BrowseNodeInfo.WebsiteSalesRank
親子関係ParentASIN, VariationSummary.*

レスポンスの構造

{
  "SearchResult": {
    "TotalResultCount": 1234,
    "SearchURL": "https://www.amazon.co.jp/s?k=...&tag=myassoc-22",
    "Items": [
      {
        "ASIN": "B08XXXXX",
        "DetailPageURL": "https://www.amazon.co.jp/dp/B08XXXXX?tag=myassoc-22",
        "Images": {
          "Primary": {
            "Large":  { "URL": "https://m.media-amazon.com/.../L.jpg", "Width": 500, "Height": 500 }
          }
        },
        "ItemInfo": {
          "Title": { "DisplayValue": "...", "Locale": "ja_JP" },
          "Features": { "DisplayValues": ["...", "..."] }
        },
        "Offers": {
          "Listings": [
            {
              "Id": "abc123...",
              "Price":   { "Amount": 1980, "Currency": "JPY", "DisplayAmount": "¥1,980" },
              "DeliveryInfo": { "IsPrimeEligible": true }
            }
          ]
        }
      }
    ]
  }
}

認証フロー

以下の旧PA-APIの4段階は履歴比較用です。Creators APIは別の資格情報・OAuth方式・送信先を使うため、そのまま実施しないでください。

  1. Amazon アソシエイトに登録 → 売上発生
  2. 「ツール」→「Product Advertising API」→ Access Key / Secret Key 発行
  3. Partner Tag(アソシエイト ID)は登録時に決定
  4. 各リクエストの Authorization ヘッダに AWS V4 署名を載せる

署名生成の詳細は 署名認証の方法(PHPサンプル ItemSearch) 記事を参照。

レート制限とエラーハンドリング

初期 TPS1 日当たり増枠条件
現行のAPI枠を確認旧PA-API枠を流用しない売上1件=1TPSと固定換算しない

下は旧記事の再試行断片です。メッセージに「429」が含まれるだけで再試行する判定は、本番用として勧めません。 正式なHTTP状態/エラーコード、再試行可能性、上限、待機指示を確認します。タイムアウト・期限・ジッター等は未実装で、PA-API廃止の403を再試行しても移行になりません:

<?php
function callWithBackoff(callable $fn, int $maxRetry = 5) {
    $delay = 1.0;
    for ($i = 0; $i < $maxRetry; $i++) {
        try {
            return $fn();
        } catch (Throwable $e) {
            $msg = $e->getMessage();
            if (strpos($msg, 'TooManyRequests') !== false || strpos($msg, '429') !== false) {
                usleep((int)($delay * 1_000_000));
                $delay *= 2;
                continue;
            }
            throw $e;
        }
    }
    throw new RuntimeException('Max retry exceeded');
}

FAQ

Q: 1 リクエストで 100 件取りたい
A: 下の旧例のItemCount/ItemPageを一度に100件返る仕様と解釈しないでください。現在の操作別上限とページ指定はCreators API公式仕様を確認し、ページをまたぐ重複や並びの変化も考慮します。

Q: 価格が null になる
A: 価格の欠落だけで売り切れと断定しません。対象Resources、返されたエラー、API世代、オファー有無を確認します。Creators APIでは旧Offersの代わりにOffersV2を確認し、nullや空配列を安全に扱います。

Q: 海外マーケットへのアクセス
A: 対象Marketplace・ストアの参加資格・Partner Tagと対応する認証情報を確認します。旧ホストの切替だけで移行済みとはしません。Creators APIでは資格情報Versionとx-marketplace等の現行送信条件を公式資料で確認します。

子ページ

子ページはありません

同階層のページ
  1. アカウントの作成とキーの生成
  2. PA-APIの使い方 リクエストの構造とパラメータの指定
  3. リクエストにスペースを含める方法
  4. 署名認証の方法(PHPサンプル ItemSearch)
  5. エラー一覧
  6. レスポンスの構造(ItemSearch)

最近更新/作成されたページ