◀ 6.

旧PA-APIのSearchItems応答構造とJSON解析・移行の注意点

ItemSearchの旧XMLと、旧PA-API 5のSearchItems JSONを読むための資料です。現在のCreators APIとは応答形が異なります。価格欠落を売り切れと即断せず、HTTP・本文内エラー・商品配列を分けて確認します。

旧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の関連資料から各子ページも選択できます。

保存済みJSONを安全に点検する例

次はPHP 8系で保存済みの旧PA-API 5 JSONを解析するローカル関数です。SDKや認証情報は使いません。通信の成否は呼出側で別途取得し、HTTP失敗、空/不正JSON、想定外の形を正常な0件へ丸めません。商品とエラーの両方がある場合は両方を返します。

<?php

// Decode saved PA-API 5 JSON for maintenance. No SDK, credentials or HTTP calls.
function readLegacySearch(int $status, string $body): array
{
    if ($status < 200 || $status >= 300) {
        throw new RuntimeException('HTTP response was not successful');
    }
    $data = json_decode($body, false, 512, JSON_THROW_ON_ERROR);
    if (!$data instanceof stdClass) {
        throw new UnexpectedValueException('Expected a JSON object');
    }
    $errors = $data->Errors ?? [];
    if (property_exists($data, 'Errors') && !is_array($data->Errors)) {
        throw new UnexpectedValueException('Errors must be an array');
    }
    foreach ($errors as $error) {
        if (!$error instanceof stdClass || !isset($error->Code, $error->Message)
            || !is_string($error->Code) || !is_string($error->Message)) {
            throw new UnexpectedValueException('Invalid error object');
        }
    }
    if (!property_exists($data, 'SearchResult')) {
        if ($errors !== []) {
            return ['items' => [], 'errors' => $errors, 'total' => null];
        }
        throw new UnexpectedValueException('Missing SearchResult and Errors');
    }
    $result = $data->SearchResult;
    if (!$result instanceof stdClass || !isset($result->Items) || !is_array($result->Items)) {
        throw new UnexpectedValueException('Expected SearchResult.Items array');
    }
    foreach ($result->Items as $item) {
        if (!$item instanceof stdClass || !isset($item->ASIN) || !is_string($item->ASIN) || $item->ASIN === '') {
            throw new UnexpectedValueException('Invalid item identifier');
        }
    }
    $total = $result->TotalResultCount ?? null;
    if (property_exists($result, 'TotalResultCount') && (!is_int($total) || $total < 0)) {
        throw new UnexpectedValueException('Invalid total count');
    }

    return ['items' => $result->Items, 'errors' => $errors, 'total' => $total];
}

itemsはstdClassの配列、errorsもstdClassの配列、totalは件数または未提供時nullです。失敗を捕捉する場合も、本文・資格情報・生の例外を公開せず、画面表示用の安全な文面と運用向け診断を分けてください。この関数はすべての商品フィールドを検証するスキーマではなく、画像URLの安全性・通貨計算・HTMLエスケープも別の責務です。

現行APIへ移す場合

現行SearchItemsのsearchResult/items/errors等と、OffersV2を確認します。旧Offersの単なる小文字化では移行できません。公式エラー資料でHTTP失敗と部分エラーを区別し、この旧応答用の解析関数を現在の応答へ適用しないでください。

この記事の要点
  • PA-API 5.0 では操作名が ItemSearch から SearchItems に変更(JSON)
  • トップ階層: SearchResult.Items[] に商品配列、SearchResult.TotalResultCount に総件数
  • 各 Item の主要フィールド: ASIN / DetailPageURL / Images.Primary.Large.URL / ItemInfo.Title.DisplayValue / Offers.Listings[0].Price.DisplayAmount / BrowseNodeInfo
  • エラー時は Errors[] 配列が返る (Code / Message)。HTTP 200 でも Errors 入りの場合あり
  • 取得項目は Resources パラメータで明示指定。指定しないと最小限のフィールドのみ
  • 4.0 (XML) との互換性なし。JSON ベース・キャメルケースに統一

SearchItems レスポンス全体構造

以下は旧PA-API 5の説明用JSONです。商品名・価格・在庫・寸法は現在の実データではなく、実API応答を保証しません。Creators APIは項目名やOffersV2等が異なり、下のパスをそのまま流用しません。

