# Category Search

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

Search for Amazon category names. Retrieves up to 50 matching [category objects](https://env.7xmtools.com/api-docs/category-object.html).

GET · 1 token per search

The category search finds Amazon categories whose names match your search term and returns up to **50** matching [category objects](https://env.7xmtools.com/api-docs/category-object.html). It uses the same `/search` endpoint as the [product search](https://env.7xmtools.com/api-docs/product-search.html), selected via the `type=category` parameter.

## Endpoint

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

## 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-search.html#domain-ids) below. |
| `type` | required | Must be set to `category` to perform a category search. |
| `term` | required | The term you want to search for. Should be [URL encoded](https://en.wikipedia.org/wiki/Percent-encoding). Multiple space-separated keywords are possible, and all provided keywords must match. The minimum length of a keyword is **3** characters. |

### 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 search costs **1 token** per request.

## Response

*Identical to the [Category Lookup](https://env.7xmtools.com/api-docs/category-lookup.html) response.*

The response contains a `categories` field with all matching [category objects](https://env.7xmtools.com/api-docs/category-object.html) (up to 50) in the format:

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

## Examples

### Example request

Search the amazon.com locale (`domain=1`) for categories matching the term `camera`:

```bash
https://api.keepa.com/search?key=YOUR_API_KEY&domain=1&type=category&term=camera
```

**Java**

```java
KeepaAPI api = new KeepaAPI("YOUR_API_KEY");
Request r = Request.getCategorySearchRequest(AmazonLocale.US, "camera", false);
api.sendRequest(r)
    .done(result -> {
        result.categories.forEach((id, category) ->
                System.out.println(id + "  " + category.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::getCategorySearchRequest(AmazonLocale::US, "camera", false));
if ($response->status == ResponseStatus::OK) {
    print_r($response->categories);
}
```

**Python**

```python
import requests

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

for cat_id, category in data["categories"].items():
    print(cat_id, category["name"])
```

**Node.js**

```javascript
const term = encodeURIComponent("camera");
const res = await fetch(`https://api.keepa.com/search?key=YOUR_API_KEY&domain=1&type=category&term=${term}`);
const data = await res.json();

for (const [catId, category] of Object.entries(data.categories)) {
  console.log(catId, category.name);
}
```

**cURL**

```bash
curl -s "https://api.keepa.com/search?key=YOUR_API_KEY&domain=1&type=category&term=camera"
```

> **Tip:** To search with multiple keywords, URL encode the spaces — e.g. `term=digital%20cameras` for *digital cameras*. All provided keywords must match, and each keyword must be at least 3 characters long. HTTP libraries such as Python's `requests` (via `params`) or JavaScript's `encodeURIComponent` handle the encoding for you.

### Example response

```json
{
  "timestamp": 1783382461000,
  "tokensLeft": 299,
  "refillIn": 42000,
  "refillRate": 5,
  "tokenFlowReduction": 0.0,
  "tokensConsumed": 1,
  "processingTimeInMs": 14,
  "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"]
    },
    "502394": {
      "domainId": 1,
      "catId": 502394,
      "name": "Camera & Photo",
      "children": [281052, 499532, 3347871],
      "parent": 172282,
      "isBrowseNode": true,
      "highestRank": 3187540,
      "lowestRank": 1,
      "productCount": 812345
    }
  }
}
```

*Response shortened for readability; illustrative values.* A real search returns up to 50 matching categories, each as a full [category object](https://env.7xmtools.com/api-docs/category-object.html) (the second entry is abridged here). Prices such as `avgBuyBox` are integers in the smallest currency unit (e.g. cents); the keys of the `categories` map are the category IDs as JSON object keys (strings), while each object's `catId` field holds the numeric ID.