過去バージョン

この記事の要点

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 ではなくアソシエイト発行のキー レート制限は売上連動: 初期 1 req/sec, 8640 req/day。429 は指数バックオフで再試行

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

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"
ItemCount	1 ページ件数（最大 10）	10
ItemPage	ページ番号（最大 10）	1～10
MinPrice / MaxPrice	価格範囲（最小単位、円なら銭まで）	50000 = ¥500
SortBy	Featured, 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 は 欲しい情報をドット記法で明示列挙します。指定しないとレスポンスに含まれません。

カテゴリ	主要 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
BrowseNode	BrowseNodeInfo.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 }
            }
          ]
        }
      }
    ]
  }
}

認証フロー

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

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

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

初期 TPS	1 日当たり	増枠条件
1 req/sec	8,640 req/day	過去 30 日の売上 1 件 = +1 TPS

HTTP 429 / TooManyRequests エラーは指数バックオフ:

<?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 最大 10、ItemPage 最大 10、合計 100 件が上限です。

Q: 価格が null になる
A: Marketplace 出品なし / 売り切れ。Offers.Listings 配列が空のことがあるので、コード側で null チェック必須。

Q: 海外マーケットへのアクセス
A: マーケットごとに キーが別。webservices.amazon.com (US), webservices.amazon.co.uk (UK), etc. それぞれアソシエイトに登録要。