{
  "SearchResult": {
    "Items": [
      {
        "ASIN": "B08N5WRWNW",
        "DetailPageURL": "https://www.amazon.co.jp/dp/B08N5WRWNW?tag=yourid-22&linkCode=ogi&th=1&psc=1",
        "Images": {
          "Primary": {
            "Large":  { "URL": "https://m.media-amazon.com/images/I/...L.jpg",  "Width": 500, "Height": 500 },
            "Medium": { "URL": "https://m.media-amazon.com/images/I/...M.jpg",  "Width": 160, "Height": 160 },
            "Small":  { "URL": "https://m.media-amazon.com/images/I/...S.jpg",  "Width": 75,  "Height": 75 }
          },
          "Variants": [ { "Large": { "URL": "..." } } ]
        },
        "ItemInfo": {
          "Title": { "DisplayValue": "Echo Dot (第5世代)", "Label": "Title", "Locale": "ja_JP" },
          "ByLineInfo": {
            "Brand":        { "DisplayValue": "Amazon", "Label": "Brand" },
            "Manufacturer": { "DisplayValue": "Amazon", "Label": "Manufacturer" }
          },
          "Features": {
            "DisplayValues": ["特徴1", "特徴2", "特徴3"]
          },
          "Classifications": {
            "Binding":      { "DisplayValue": "エレクトロニクス" },
            "ProductGroup": { "DisplayValue": "Electronics" }
          }
        },
        "Offers": {
          "Listings": [
            {
              "Id": "abc123...",
              "Price": {
                "DisplayAmount": "¥7,480",
                "Amount":        7480,
                "Currency":      "JPY",
                "Savings":       { "DisplayAmount": "¥500", "Amount": 500, "Percentage": 6 }
              },
              "Availability": { "Message": "在庫あり", "Type": "Now" },
              "Condition":   { "Value": "New", "DisplayValue": "新品" },
              "DeliveryInfo": { "IsPrimeEligible": true, "IsFreeShippingEligible": true }
            }
          ],
          "Summaries": [
            { "Condition": { "Value": "New" }, "HighestPrice": {"Amount":7480}, "LowestPrice": {"Amount":7480}, "OfferCount": 12 }
          ]
        },
        "BrowseNodeInfo": {
          "BrowseNodes": [
            { "Id": "12345", "DisplayName": "スマートスピーカー", "ContextFreeName": "スマートスピーカー", "IsRoot": false,
              "Ancestor": { "Id": "67890", "DisplayName": "Amazon Echo" } }
          ]
        }
      }
    ],
    "TotalResultCount": 1248,
    "SearchURL": "https://www.amazon.co.jp/s?k=echo+dot&tag=yourid-22"
  }
}

主要フィールドの早見表

フィールド意味
SearchResult.Items[]ヒット商品配列
SearchResult.TotalResultCountマッチ総件数
Item.ASINAmazon Standard Identification Number (10 文字)
Item.DetailPageURLアソシエイトタグ付き商品ページ URL
Item.Images.Primary.Large.URLメイン画像 (大)
Item.ItemInfo.Title.DisplayValue商品タイトル (表示用)
Item.Offers.Listings[0].Price.DisplayAmount整形済価格(¥7,480 など)
Item.Offers.Listings[0].Price.Amount数値価格
Item.Offers.Summaries[]新品/中古別の最高・最低価格
Item.BrowseNodeInfo.BrowseNodes[]カテゴリ階層

Resources パラメータ — 取得項目を明示

旧例の取得項目はResourcesと応答の双方で確認します。デフォルトを現行APIへ一般化せず、下は旧形式の要求例として比較してください:

{
  "Keywords": "echo dot",
  "SearchIndex": "Electronics",
  "ItemCount": 10,
  "PartnerTag": "yourid-22",
  "PartnerType": "Associates",
  "Marketplace": "www.amazon.co.jp",
  "Resources": [
    "Images.Primary.Large",
    "Images.Primary.Medium",
    "ItemInfo.Title",
    "ItemInfo.Features",
    "ItemInfo.ByLineInfo",
    "ItemInfo.Classifications",
    "Offers.Listings.Price",
    "Offers.Listings.Availability.Message",
    "Offers.Listings.DeliveryInfo.IsPrimeEligible",
    "Offers.Summaries.HighestPrice",
    "Offers.Summaries.LowestPrice",
    "BrowseNodeInfo.BrowseNodes",
    "ParentASIN"
  ]
}

