> ## Documentation Index
> Fetch the complete documentation index at: https://docs.querying.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Amazon API

> Amazon の商品を検索し、商品ページを読み取って JSON で受け取ります。検索結果の順位と価格、評価、レビュー数、商品ページの価格、在庫、販売者、画像、仕様、オプションを返します。

Amazon（amazon.com）の商品を検索し、商品ページを非同期タスク API で読み取ります。`COMMERCE_SERP` に `site` `amazon` を指定すると検索結果の商品をストアの順に受け取り、`COMMERCE_PRODUCT` に商品の `url` を渡すとその商品を 1 つ読み取ります。完了した検索または商品ページ 1 件につき **1 クレジット**です。

## 検索

```bash theme={"theme":"css-variables"}
curl -X POST https://api.querying.ai/v1/async/task \
  -H "Authorization: Bearer $QUERYING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "taskType": "COMMERCE_SERP", "payload": { "site": "amazon", "query": "wireless earbuds", "limit": 3 } }'
```

タスクを送信したあと、`GET /v1/async/task/{id}` をポーリングするか Webhook で受け取ります。[非同期タスク](https://docs.querying.ai/ja/concepts/async-tasks.md)を参照してください。

### パラメータ

* `site`: 必須。`amazon` です。
* `query`: 必須。検索語で、1-500 文字です。
* `limit`: 任意の整数、1-40。デフォルトは 20 です。
* `country`: 任意。デフォルトはストアの国の `US` です。ほかの国は `422 REGION_UNSUPPORTED` で拒否されます。

受け付けるペイロードフィールドは上記のみです。`include` は省略してください。`include: {}` でも、クレジットを確保する前に `payload.include` の `422 VALIDATION_ERROR` を返します。

### レスポンス例

```json theme={"theme":"css-variables"}
{
  "site": "amazon",
  "query": "wireless earbuds",
  "country": "US",
  "returnedCount": 3,
  "products": [
    {
      "rank": 1,
      "productId": "B0HJTS6LXB",
      "title": "Wireless Earbuds, 2026 Bluetooth 5.4 Headphones Bass Stereo Ear Buds with Noise Cancelling Mic, LED Display in Ear Earphones 50H Playtime Ear Buds, IP7 Waterproof for Laptop Pad Phones Dark Black",
      "url": "https://www.amazon.com/dp/B0HJTS6LXB",
      "price": 19.99,
      "currency": "USD",
      "rating": 4.6,
      "reviewCount": 656,
      "imageUrl": "https://m.media-amazon.com/images/I/61aSuH86kYL._AC_UY218_.jpg"
    },
    {
      "rank": 2,
      "productId": "B0FQFB8FMG",
      "title": "Apple AirPods Pro 3 Wireless Earbuds with Active Noise Cancellation",
      "url": "https://www.amazon.com/dp/B0FQFB8FMG",
      "price": 179,
      "currency": "USD",
      "rating": 4.4,
      "reviewCount": 18076,
      "imageUrl": "https://m.media-amazon.com/images/I/61solmQSSlL._AC_UY218_.jpg"
    },
    {
      "rank": 3,
      "productId": "B0BQPNMXQV",
      "title": "JBL Vibe Beam - True Wireless Earbuds - Black",
      "url": "https://www.amazon.com/dp/B0BQPNMXQV",
      "price": 29.95,
      "currency": "USD",
      "rating": 4.2,
      "reviewCount": 41710,
      "imageUrl": "https://m.media-amazon.com/images/I/41+1Csr1pSL._AC_UY218_.jpg"
    }
  ]
}
```

### 結果フィールド

* `site`、`query`、`country` はリクエストの値です。`returnedCount` は `products` の件数です。
* 各商品は `rank`、`productId`、`title`、`url` を含みます。`productId` は ASIN です。`rank` はストアのデフォルトの並び順で、ストアが広告と表示した商品は除きます。
* `price`、`rating`、`reviewCount`、`imageUrl` は、検索結果の画面に表示されている場合に含みます。`price` は商品ごとの `currency`（ISO 4217）の数値で、容量ごとに価格が異なる場合は最も低い価格です。 Amazon は 1 回の検索で複数の通貨を表示することがあります。
* `rating` は 5 点満点です。 999+ のように省略表示されたレビュー数は含みません。
* 検索ごとに、ストアの検索結果の 1 ページ目から商品を取得します。

## 商品ページ

```bash theme={"theme":"css-variables"}
curl -X POST https://api.querying.ai/v1/async/task \
  -H "Authorization: Bearer $QUERYING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "taskType": "COMMERCE_PRODUCT", "payload": { "url": "https://www.amazon.com/dp/B0HJTS6LXB" } }'
```

### パラメータ

* `url`: 必須。Amazon の商品ページで、2,048 文字以内です。形式は `amazon.com/dp/{ASIN}` または `amazon.co.jp/dp/{ASIN}` です。検索結果の商品 `url` はそのまま渡せます。トラッキングコードなど結果に影響しないパラメータは読み取り前に取り除きます。 `/gp/product/{ASIN}` など、同じページの別のアドレスも使えます。
* `country`: 任意。デフォルトはページの国で、amazon.com は `US`、amazon.co.jp は `JP` です。ほかの国は `422 REGION_UNSUPPORTED` で拒否されます。

受け付けるペイロードフィールドは上記のみです。`include` は省略してください。`include: {}` でも、クレジットを確保する前に `payload.include` の `422 VALIDATION_ERROR` を返します。

### レスポンス例

```json theme={"theme":"css-variables"}
{
  "site": "amazon",
  "country": "US",
  "url": "https://www.amazon.com/dp/B0HJTS6LXB",
  "productId": "B0HJTS6LXB",
  "title": "Wireless Earbuds, 2026 Bluetooth 5.4 Headphones Bass Stereo Ear Buds with Noise Cancelling Mic, LED Display in Ear Earphones 50H Playtime Ear Buds, IP7 Waterproof for Laptop Pad Phones Dark Black",
  "brand": "XIAOWTEK",
  "price": 19.99,
  "listPrice": 199.99,
  "currency": "USD",
  "inStock": true,
  "seller": "duanyuekj",
  "rating": 4.6,
  "reviewCount": 656,
  "images": [
    "https://m.media-amazon.com/images/I/61aSuH86kYL._AC_SL1500_.jpg",
    "https://m.media-amazon.com/images/I/614SJ1xXHDL._AC_SL1500_.jpg"
  ],
  "description": "LED Power Display and 50H Playback: Dual digital LED power display outside of the case is to show the power level for charging case and earbuds. When charging for the case, the LED light will start…",
  "descriptionImages": [
    "https://m.media-amazon.com/images/S/aplus-media-library-service-media/bd0bc2d5-cf30-4f89-bb94-79fa935a35c4.__CR0,0,1464,600_PT0_SX1464_V1___.jpg",
    "https://m.media-amazon.com/images/S/aplus-media-library-service-media/a0abce46-fbc8-4054-9705-77153bb852a8.__CR0,0,1464,600_PT0_SX1464_V1___.jpg"
  ],
  "specs": [
    { "name": "Brand", "value": "XIAOWTEK" },
    { "name": "Color", "value": "Dark Black" },
    { "name": "Ear Placement", "value": "In Ear" }
  ],
  "options": [{ "name": "Color", "values": ["Blue", "Carbon Black", "Dark Black", "Pink"] }],
  "categories": [
    "Electronics",
    "Headphones, Earbuds & Accessories",
    "Headphones & Earbuds",
    "Earbud Headphones"
  ]
}
```

### 結果フィールド

* `site`、`country`、`url`、`productId` でページを識別します。`url` は読み取ったページで、`productId` は検索結果の ID と同じです。
* `title` は常に含みます。`brand`、`price`、`listPrice`、`currency`、`inStock`、`seller`、`rating`、`reviewCount`、`images`、`description`、`descriptionImages`、`specs`、`options`、`categories`、`gtin` は、ページに表示されている場合に含みます。
* `price` は、クーポンと送料を適用する前にページが最初に表示する購入価格で、`currency`（ISO 4217）の値です。 `listPrice` はページが取り消し線で表示する通常価格で、`price` より高い場合だけ含みます。 `inStock` は在庫の有無です。 `seller` は販売者です。 amazon.co.jp のページは `country` が `JP` で、価格は `JPY` です。 Amazon が商品のおすすめ出品を選んでいない場合はページに価格がないため、`price`、`currency`、`seller`、`inStock` は出品一覧で価格のある最初の販売者のものです。
* `rating` は小数第 2 位までの 5 点満点の評価です。 `reviewCount` はレビュー数です。
* `images` は商品ギャラリーの写真を、ページの順に最大 30 枚含みます。
* `description` は段落ごとに 1 行のプレーンテキストで、最大 10,000 文字です。画像の中にしかない文字は含みません。
* `descriptionImages` は商品説明の画像を、ページの順に最大 300 枚含みます。販売者が説明に入れたバナーやお知らせも含まれ、画像の中の文字は読み取りません。
* `specs` は商品詳細の `{ name, value }` の組を最大 100 個含みます。 `options` はサイズや色などの選択肢を最大 20 個、選択肢ごとに `values` を最大 100 個含みます。ほかのフィールドは、ページが最初に選択している選択肢のものです。 `categories` は最も広いカテゴリから最も狭いカテゴリまでの、最大 10 階層です。 `gtin` はページに記載された UPC、EAN、JAN です。

## エラーと課金

* 商品が 1 つもない検索は、失敗したタスクとして終了します。
* ストアが 404 または 410 で応答する商品ページ（削除された商品など）は `PAGE_UNAVAILABLE` で終了し、メッセージにストアの応答が入ります。ストアが 403、412、429、435 で読み取りを拒否した場合、タスクは待機して最大 6 分間再試行します。ほかの読み取り失敗と、それより長く続く拒否は `ENGINE_NO_RESULT` で終了します。
* 課金は完了したタスクだけで、検索または商品ページ 1 件につき 1 クレジットです。

## 関連

* [Walmart](https://docs.querying.ai/ja/engines/walmart.md)
* [Target](https://docs.querying.ai/ja/engines/target.md)
* [eBay](https://docs.querying.ai/ja/engines/ebay.md)
* [Commerce のストア一覧](https://docs.querying.ai/ja/engines/overview.md#commerce)
* [クレジットと上限](https://docs.querying.ai/ja/concepts/credits-and-limits.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.