Image Search
Find Amazon products from a photo. Each match is the same item a keyword search returns.
POST /v1/amazon/image-searchPOST only, with a JSON body.
Parameters
| Parameter | Type | Required | Notes |
|---|---|---|---|
image | object | yes | The picture to search by: {contentType, data} with data base64-encoded. POST only — a base64 image is tens of kilobytes and a URL caps out around 8 KB. |
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. | |
page | integer | 1-based page number over the visual matches, about 48 per page; each page is charged separately. No pageSize and no cursor. | |
priceMax | number ≥ 0 | Highest price to return, in decimal major units. | |
priceMin | number ≥ 0 | Lowest price to return, in decimal major units. | |
query | string | Optional words that narrow the visual matches, e.g. the product type. Supplying it is usually much more precise. | |
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 |
Request
curl -X POST "https://gateway.apinoa.com/v1/amazon/image-search" \
-H "x-api-key: $APINOA_API_KEY" \
-H "content-type: application/json" \
-d "{\"image\": {\"contentType\": \"image/jpeg\", \"data\": \"$(base64 < photo.jpg | tr -d '\n')\"}}"Response
Returns SearchResult in data. A real response, shortened: arrays keep their first entries and long text is cut.
{
"success": true,
"data": {
"marketplace": "amazon",
"page": {
"index": 1,
"size": 48,
"total": 90
},
"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",
"category": [
{
"name": "Women's Hiking Socks"
}
],
"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,
"membership": "Prime",
"minDays": 1,
"maxDays": 1
}
],
"badges": [
"Best Seller in Women's Hiking Socks",
"Limited time deal"
],
"promotions": [],
"matchScore": 0.70708364
}
]
}
}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. 2 units when the picture matches; 1 unit when it matches nothing. List price; the rate steps down above 1,000 calls a day.
Notes
- POST only. A base64 image is tens of kilobytes; a query string caps out around 8 KB.
querynarrows the picture. The image decides what the results are about, and words narrow them. A photo of a figure returned 48 matches on its own and 22 withquery: "plush". Price, rating, category filters andsortapply as they do on search.- JPEG, PNG or GIF. WebP and HEIC are refused with a 400; convert them first.
- No match is not an error. A picture Amazon recognises nothing in returns an empty
itemsand costs 1 unit; a match costs 2. - Paging. About 48 matches per page; ask for the next
pageuntilitemscomes back empty. Each page is billed.