エラーレスポンス構造

下のErrors表とSDK例は旧PA-APIの記録です。現在のCreators APIのエラー名・原因の完全な一覧ではありません。返却されたHTTP状態と正式なコードを確認し、旧キーの変更や売上条件だけで対処を決めないでください。

{
  "__type": "com.amazon.paapi5#ErrorData",
  "Errors": [
    {
      "Code": "InvalidParameterValue",
      "Message": "The PartnerTag is not present or is not mapped to a valid associate store with the given access key."
    }
  ]
}

注意: HTTP 200 で返ってきても SearchResult が空で Errors だけ存在するケースがある(部分エラー / 一部商品取得失敗)。両方チェックすること。

エラーコード意味対処
InvalidParameterValueパラメータ不正PartnerTag / Resources / SearchIndex を再確認
InvalidAssociateアソシエイト無効対象APIの利用資格・ストアとの対応を確認。売上件数だけで原因を断定しない
TooManyRequestsレート超過リクエスト頻度を下げる、Retry-After 待機
UnrecognizedClientキー / 署名不正Access Key / Secret 確認、リージョン確認
NoResults0 件ヒットキーワード / SearchIndex を見直し

4.0 (XML) → 5.0 (JSON) の主な違い

項目4.0 (旧)5.0 (旧PA-API)
形式XMLJSON
メソッド名ItemSearch / ItemLookupSearchItems / GetItems
取得項目指定ResponseGroupResources (より細かい)
署名SHA256 シンプル署名AWS SigV4
タイトル取得パスItem.ItemAttributes.TitleItem.ItemInfo.Title.DisplayValue
価格取得パスItem.OfferSummary.LowestNewPriceItem.Offers.Listings[0].Price

PHP でレスポンスをパースする例

次は旧SDK依存の未実行断片として保持します。 req等の前提設定・通信例外・HTTPエラーを網羅せず、生のエラー文をログへ出す例をそのまま使わないでください。HTML画面へ値を出す場合は出力文脈に合うエスケープが別途必要です。

<?php
$resp = $apiInstance->searchItems($req);

// エラーチェック
if ($resp->getErrors() !== null) {
    foreach ($resp->getErrors() as $err) {
        error_log($err->getCode() . ': ' . $err->getMessage());
    }
}

$result = $resp->getSearchResult();
if ($result === null) return;

echo "総ヒット数: " . $result->getTotalResultCount() . "\n";

foreach ($result->getItems() ?? [] as $item) {
    $asin    = $item->getASIN();
    $url     = $item->getDetailPageURL();
    $title   = $item->getItemInfo()?->getTitle()?->getDisplayValue() ?? '(no title)';
    $image   = $item->getImages()?->getPrimary()?->getLarge()?->getURL();
    $listing = $item->getOffers()?->getListings()[0] ?? null;
    $price   = $listing?->getPrice()?->getDisplayAmount() ?? '不明';
    $isPrime = $listing?->getDeliveryInfo()?->getIsPrimeEligible() ?? false;

    echo "$asin | $title | $price" . ($isPrime ? ' [Prime]' : '') . "\n";
    echo "  $url\n  $image\n\n";
}

FAQ

Q: 価格情報が含まれない商品がある
A: 価格欠落だけで在庫切れとは判断できません。旧例のResources・返却エラー・オファー有無を確認します。欠落、null、空配列を区別し、Creators APIの価格情報はOffersV2の現行仕様で確認してください。

Q: Resources で指定しなかった項目は返ってこない
A: 必要なResourcesを対象APIの正式な一覧から指定します。要求済みでも商品ごとに項目が欠ける場合があり、指定した全項目の存在を保証するものではありません。現行SearchItemsの既定値を旧例から推測しないでください。

Q: アフィリエイト URL になっていない
A: 対象API・ストア・Partner Tagと返されたURLを確認します。URLにtagという文字があるだけで有効な紐付けと断定せず、公式のリンク要件と実際の返却値を照合してください。

子ページ

子ページはありません

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

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