Product Finder

This request offers the same core functionality as the Product Finder on the Keepa website.

• The request returns only ASIN lists, not product objects.
• Each request consumes 10 tokens plus an additional token per 100 ASINs in the result set.
• A query can return up to 10,000 ASINs using paging, with a minimum page size of 50 ASINs. If using paging, initial search results are not cached, so the order of results may be inconsistent between individual pages if there is a delay between consecutive page requests.
• Filters are joined by an AND condition.
• For filters allowing multiple entries (all arrays), each specified entry is considered with an OR condition, supporting a maximum of 50 entries.
• The product query searches the Keepa database, not Amazon's. It may not find all products on Amazon that match your query.
• Product data constantly changes. Running the same query twice may yield different results, as products may be misplaced due to recent changes or updates during the query execution.

Endpoint#

You can choose between an HTTP GET or POST request.

GET format#

The <queryJSON> must be URL-encoded if the GET format is used.

POST format#

The POST payload must contain the <queryJSON>.

Parameters#

Valid domain IDs#

Token Cost#

• Base cost: 10 tokens per request + 1 token per 100 ASINs in the result set.
• stats=1: additionally 30 tokens + 1 token for every 1,000,000 products matched by the query as a whole (not just the current page).

The query JSON#

The selection JSON combines paging, sorting and filters. All filters are optional; the query is valid as long as at least one filter is specified. The scalar and array filters are listed individually below; price/value statistics filters follow systematic naming patterns of the form <family>_<PRICE_TYPE>_lte|_gte (see price-type statistics filters).

