---
title: "Image Search"
description: "Find Amazon products from a photo. Each match is the same item a keyword search returns."
---

```http
POST /v1/amazon/image-search
```

`POST` 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

```bash tab="cURL"
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')\"}}"
```

```js tab="JavaScript"
import { readFile } from "node:fs/promises";

const data = (await readFile("photo.jpg")).toString("base64");
const res = await fetch("https://gateway.apinoa.com/v1/amazon/image-search", {
  method: "POST",
  headers: { "x-api-key": process.env.APINOA_API_KEY, "content-type": "application/json" },
  body: JSON.stringify({ image: { contentType: "image/jpeg", data } }),
});
const { success, data: result, error } = await res.json();
```

```python tab="Python"
import base64
import os

import requests

with open("photo.jpg", "rb") as f:
    data = base64.b64encode(f.read()).decode()

res = requests.post(
    "https://gateway.apinoa.com/v1/amazon/image-search",
    json={"image": {"contentType": "image/jpeg", "data": data}},
    headers={"x-api-key": os.environ["APINOA_API_KEY"]},
)
body = res.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",
    "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](/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. 2 units when the picture matches; 1 unit when it matches nothing. [List price](https://apinoa.com/en/pricing); 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.
- **`query` narrows 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 with `query: "plush"`. Price, rating, category filters and `sort` apply 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 `items` and costs 1 unit; a match costs 2.
- **Paging.** About 48 matches per page; ask for the next `page` until `items` comes back empty. Each page is billed.