# Category Lookup

Source: https://env.7xmtools.com/api-docs/category-lookup.html

Retrieve [category objects](https://env.7xmtools.com/api-docs/category-object.html) and optionally their parent tree using a category ID.

GET · 1 token per request (up to 10 categories)

Given one or more Amazon category node IDs, this request returns the matching [category objects](https://env.7xmtools.com/api-docs/category-object.html). 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.

> **Note:** We cannot provide any data for promotional categories (e.g., Launchpad).

## Endpoint

```
GET https://api.keepa.com/category?key=<yourAccessKey>&domain=<domainId>&category=<categoryId>&parents=<includeParents>
```

## 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/category-lookup.html#domain-ids) below. |
| `category` | required | The category node ID of the category you want to request.<br>• For batch requests, use a comma-separated list of IDs (up to **10**). **Token cost remains the same.**<br>• Alternatively, you can specify the value **0** to retrieve a list of all root categories. |
| `parents` | required | Whether or not to include the category tree for each category. Valid values:<br>• `1` — include parent categories.<br>• `0` — do not include parent categories. |

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

## 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](https://env.7xmtools.com/api-docs/category-search.html) response.*

The response contains:

- A `categories` field with all found [category objects](https://env.7xmtools.com/api-docs/category-object.html).
- 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>`:

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

## Examples

### Example request

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

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

**Java**

```java
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**

```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::getCategoryLookupRequest(AmazonLocale::US, true, "281052"));
if ($response->status == ResponseStatus::OK) {
    print_r($response->categories);
}
```

**Python**

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

**Node.js**

```javascript
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**

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

### Example response

```json
{
  "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](https://env.7xmtools.com/api-docs/category-object.html) 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):

```bash
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`:

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

> **Tip:** The keys of the `categories` and `categoryParents` maps are the category IDs as JSON object keys (strings), while each object's `catId` field holds the numeric ID.