{
    "page": Integer,
    "perPage": Integer,
    "sort": [ [String, String] ],

    "rootCategory": Long[],
    "categories_include": Long[],
    "categories_exclude": Long[],
    "salesRankReference": Long,
    "title": String,
    "manufacturer": String[],
    "brand": String[],
    "singleVariation": Boolean,
    "historicalParentASIN": String,
    "hasParentASIN": Boolean,
    "productType": Integer,
    "availabilityAmazon": Integer[],
    "returnRate": Integer[],
    "hasReviews": Boolean,
    "isLowestOffer": Boolean,
    "trackingSince_lte": Integer, "trackingSince_gte": Integer,
    "lastPriceChange_lte": Integer, "lastPriceChange_gte": Integer,
    "lastOffersUpdate_lte": Integer, "lastOffersUpdate_gte": Integer,

    "partNumber": String[], "model": String[],
    "color": String[], "size": String[], "edition": String[], "format": String[],
    "author": String[], "binding": String[], "genre": String[], "languages": String[],
    "publisher": String[], "platform": String[],
    "activeIngredients": String[], "specialIngredients": String[],
    "itemTypeKeyword": String[], "targetAudienceKeyword": String[],
    "itemForm": String[], "scent": String[], "unitType": String[],
    "pattern": String[], "style": String[], "material": String[],
    "brandStoreName": String[], "brandStoreUrlName": String[],
    "frequentlyBoughtTogether": String[],

    "packageHeight_lte": Integer, "packageHeight_gte": Integer,
    "packageLength_lte": Integer, "packageLength_gte": Integer,
    "packageWidth_lte": Integer, "packageWidth_gte": Integer,
    "packageWeight_lte": Integer, "packageWeight_gte": Integer,
    "itemHeight_lte": Integer, "itemHeight_gte": Integer,
    "itemLength_lte": Integer, "itemLength_gte": Integer,
    "itemWidth_lte": Integer, "itemWidth_gte": Integer,
    "itemWeight_lte": Integer, "itemWeight_gte": Integer,

    "variationCount_lte": Integer, "variationCount_gte": Integer,
    "imageCount_lte": Integer, "imageCount_gte": Integer,
    "videoCount_lte": Byte, "videoCount_gte": Byte,
    "variationReviewCount_lte": Integer, "variationReviewCount_gte": Integer,
    "variationRatingCount_lte": Integer, "variationRatingCount_gte": Integer,

    "buyBoxStatsAmazon30_lte": Integer, "buyBoxStatsAmazon30_gte": Integer,
    "buyBoxStatsAmazon90_lte": Integer, "buyBoxStatsAmazon90_gte": Integer,
    "buyBoxStatsAmazon180_lte": Integer, "buyBoxStatsAmazon180_gte": Integer,
    "buyBoxStatsAmazon365_lte": Integer, "buyBoxStatsAmazon365_gte": Integer,
    "buyBoxStatsTopSeller30_lte": Integer, "buyBoxStatsTopSeller30_gte": Integer,
    "buyBoxStatsTopSeller90_lte": Integer, "buyBoxStatsTopSeller90_gte": Integer,
    "buyBoxStatsTopSeller180_lte": Integer, "buyBoxStatsTopSeller180_gte": Integer,
    "buyBoxStatsTopSeller365_lte": Integer, "buyBoxStatsTopSeller365_gte": Integer,
    "buyBoxStatsSellerCount30_lte": Integer, "buyBoxStatsSellerCount30_gte": Integer,
    "buyBoxStatsSellerCount90_lte": Integer, "buyBoxStatsSellerCount90_gte": Integer,
    "buyBoxStatsSellerCount180_lte": Integer, "buyBoxStatsSellerCount180_gte": Integer,
    "buyBoxStatsSellerCount365_lte": Integer, "buyBoxStatsSellerCount365_gte": Integer,

    "outOfStockPercentage90_lte": Integer, "outOfStockPercentage90_gte": Integer,
    "outOfStockCountAmazon30_lte": Integer, "outOfStockCountAmazon30_gte": Integer,
    "outOfStockCountAmazon90_lte": Integer, "outOfStockCountAmazon90_gte": Integer,
    "deltaPercent90_monthlySold_lte": Integer, "deltaPercent90_monthlySold_gte": Integer,
    "monthlySold_lte": Integer, "monthlySold_gte": Integer,

    "couponOneTimeAbsolute_lte": Integer, "couponOneTimeAbsolute_gte": Integer,
    "couponOneTimePercent_lte": Integer, "couponOneTimePercent_gte": Integer,
    "couponSNSPercent_lte": Integer, "couponSNSPercent_gte": Integer,
    "flipability30_lte": Byte, "flipability30_gte": Byte,
    "flipability90_lte": Byte, "flipability90_gte": Byte,
    "flipability365_lte": Byte, "flipability365_gte": Byte,
    "businessDiscount_lte": Byte, "businessDiscount_gte": Byte,

    "isHazMat": Boolean, "isHeatSensitive": Boolean, "isAdultProduct": Boolean,
    "isEligibleForSuperSaverShipping": Boolean,
    "isSNS": Boolean, "isMerchOnDemand": Boolean, "isPrimeExclusive": Boolean,
    "batteriesRequired": Boolean, "batteriesIncluded": Boolean,
    "hasMainVideo": Boolean, "hasAPlus": Boolean, "hasAPlusFromManufacturer": Boolean,

    "buyBoxIsAmazon": Boolean, "buyBoxIsFBA": Boolean, "buyBoxIsUnqualified": Boolean,
    "buyBoxIsPreorder": Boolean, "buyBoxIsBackorder": Boolean, "buyBoxIsPrimeExclusive": Boolean,
    "buyBoxSellerId": String[], "buyBoxUsedCondition": Integer[],
    "buyBoxUsedIsFBA": Boolean, "buyBoxUsedSellerId": String[],
    "sellerIds": String[], "sellerIdsLowestFBA": String[], "sellerIdsLowestFBM": String[],
    "dealType": String[],

    "numberOfItems_lte": Integer, "numberOfItems_gte": Integer,
    "numberOfPages_lte": Integer, "numberOfPages_gte": Integer,
    "publicationDate_lte": Integer, "publicationDate_gte": Integer,
    "releaseDate_lte": Integer, "releaseDate_gte": Integer,
    "lightningEnd_lte": Integer, "lightningEnd_gte": Integer,

    "current_<PRICE_TYPE>_lte": Integer, "current_<PRICE_TYPE>_gte": Integer,
    "delta30_<PRICE_TYPE>_lte": Integer, "delta30_<PRICE_TYPE>_gte": Integer,
    "delta90_<PRICE_TYPE>_lte": Integer, "delta90_<PRICE_TYPE>_gte": Integer,
    "deltaPercent30_<PRICE_TYPE>_lte": Integer, "deltaPercent30_<PRICE_TYPE>_gte": Integer,
    "deltaPercent90_<PRICE_TYPE>_lte": Integer, "deltaPercent90_<PRICE_TYPE>_gte": Integer,
    "deltaLast_<PRICE_TYPE>_lte": Integer, "deltaLast_<PRICE_TYPE>_gte": Integer,
    "avg30_<PRICE_TYPE>_lte": Integer, "avg30_<PRICE_TYPE>_gte": Integer,
    "avg90_<PRICE_TYPE>_lte": Integer, "avg90_<PRICE_TYPE>_gte": Integer,
    "avg180_<PRICE_TYPE>_lte": Integer, "avg180_<PRICE_TYPE>_gte": Integer,
    "avg365_<PRICE_TYPE>_lte": Integer, "avg365_<PRICE_TYPE>_gte": Integer,
    "lastPriceChange_<PRICE_TYPE>_lte": Integer, "lastPriceChange_<PRICE_TYPE>_gte": Integer,
    "backInStock_<PRICE_TYPE>": Boolean,
    "isLowest_<PRICE_TYPE>": Boolean,
    "isLowest90_<PRICE_TYPE>": Boolean
}

