# Product Search

Source: https://env.7xmtools.com/api-docs/product-search.html

Search for Amazon products using keywords and retrieve up to 20 results per search term — either as full product objects or as a plain list of ASINs.

GET · 10 tokens per search (up to 20 results)

Search for Amazon products using keywords, returning up to **20** results per search term. The results are in the same order as a search on Amazon, excluding sponsored content. By default, the product search response contains the [product objects](https://env.7xmtools.com/api-docs/product-object.html) of the found products.

## Endpoint

```
GET https://api.keepa.com/search?key=<yourAccessKey>&domain=<domainId>&type=product&term=<searchTerm>
```

## Parameters

### Required parameters

| Parameter | Required | Description |
| --- | --- | --- |
| `key` | required | Your private API key. |
| `domain` | required | Integer value for the Amazon locale you want to access. See the [valid domain IDs](https://env.7xmtools.com/api-docs/product-search.html#domain-ids) below. |
| `type` | required | Must be set to `product` for a product search. |
| `term` | required | The term you want to search for. Should be [URL encoded](https://en.wikipedia.org/wiki/Percent-encoding). |

### Valid domain IDs

| Domain ID | Locale |
| --- | --- |
| **1** | com |
| **2** | co.uk |
| **3** | de |
| **4** | fr |
| **5** | co.jp |
| **6** | ca |
| **8** | it |
| **9** | es |
| **10** | in |
| **11** | com.mx |
| **12** | com.br |

### Optional parameters

| Parameter | Required | Description |
| --- | --- | --- |
| `asins-only` | optional | If provided and set to `1`, only the ASINs of the found products will be provided instead of the full product objects.<br>**Example:** `&asins-only=1` |
| `stats` | optional | No extra token cost. If specified, the product object will include a `stats` field (see [Statistics Object](https://env.7xmtools.com/api-docs/statistics-object.html)) with quick access to current prices, min/max prices, and weighted mean values. You can provide the `stats` parameter in two forms:<br>• **Last x days:** a positive integer value representing the number of last days to calculate stats for.<br>**Example:** `&stats=180` (stats for the last 180 days)<br>• **Interval:** a date range for the stats calculation using two timestamps (Unix epoch time in milliseconds) or two date strings (ISO8601 format, with or without time in UTC).<br>**Examples:** `&stats=2015-10-20,2015-12-24` (from October 20 to December 24, 2015) · `&stats=1445299200000,1450915200000` (Unix epoch time in milliseconds) |
| `update` | optional | **Additional token cost:** 0 or 1 per found product.<br>Positive integer value. If the product's last update is older than `<update>` hours, force a refresh. The default value the API uses is **1** hour.<br>**Usage:**<br>• **Speed up requests:** if up-to-date data is not required, use a higher value than **1** hour. No extra token cost.<br>• **Always retrieve live data:** use the value **0**. If our last update for the product was less than 1 hour ago, this consumes **1 extra token** per product.<br>**Example:** `&update=48` (only trigger an update if the product's last update is older than 48 hours) |
| `history` | optional | No extra token cost. Boolean value (`0` = false, `1` = true). If specified and set to `0`, the product object will not include the `csv` field. Use this to reduce response size and improve processing time if you do not need the historical data.<br>**Example:** `&history=0` |
| `rating` | optional | Up to **1** extra token per found product (**maximum of 5 additional tokens per search**). Boolean value (`0` = false, `1` = true). If specified and set to `1`, the product object will include our existing `RATING` and `COUNT_REVIEWS` history in the `csv` field.<br>• The extra token will only be consumed if our last update to both data points is less than **14** days ago.<br>• Using this parameter does not trigger an update to these fields; it only provides access to existing data if available.<br>• If you need up-to-date data, you have to use the `offers` parameter of a separate [product request](https://env.7xmtools.com/api-docs/product.html).<br>• Use this if you need access to the rating data, which may be outdated, but do not need any other data fields provided through the `offers` parameter — to save tokens and speed up the request.<br>**Example:** `&rating=1` (include rating and review count data in the `csv` field) |

> **Note:** If there is insufficient historical data for a price type, the actual interval of the weighted mean calculation for the `stats` field may be shorter than specified. All data provided via the `stats` field are calculated using the product object's `csv` history field; no new data is provided through this parameter.

## Token Cost

| Component | Cost |
| --- | --- |
| Product search (up to 20 results) | **10** tokens |
| `update` parameter | **0 or 1** extra token per found product (1 extra token only with `update=0` when our last update for the product was less than 1 hour ago) |
| `rating` parameter | Up to **1** extra token per found product, **maximum of 5 additional tokens per search** (only consumed if our last update to both data points is less than 14 days ago) |
| `stats` parameter | No extra token cost |
| `history` parameter | No extra token cost |

## Response

An ordered array of [product objects](https://env.7xmtools.com/api-docs/product-object.html) in the `products` field, or an ordered string array of ASINs in the `asinList` field (if the `asins-only` parameter was used).

## Examples

### Example request

Search for *wireless mouse* on amazon.com (note the URL-encoded search term):

```bash
https://api.keepa.com/search?key=YOUR_API_KEY&domain=1&type=product&term=wireless%20mouse
```

**Java**

```java
KeepaAPI api = new KeepaAPI("YOUR_API_KEY");
Request r = Request.getProductSearchRequest(AmazonLocale.US, "wireless mouse", null);
api.sendRequest(r)
    .done(result -> {
        for (Product product : result.products) {
            System.out.println(product.asin + "  " + product.title);
        }
    })
    .fail(failure -> System.out.println(failure));
```

**PHP**

```php
<?php
use Keepa\KeepaAPI;
use Keepa\API\Request;
use Keepa\API\ResponseStatus;
use Keepa\objects\AmazonLocale;

$api = new KeepaAPI("YOUR_API_KEY");
$response = $api->sendRequestWithRetry(Request::getProductSearchRequest(AmazonLocale::US, "wireless mouse", null));
if ($response->status == ResponseStatus::OK) {
    foreach ($response->products as $product) {
        echo $product->asin . "  " . $product->title . PHP_EOL;
    }
}
```

**Python**

```python
import requests

params = {
    "key": "YOUR_API_KEY",
    "domain": 1,
    "type": "product",
    "term": "wireless mouse",  # requests handles the URL encoding
}
r = requests.get("https://api.keepa.com/search", params=params)
data = r.json()
for product in data["products"]:
    print(product["asin"], product["title"])
```

**Node.js**

```javascript
const term = encodeURIComponent("wireless mouse");
const url = `https://api.keepa.com/search?key=YOUR_API_KEY&domain=1&type=product&term=${term}`;
const res = await fetch(url);
const data = await res.json();
for (const product of data.products) {
  console.log(product.asin, product.title);
}
```

**cURL**

```bash
curl -s "https://api.keepa.com/search?key=YOUR_API_KEY&domain=1&type=product&term=wireless%20mouse"
```

### Example response

```json
{
  "timestamp": 1753592460000,
  "tokensLeft": 268,
  "refillIn": 32000,
  "refillRate": 5,
  "tokenFlowReduction": 0,
  "tokensConsumed": 10,
  "processingTimeInMs": 341,
  "products": [
    {
      "asin": "B09HM94VDS",
      "domainId": 1,
      "title": "Logitech MX Master 3S Wireless Performance Mouse",
      "trackingSince": 5926110,
      "listedSince": 5925800,
      "lastUpdate": 7662540,
      "lastPriceChange": 7661180,
      "rootCategory": 172282,
      "categories": [11036491, 172282],
      "parentAsin": null,
      "manufacturer": "Logitech",
      "brand": "Logitech",
      "websiteDisplayGroupName": "Personal Computer",
      "model": "910-006556",
      "images": [{"l": "61ni3t6ryLL.jpg", "lH": 1500, "lW": 1500, "m": "71fP4WKKvNL.jpg", "mH": 500, "mW": 500}],
      "csv": [
        [7655020, 9999, 7658200, 9499, 7661180, 8999],
        [7655020, 9899, 7661180, 8999],
        null
      ]
    }
  ]
}
```

Response shortened for readability; illustrative values. A real response contains up to 20 product objects, each with the full set of [product object](https://env.7xmtools.com/api-docs/product-object.html) fields, and the `csv` history arrays cover all price types. Prices are integers in the smallest currency unit (e.g. `8999` = $89.99); history timestamps are in Keepa Time minutes.

### Example: ASINs only

With `asins-only=1`, the response contains a plain, ordered ASIN list in `asinList` instead of product objects:

**Java**

```java
KeepaAPI api = new KeepaAPI("YOUR_API_KEY");
Request r = Request.getProductSearchRequest(AmazonLocale.US,
        "wireless mouse", null, 1, false, true)  // asinsOnly = true;
api.sendRequest(r)
    .done(result -> {
        System.out.println(String.join(", ", result.asinList));
    })
    .fail(failure -> System.out.println(failure));
```

**PHP**

```php
<?php
use Keepa\KeepaAPI;
use Keepa\API\Request;
use Keepa\API\ResponseStatus;
use Keepa\objects\AmazonLocale;

$api = new KeepaAPI("YOUR_API_KEY");
// asins-only has no dedicated factory parameter in the PHP client —
// set it via the public parameter map:
$r = Request::getProductSearchRequest(AmazonLocale::US, "wireless mouse", null);
$r->parameter["asins-only"] = "1";
$response = $api->sendRequestWithRetry($r);
if ($response->status == ResponseStatus::OK) {
    print_r($response->asinList);
}
```

**Python**

```python
import requests

params = {
    "key": "YOUR_API_KEY",
    "domain": 1,
    "type": "product",
    "term": "wireless mouse",
    "asins-only": 1,
}
r = requests.get("https://api.keepa.com/search", params=params)
print(r.json()["asinList"])
```

**Node.js**

```javascript
const term = encodeURIComponent("wireless mouse");
const url = `https://api.keepa.com/search?key=YOUR_API_KEY&domain=1&type=product&term=${term}&asins-only=1`;
const res = await fetch(url);
const data = await res.json();
console.log(data.asinList);
```

**cURL**

```bash
curl -s "https://api.keepa.com/search?key=YOUR_API_KEY&domain=1&type=product&term=wireless%20mouse&asins-only=1"
```

```json
{
  "timestamp": 1753592520000,
  "tokensLeft": 258,
  "refillIn": 26000,
  "refillRate": 5,
  "tokenFlowReduction": 0,
  "tokensConsumed": 10,
  "processingTimeInMs": 112,
  "asinList": [
    "B09HM94VDS",
    "B07S395RWD",
    "B003NR57BY",
    "B01N7KFXKP"
  ]
}
```

Response shortened for readability; illustrative values.

> **Tip:** If you only need the ASINs (e.g. to feed them into a batch [product request](https://env.7xmtools.com/api-docs/product.html) later), use `asins-only=1` to keep the response small. If you do need product data but not the price history, add `history=0` to reduce response size and processing time.