> ## 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

> Busca productos en la tienda Amazon y lee sus páginas de producto como JSON: posiciones con precios, valoraciones y número de reseñas en la búsqueda, y precio, disponibilidad, vendedor, imágenes, especificaciones y opciones en cada página de producto.

Busca productos en la tienda Amazon (amazon.com) y lee sus páginas de producto mediante la API de tareas asíncronas. Envía `COMMERCE_SERP` con `site` `amazon` para recibir los productos que muestra una búsqueda, en el orden de la tienda, o `COMMERCE_PRODUCT` con la `url` de un producto para leer ese producto. Cada búsqueda o página de producto completada cuesta **1 crédito**.

## Búsqueda

```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 } }'
```

Envía la tarea y luego consulta `GET /v1/async/task/{id}` o recibe su webhook. Consulta [Tareas asíncronas](https://docs.querying.ai/es/concepts/async-tasks.md).

### Parámetros

* `site`: Obligatorio. `amazon`.
* `query`: Obligatorio. Consulta de búsqueda, de 1 a 500 caracteres.
* `limit`: Entero opcional de 1 a 40, con 20 por defecto.
* `country`: Opcional. Por defecto, `US`, el país de la tienda. Cualquier otro país se rechaza con `422 REGION_UNSUPPORTED`.

Solo se aceptan los campos de payload enumerados arriba. Omite `include`: incluso `include: {}` devuelve `422 VALIDATION_ERROR` en `payload.include` antes de reservar créditos.

### Ejemplo de respuesta

```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"
    }
  ]
}
```

### Campos del resultado

* `site`, `query` y `country` repiten la solicitud. `returnedCount` es el número de elementos de `products`.
* Cada producto incluye `rank`, `productId`, `title` y `url`. `productId` es el ASIN. `rank` sigue el orden predeterminado de la tienda, y se omiten los anuncios que la tienda marca como patrocinados.
* `price`, `rating`, `reviewCount` e `imageUrl` aparecen cuando la página de resultados los muestra. `price` es un número en la `currency` del producto (ISO 4217); cuando los tamaños tienen precios distintos, es el más bajo. Una misma búsqueda en Amazon puede mostrar más de una moneda.
* `rating` usa una escala de cinco puntos. Los números de reseñas abreviados, como 999+, se omiten.
* Cada búsqueda devuelve productos de la primera página de resultados de la tienda.

## Página de producto

```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" } }'
```

### Parámetros

* `url`: Obligatorio. Una página de producto de la tienda Amazon, de hasta 2.048 caracteres: `amazon.com/dp/{ASIN}` o `amazon.co.jp/dp/{ASIN}`. Las `url` de producto que devuelve una búsqueda sirven tal cual. Los parámetros que no afectan al resultado, como los códigos de seguimiento, se quitan antes de leer la página. También sirven otras direcciones de la misma página, como `/gp/product/{ASIN}`.
* `country`: Opcional. Por defecto, el país de la página: `US` en amazon.com y `JP` en amazon.co.jp. Cualquier otro país se rechaza con `422 REGION_UNSUPPORTED`.

Solo se aceptan los campos de payload enumerados arriba. Omite `include`: incluso `include: {}` devuelve `422 VALIDATION_ERROR` en `payload.include` antes de reservar créditos.

### Ejemplo de respuesta

```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"
  ]
}
```

### Campos del resultado

* `site`, `country`, `url` y `productId` identifican la página. `url` es la página que se leyó, y `productId` coincide con el que devuelve una búsqueda.
* `title` siempre está presente. `brand`, `price`, `listPrice`, `currency`, `inStock`, `seller`, `rating`, `reviewCount`, `images`, `description`, `descriptionImages`, `specs`, `options`, `categories` y `gtin` aparecen cuando la página los muestra.
* `price` es lo que paga un comprador tal como la página lo muestra al abrirse, antes de cupones y envío, en `currency` (ISO 4217). `listPrice` es el precio habitual que la página tacha, presente cuando es mayor que `price`. `inStock` es la disponibilidad del producto. `seller` es el comerciante que lo vende. Las páginas de amazon.co.jp devuelven `country` `JP` y precios en `JPY`. Cuando Amazon no elige una oferta destacada para un producto, la página no muestra precio, así que `price`, `currency`, `seller` e `inStock` salen del primer vendedor con precio de la lista de ofertas del producto.
* `rating` usa una escala de cinco puntos con dos decimales. `reviewCount` es el número de reseñas.
* `images` lista hasta 30 fotos de la galería del producto, en el orden de la página.
* `description` es texto plano con una línea por párrafo, de hasta 10.000 caracteres; el texto que solo aparece dentro de imágenes no se incluye.
* `descriptionImages` lista hasta 300 imágenes de la descripción del producto, en el orden de la página. Se incluyen los banners y avisos que los vendedores ponen en su descripción, y el texto dentro de las imágenes no se lee.
* `specs` lista hasta 100 pares `{ name, value }` de los detalles del producto. `options` lista hasta 20 opciones, como talla o color, cada una con hasta 100 `values`; los demás campos describen la opción con la que se abre la página. `categories` va de la categoría más amplia a la más concreta, con hasta 10 niveles. `gtin` es el UPC, EAN o JAN que indica la página.

## Errores y facturación

* Una búsqueda que no devuelve productos termina como tarea fallida.
* Una página de producto que la tienda responde con 404 o 410, como un producto retirado, termina la tarea con `PAGE_UNAVAILABLE`, y el mensaje incluye la respuesta de la tienda. Si la tienda rechaza la lectura con 403, 412, 429 o 435, la tarea espera y vuelve a consultar durante un máximo de 6 minutos. Las demás lecturas fallidas, y un rechazo que dura más, terminan con `ENGINE_NO_RESULT`.
* Solo se cobran las tareas completadas: 1 crédito por búsqueda o página de producto.

## Relacionado

* [Walmart](https://docs.querying.ai/es/engines/walmart.md)
* [Target](https://docs.querying.ai/es/engines/target.md)
* [eBay](https://docs.querying.ai/es/engines/ebay.md)
* [Todas las tiendas de Commerce](https://docs.querying.ai/es/engines/overview.md#commerce)
* [Créditos y límites](https://docs.querying.ai/es/concepts/credits-and-limits.md)


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