Paging#

Paging is optional; by default, up to 50 results are provided.

Sorting#

Sorting is optional; by default, results are sorted ascending by current sales rank.

sort can include up to three sorting criteria. Use a two-dimensional array where each entry is in the format [fieldName, sortDirection]:

• fieldName: any filter from the list below that is either a String or Integer, except the filter-only fields listed in the note. The fieldName must not include _lte or _gte.
• sortDirection: use "asc" for ascending or "desc" for descending.

"sort": [ ["current_SALES", "asc"] ]

Filter basics#

The following fields act as filters. Only products that exactly match all filters will be returned by the query. All string filters are case insensitive and can be used as exclusion filters by using the prefix ✜. Filters ending in _gte restrict the output to values "Greater than or equal" to the specified value, while _lte means "Less than or equal".

minMatch — K-of-N matching on array filters

Entries within one array filter are normally joined by OR: any one of them may match. minMatch raises that bar per field, as a map of filter name to the number of entries that must match. Setting it equal to the number of entries turns that filter into an AND.

"minMatch": { "sellerIds": 2, "manufacturer": 1 }

Here a product must be offered by at least two of the listed sellerIds, while manufacturer keeps its default OR behaviour. Values are clamped to the number of entries actually supplied for that filter.

exists — matching on a missing value

Every other filter matches on a value being present. exists is the opposite: a map of filter name to a Boolean, where false selects the products we hold no value for, and true those we do.

"exists": { "brand": false, "color": true }

This example returns products that have no brand and do have a colour. Entries combine with every other filter using AND, so "brand": ["canon"] together with "exists": { "brand": false } matches nothing.

An unknown or unsupported filter name is rejected with an invalidParameter error rather than ignored, and at most 50 entries are accepted. Filters that always carry a value — productType or hasParentASIN, for example — are not supported, because asking whether they exist has no meaningful answer. Supported filter names:

Category & title filters#

Product type, variations & state#

Product attribute filters (String arrays)#

Most of these are also available to the exists filter, to find the products that carry no value for one of them at all.

Dimensions & media#

Product flags (Boolean)#

Buy Box & seller filters#

Stock, coupons & scores#

Update & lifecycle times#

All values are Keepa Time minutes.

Sales rank filters#

Offer counts & Buy Box statistics#

Monthly sold, fees & packaging#

Classification & state#

Price-type statistics filters#

These filter families exist for every price type (see the list below). The placeholder <PRICE_TYPE> stands for a price type name such as AMAZON, NEW or BUY_BOX_SHIPPING — e.g. current_AMAZON_gte, avg90_NEW_lte, isLowest_BUY_BOX_SHIPPING.

Available price types

The standard price type set — available in the current, delta, deltaPercent, deltaLast, avg30/90/180 and backInStock families:

AMAZON, NEW, USED, SALES, LISTPRICE, COLLECTIBLE, REFURBISHED, NEW_FBM_SHIPPING, LIGHTNING_DEAL, WAREHOUSE, NEW_FBA, COUNT_NEW, COUNT_USED, COUNT_REFURBISHED, COUNT_COLLECTIBLE, RATING, COUNT_REVIEWS, BUY_BOX_SHIPPING, USED_NEW_SHIPPING, USED_VERY_GOOD_SHIPPING, USED_GOOD_SHIPPING, USED_ACCEPTABLE_SHIPPING, REFURBISHED_SHIPPING, TRADE_IN

The avg365, lastPriceChange, isLowest and isLowest90 families additionally support:

BUY_BOX_USED_SHIPPING, EBAY_NEW_SHIPPING, EBAY_USED_SHIPPING, PRIME_EXCL, RENT

