Product Search — Keepa API Documentation

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 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 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.

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. Example: `&asins-only=1`
`stats`	optional	No extra token cost. If specified, the product object will include a `stats` field (see Statistics Object) with quick access to current prices, min/max prices, and weighted mean values. You can provide the `stats` parameter in two forms: Last x days: a positive integer value representing the number of last days to calculate stats for. Example: `&stats=180` (stats for the last 180 days) 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). 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. 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. Usage: Speed up requests: if up-to-date data is not required, use a higher value than 1 hour. No extra token cost. 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. 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. 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. The extra token will only be consumed if our last update to both data points is less than 14 days ago. Using this parameter does not trigger an update to these fields; it only provides access to existing data if available. If you need up-to-date data, you have to use the `offers` parameter of a separate product request. 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. 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 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):

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

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
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;
    }
}

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"])

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 -s "https://api.keepa.com/search?key=YOUR_API_KEY&domain=1&type=product&term=wireless%20mouse"

Example response#

{
  "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 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:

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
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);
}

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"])

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 -s "https://api.keepa.com/search?key=YOUR_API_KEY&domain=1&type=product&term=wireless%20mouse&asins-only=1"

{
  "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 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.