---
title: "Search"
description: "Search Amazon by keyword, with price, rating, brand and category filters, on any of sixteen Amazon marketplaces."
---

> Every apinoa docs page as markdown: https://apinoa.com/llms.txt (all in one file: https://apinoa.com/llms-full.txt; this API family in one file: https://apinoa.com/docs/marketplace/llms.txt)

```http
GET | POST /v1/amazon/search
```

Send parameters as a query string with `GET`, or as a JSON body with `POST`. Both are equivalent.

## Request

```bash tab="cURL"
curl "https://gateway.apinoa.com/v1/amazon/search?query=wool+socks&priceMax=30" \
  -H "x-api-key: $APINOA_API_KEY"
```

```js tab="JavaScript"
const params = new URLSearchParams({ query: "wool socks", priceMax: "30" });
const res = await fetch(`https://gateway.apinoa.com/v1/amazon/search?${params}`, {
  headers: { "x-api-key": process.env.APINOA_API_KEY },
});
const { success, data, error } = await res.json();
```

```python tab="Python"
import os

import requests

res = requests.get(
    "https://gateway.apinoa.com/v1/amazon/search",
    params={"query": "wool socks", "priceMax": "30"},
    headers={"x-api-key": os.environ["APINOA_API_KEY"]},
)
body = res.json()
```

## Parameters

| Parameter | Type | Required | Notes |
|---|---|---|---|
| `query` | string | yes | Keywords to search for. Required here; to search by picture use `image-search`. |
| `brands` | string list |  | Brand names as Amazon spells them, e.g. brands=Nike,Adidas. A call that uses `brands` costs 2 units instead of 1. Not available on amazon.fr (`region=FR`). |
| `categoryId` | string |  | Narrow to one category, by the marketplace's own id. Opaque and per-marketplace; take it from Product.category[].id or from a result's `facets`. |
| `facets` | string \| object list |  | Narrowings taken from a result's `facets`, e.g. facets=Color:Black. A call that uses `facets` costs 2 units instead of 1. Not available on amazon.fr (`region=FR`). |
| `include` | string list |  | Expansions that cost more than the default answer, e.g. include=facets. |
| `page` | integer |  | 1-based page number; each page is charged separately. There is no `pageSize` (Amazon fixes the count per page by keyword, 13-47 in practice) and no `cursor` — paging is by number. |
| `priceMax` | number ≥ 0 |  | Highest price to return, in decimal major units. |
| `priceMin` | number ≥ 0 |  | Lowest price to return, in decimal major units. |
| `ratingMin` | number |  | `4` only. Amazon's rating filter offers exactly one threshold, "4 Stars & Up"; any other value is a 400 rather than a silently different search. Not available on amazon.fr (`region=FR`). |
| `region` | enum |  | Which Amazon marketplace to query, by buyer country: US, CA, MX, BR, FR, IT, ES, NL, SE, TR, AE, SA, IN, JP, SG, AU. Defaults to US. Prices come back in that marketplace's own currency (JP in JPY, FR in EUR). `US` `CA` `MX` `BR` `FR` `IT` `ES` `NL` `SE` `TR` `AE` `SA` `IN` `JP` `SG` `AU` |
| `sort` | enum |  | Result ordering: `best_match`, `price_asc`, `price_desc`, `newly_listed` or `avg_review`. Defaults to `best_match`, Amazon's own relevance ordering. `best_match` `price_asc` `price_desc` `newly_listed` `avg_review` |

The same parameters, and every response type, are in the OpenAPI document: https://apinoa.com/openapi.json

## Response

Returns [`SearchResult`](/docs/api-reference/marketplaces/response-schema#searchresult) in `data`. A real response, shortened: arrays keep their first entries and long text is cut.

```json
{
  "success": true,
  "data": {
    "marketplace": "amazon",
    "query": "wool socks",
    "page": {
      "index": 1,
      "size": 48,
      "total": 13179
    },
    "items": [
      {
        "marketplace": "amazon",
        "id": "B07F3FFTMK",
        "title": "Alvada Mens Merino Wool Crew Socks Thermal and Warm Socks for Winter Work Hiking Running 3 Pairs",
        "attributes": [],
        "price": {
          "currency": "USD",
          "amount": 13.49
        },
        "url": "https://www.amazon.com/dp/B07F3FFTMK",
        "imageUrl": "https://m.media-amazon.com/images/I/91aOC3G1W6L.jpg",
        "variantCount": 24,
        "listPrice": {
          "currency": "USD",
          "amount": 14.99
        },
        "unitPrice": {
          "price": {
            "currency": "USD",
            "amount": 4.5
          },
          "unit": "count"
        },
        "rating": {
          "average": 4.5,
          "count": 37581
        },
        "salesLabel": "10K+ bought in past month",
        "salesCount": 10000,
        "delivery": {
          "estimate": "Non-members get FREE delivery Thu, Oct 29 on $35 of items shipped by Amazon",
          "free": true,
          "minimumOrder": {
            "currency": "USD",
            "amount": 35
          },
          "minDays": 5,
          "maxDays": 5
        },
        "shippingOptions": [
          {
            "estimate": "Non-members get FREE delivery Thu, Oct 29 on $35 of items shipped by Amazon",
            "free": true,
            "minimumOrder": {
              "currency": "USD",
              "amount": 35
            },
            "minDays": 5,
            "maxDays": 5
          },
          {
            "estimate": "Join Prime to get FREE delivery Tomorrow, Oct 25",
            "free": true,
            "minDays": 1,
            "maxDays": 1,
            "ext": {
              "membership": "Prime"
            }
          }
        ],
        "badges": [
          "Overall Pick",
          "Amazon's Choice"
        ],
        "promotions": []
      }
    ]
  }
}
```

## Errors

| Status | Code | Meaning |
|---|---|---|
| 400 | `INVALID_PARAMS` | A parameter is missing, unknown or out of range. The message names it. |
| 401 | `UNAUTHORIZED` | The `x-api-key` header is missing, or the key is revoked or unknown. |
| 402 | `INSUFFICIENT_BALANCE` | The balance does not cover this call. Top up in the dashboard. |
| 429 | `MARKETPLACE_SATURATED` | Too many concurrent calls. Retry after the `Retry-After` seconds. |
| 502 | `UPSTREAM_ERROR` | The platform answered with something unusable. Retry with backoff. |

Every code is listed in [Errors](/docs/errors). Failed calls are not billed.

## Pricing

**Price** $0.001 per call, plus $0.001 for each extra call it makes — at most 1 more, so $0.002 in total. Only `brands` and rail facets add one: either makes the call 2 units. Every other filter costs nothing extra. [List price](https://apinoa.com/en/pricing); the rate steps down above 1,000 calls a day.

## Notes

- **`region` picks the marketplace.** `region=JP` searches amazon.co.jp and prices in yen. The sixteen countries are listed on the [Amazon](/docs/api-reference/amazon) page. Omitted, it is amazon.com.
- **Paging is by `page`.** Amazon fixes the page size by keyword (13 to 47 in practice), so there is no `pageSize` and no `cursor`.
- **`ratingMin` is `4` or a 400.** Amazon offers exactly one rating threshold, "4 Stars & Up". Any other value is refused rather than answered with a different search.
- **`brands` and `facets` cost 2 units.** Every other filter costs nothing extra. See [Filters](/docs/api-reference/marketplaces/filters).
- **Not supported:** `condition`, `freeShipping`, `inStock`.