Keepa Time Minutes#

Time format used for all timestamps. To convert to an uncompressed Unix epoch time:

• For milliseconds: (keepaTime + 21564000) * 60000
• For seconds: (keepaTime + 21564000) * 60

Response#

{
    "asinList": String array,
    "searchInsights": Search Insights Object,
    "totalResults": Integer
}

Examples#

Example query#

Find products in root category 3167641 with a current Amazon price between € 10.00 and € 50.00, 100 results per page:

{
  "rootCategory": 3167641,
  "current_AMAZON_lte": 5000,
  "current_AMAZON_gte": 1000,
  "perPage": 100,
  "page": 0
}

KeepaAPI api = new KeepaAPI("YOUR_API_KEY");
ProductFinderRequest finder = new ProductFinderRequest();
finder.rootCategory = new String[]{"3167641"};
finder.current_AMAZON_gte = 1000;   // prices in cents
finder.current_AMAZON_lte = 5000;
finder.perPage = 100;
finder.page = 0;
api.sendRequest(Request.getProductFinderRequest(AmazonLocale.DE, finder))
    .done(result -> {
        System.out.println(result.asinList.length + " ASINs on this page");
    })
    .fail(failure -> System.out.println(failure));

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

use Keepa\objects\ProductFinderRequest;
$api = new KeepaAPI("YOUR_API_KEY");
$finder = new ProductFinderRequest();
$finder->rootCategory = 3167641;
$finder->current_AMAZON_gte = 1000;   // prices in cents
$finder->current_AMAZON_lte = 5000;
$finder->perPage = 100;
$finder->page = 0;
$response = $api->sendRequestWithRetry(Request::getFinderRequest(AmazonLocale::DE, $finder));
if ($response->status == ResponseStatus::OK) {
    print_r($response->asinList);
}

import requests

selection = {
    "rootCategory": 3167641,
    "current_AMAZON_lte": 5000,
    "current_AMAZON_gte": 1000,
    "perPage": 100,
    "page": 0,
}
r = requests.post(
    "https://api.keepa.com/query",
    params={"domain": 3, "key": "YOUR_API_KEY"},
    json=selection,
)
data = r.json()
print(data["totalResults"], "matches")
print(data["asinList"][:10])

const selection = {
  rootCategory: 3167641,
  current_AMAZON_lte: 5000,
  current_AMAZON_gte: 1000,
  perPage: 100,
  page: 0,
};
const res = await fetch("https://api.keepa.com/query?domain=3&key=YOUR_API_KEY", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify(selection),
});
const data = await res.json();
console.log(data.totalResults, "matches");
console.log(data.asinList.slice(0, 10));

# GET: the selection JSON must be URL-encoded (--data-urlencode does this)
curl -s -G "https://api.keepa.com/query" \
  --data-urlencode "key=YOUR_API_KEY" \
  --data-urlencode "domain=3" \
  --data-urlencode 'selection={"rootCategory":3167641,"current_AMAZON_lte":5000,"current_AMAZON_gte":1000,"perPage":100,"page":0}'

# POST: the selection JSON is the request body
curl -s -X POST "https://api.keepa.com/query?domain=3&key=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"rootCategory":3167641,"current_AMAZON_lte":5000,"current_AMAZON_gte":1000,"perPage":100,"page":0}'

Example with Search Insights (stats=1)#

Same query, but with aggregated KPIs over the whole result set — note the additional token cost:

curl -s -X POST "https://api.keepa.com/query?domain=3&key=YOUR_API_KEY&stats=1" \
  -H "Content-Type: application/json" \
  -d '{"rootCategory":3167641,"current_AMAZON_gte":1000,"deltaPercent90_AMAZON_gte":20,"sort":[["current_SALES","asc"]]}'

Example response#

{
  "timestamp": 1783382461000,
  "tokensLeft": 248,
  "refillIn": 31000,
  "refillRate": 5,
  "tokenFlowReduction": 0.0,
  "tokensConsumed": 11,
  "processingTimeInMs": 342,
  "asinList": [
    "B0BDHWDR12",
    "B09XS7JWHH",
    "B08N5WRWNW",
    "B07YN82X3B",
    "B01M0AGIKS"
  ],
  "totalResults": 18234
}

Response shortened for readability; illustrative values. With &stats=1 the response additionally contains the searchInsights field — see the Search Insights Object for a full example.