Search
Search Amazon by keyword, with price, rating, brand and category filters, on any of sixteen Amazon marketplaces.
GET | POST /v1/amazon/searchSend parameters as a query string with GET, or as a JSON body with POST. Both are equivalent.
Request
curl "https://gateway.apinoa.com/v1/amazon/search?query=wool+socks&priceMax=30" \
-H "x-api-key: $APINOA_API_KEY"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.
Response
Returns SearchResult in data. A real response, shortened: arrays keep their first entries and long text is cut.
{
"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. 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; the rate steps down above 1,000 calls a day.
Notes
regionpicks the marketplace.region=JPsearches amazon.co.jp and prices in yen. The sixteen countries are listed on the 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 nopageSizeand nocursor. ratingMinis4or a 400. Amazon offers exactly one rating threshold, "4 Stars & Up". Any other value is refused rather than answered with a different search.brandsandfacetscost 2 units. Every other filter costs nothing extra. See Filters.- Not supported:
condition,freeShipping,inStock.