Category Lookup

Given one or more Amazon category node IDs, this request returns the matching category objects. If requested, it also returns every category on the path from each category up to the root of the category tree, so you can reconstruct the full tree by traversing the parents.

Endpoint#

Parameters#

Valid domain IDs#

Token Cost#

A category lookup costs 1 token per request. Batch requests with a comma-separated list of up to 10 category IDs cost the same 1 token, as does requesting all root categories with category=0.

Response#

Identical to the Category Search response.

The response contains:

• A categories field with all found category objects.
• If the parents parameter was set to 1, a categoryParents field with all category objects found on the way to the tree's root.

You can construct a category tree by traversing the parents.

Both fields are maps in the format <categoryId, categoryObject>:

{
  "<categoryId>": categoryObject,
  "<categoryId2>": categoryObject,
  ...
}

Examples#

Example request#

Look up the category Digital Cameras (node ID 281052) on amazon.com, including its parent tree:

https://api.keepa.com/category?key=YOUR_API_KEY&domain=1&category=281052&parents=1

KeepaAPI api = new KeepaAPI("YOUR_API_KEY");
Request r = Request.getCategoryLookupRequest(AmazonLocale.US, true, 281052);
api.sendRequest(r)
    .done(result -> {
        System.out.println(result.categories.get(281052L).name);
    })
    .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::getCategoryLookupRequest(AmazonLocale::US, true, "281052"));
if ($response->status == ResponseStatus::OK) {
    print_r($response->categories);
}

import requests

params = {"key": "YOUR_API_KEY", "domain": 1, "category": 281052, "parents": 1}
r = requests.get("https://api.keepa.com/category", params=params)
data = r.json()

category = data["categories"]["281052"]
print(category["name"], "- parent:", category["parent"])

const res = await fetch("https://api.keepa.com/category?key=YOUR_API_KEY&domain=1&category=281052&parents=1");
const data = await res.json();

const category = data.categories["281052"];
console.log(category.name, "- parent:", category.parent);

curl -s "https://api.keepa.com/category?key=YOUR_API_KEY&domain=1&category=281052&parents=1"

Example response#

{
  "timestamp": 1783382461000,
  "tokensLeft": 299,
  "refillIn": 42000,
  "refillRate": 5,
  "tokenFlowReduction": 0.0,
  "tokensConsumed": 1,
  "processingTimeInMs": 12,
  "categories": {
    "281052": {
      "domainId": 1,
      "catId": 281052,
      "name": "Digital Cameras",
      "websiteDisplayGroup": "photo_display_on_website",
      "children": [3109924011, 7242008011, 3017941, 2476680011, 330405011, 2476681011, 3109925011],
      "parent": 502394,
      "isBrowseNode": true,
      "highestRank": 2452122,
      "lowestRank": 1,
      "productCount": 148632,
      "avgBuyBox": 45999,
      "avgBuyBox90": 46750,
      "avgBuyBox365": 47210,
      "avgBuyBoxDeviation": 2450,
      "avgReviewCount": 235,
      "avgRating": 43,
      "isFBAPercent": 65.5,
      "soldByAmazonPercent": 22.4,
      "hasCouponPercent": 10.2,
      "avgOfferCountNew": 3.5,
      "avgOfferCountUsed": 1.2,
      "sellerCount": 452,
      "brandCount": 120,
      "avgDeltaPercent30BuyBox": 2.1,
      "avgDeltaPercent90BuyBox": 3.4,
      "avgDeltaPercent30Amazon": 0.8,
      "avgDeltaPercent90Amazon": 1.5,
      "relatedCategories": [672123011, 281407, 11057241],
      "topBrands": ["Sony", "Canon", "Panasonic"]
    }
  },
  "categoryParents": {
    "502394": {
      "domainId": 1,
      "catId": 502394,
      "name": "Camera & Photo",
      "children": [281052, 499532, 3347871],
      "parent": 172282,
      "isBrowseNode": true
    },
    "172282": {
      "domainId": 1,
      "catId": 172282,
      "name": "Electronics",
      "websiteDisplayGroup": "ce_display_on_website",
      "children": [502394, 172623, 172541],
      "parent": 0,
      "isBrowseNode": true
    }
  }
}

Response shortened for readability; illustrative values. The categoryParents entries are abridged category objects here — the API returns full category objects for each entry. A parent value of 0 marks a root category.

Other request variants#

Batch lookup of up to 10 categories in one request (still 1 token):

https://api.keepa.com/category?key=YOUR_API_KEY&domain=1&category=281052,502394,172282&parents=0

List all root categories of a locale by passing category=0:

https://api.keepa.com/category?key=YOUR_API_KEY&domain=1&category=0&parents=0