--- title: List and Search slug: rainforestapi/categories-api/list-and-search docTags: createdAt: 2024-07-30T12:48:41.125Z --- # List and Search Categories `GET` `/categories` The Categories API exposes just one endpoint `/categories` . You can use this endpoint to list or search for categories on a given Amazon `domain` . Categories are expressed in a hierarchical structure, each category may have one or more child categories as-determined by the `has_children` property. You can retrieve the child categories of a given category by passing the parent category ID in the `parent_id` parameter. To retrieve the top-level categories make a request without any `parent_id` . Top-level categories have their `is_root=true` property set to true. *** ### Parameters The following querystring (HTTP GET) parameters allow you to refine the results returned by the Categories API. | *`Parameter`* | *`Required`* | *`Description`* | | --------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | *`api_key`* | *`required`* | The API key for your account. | | *`domain`* | *`required`* | Filters the Categories returned to only those from the [Amazon Domain ](https://docs.trajectdata.com/rainforestapi/product-data-api/reference/amazon-domains)i.e. `domain=amazon.de` . | | *`type`* | *`optional`* | Determines the type of Category to search for.
Valid values are: `standard` - for regular Amazon categories compatible with the `category_id` parameter on `type=search` or `type=category` requests.
`bestsellers` , `gift_ideas` , `most_wished_for` , `movers_and_shakers` or `new_releases` - for Bestseller Amazon categories compatible with the `category_id` parameter on `type=bestseller` requests.
`deals` - for Deals Amazon categories compatible with the `category_id` parameter on `type=deals` requests.
Defaults to `standard` when the `type` parameter is not specified. | | *`id`* | *`optional`* | A single ID of the category to retrieve.
**Note **that `id` cannot be used when `parent_id` or `search_term` are used. | | *`parent_id`* | *`optional`* | The ID of the parent category to retrieve child categories for.
**Note** that `parent_id` cannot be used when `id` or `search_term` are used. | | *`search_term`* | *`optional`* | Searches the entire category hierarchy for categories containing the `search_term` i.e. `search_term=appliances` (to return only categories containing the string `appliances` ).
**Note** that `search_term` cannot be used when `id` or `parent_id` are used. | ### Results The Categories API returns the following properties: | *`Property`* | *`Type`* | *`Description`* | | -------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | *`categories`* | *`array`* | An array of Category objects containing details of a given category. The `categories` array is present when either the `parent_id` or `search_term` request parameters are used.
- `domain`
- `string`
- The Amazon Domain the category belongs to.

- `id`
- `string`
- The ID of the category. Can be passed into the `category_id` parameter of a subsequent [category ](https://docs.trajectdata.com/rainforestapi/product-data-api/parameters/category), [search ](https://docs.trajectdata.com/rainforestapi/product-data-api/parameters/category), [deals ](https://docs.trajectdata.com/rainforestapi/product-data-api/parameters/deals)or [bestsellers ](https://docs.trajectdata.com/rainforestapi/product-data-api/parameters/bestsellers)API request.

- `name`
- `string`
- The name of the category.

- `has_children`
- `boolean`
- True/false as to whether this category has child categories.

- `is_root`
- `boolean`
- True/false as to whether this category is a top-level (root) category.

- `path`
- `string`
- The fully qualified path to the category in the category hierarchy, delimited by ">" characters. For example: `Category 1 > Category 2 > Category 3`

- `type`
- `string`
- The type of category - either `standard` , `bestsellers` , `gift_ideas` , `most_wished_for` , `movers_and_shakers` , `new_releases` or `deals` . | | *`current_category`* | *`object`* | An object with the same properties as the category objects in the `categories` array showing details of the current category.
**Note** that `current_category` is only present when a request is made using the `parent_id` request parameter (i.e. when retrieving child categories for a given `parent_id` ). | | *`parent_category`* | *`object`* | An object with the same properties as the category objects in the `categories` array showing details of the parent category.
**Note** that `parent_category` is only present when a request is made using the `parent_id` request parameter (i.e. when retrieving child categories for a given `parent_id` ). `parent_category` shows details of the category that is the parent of the category specified in `parent_id` .
**Note** `parent_category` is not returned if the category specified in the `parent_id` request parameter is `is_root=true` . | | *`category`* | *`object`* | An object with the same properties as the category objects in the `categories` array showing details of the single category requested by the `id` parameter.
**Note** that `category` is only present when a request is made using the `id` request parameter (i.e. when retrieving details of a single category). | ### Example - Listing Root Categories In the example below we retrieve all top-level (root) categories for the `amazon.com` domain: :::CodeblockTabs ```curl curl -L --get https://api.rainforestapi.com/categories \ -d api_key="demo" \ -d domain="amazon.com" ``` ```nodejs const axios = require('axios'); axios.get('https://api.rainforestapi.com/categories?api_key=demo&domain=amazon.com') .then(response => { const apiResponse = response.data; console.log("Categories: ", JSON.stringify(apiResponse, 0, 2); }).catch(error => { console.error(error); }); ``` ```python import requests import json params = { 'api_key': 'demo', 'domain': 'amazon.com' } api_result = requests.get('https://api.rainforestapi.com/categories', { params }) api_response = api_result.json() print "Categories: ", json.dumps(api_response) ``` ```php 'demo', 'domain' => 'amazon.com', ]); $ch = curl_init('https://api.rainforestapi.com/categories', $queryString); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); curl_setopt($ch, CURLOPT_FOLLOWLOCATION, true); # the following options are required if you're using an outdated OpenSSL version # more details: https://www.openssl.org/blog/blog/2021/09/13/LetsEncryptRootCertExpire/ curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, false); curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false); curl_setopt($ch, CURLOPT_TIMEOUT, 180); $json = curl_exec($ch); curl_close($ch); $api_result = json_decode($json, true); print_r($api_result); ?> ``` ::: The Categories API responds with the top-level (root) categories for `amazon.com` in the `categories` property. ```json { "request_info": { "success": true, "credits_used": 1, "credits_remaining": 999, "credits_used_this_request": 1, "credits_reset_at": "2020-01-01T00:00:00.000Z" }, "categories": [ { "domain": "amazon.com", "id": "2619526011", "name": "Appliances", "has_children": true, "is_root": true, "path": "Appliances" }, { "domain": "amazon.com", "id": "2617942011", "name": "Arts, Crafts & Sewing", "has_children": true, "is_root": true, "path": "Arts, Crafts & Sewing" } ] } ``` *** ### Example - Listing Child Categories In the example below we retrieve child categories for a parent category with ID `2619526011` on `amazon.com` : :::CodeblockTabs ```curl curl -L --get https://api.rainforestapi.com/categories \ -d api_key="demo" \ -d parent_id="2619526011" \ -d domain="amazon.com" ``` ```nodejs const axios = require('axios'); axios.get('https://api.rainforestapi.com/categories?api_key=demo&parent_id=2619526011&domain=amazon.com') .then(response => { const apiResponse = response.data; console.log("Categories: ", JSON.stringify(apiResponse, 0, 2); }).catch(error => { console.error(error); }); ``` ```python import requests import json params = { 'api_key': 'demo', 'parent_id': '2619526011', 'domain': 'amazon.com' } api_result = requests.get('https://api.rainforestapi.com/categories', { params }) api_response = api_result.json() print "Categories: ", json.dumps(api_response) ``` ```php 'demo', 'parent_id' => '2619526011', 'domain' => 'amazon.com', ]); $ch = curl_init('https://api.rainforestapi.com/categories', $queryString); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); curl_setopt($ch, CURLOPT_FOLLOWLOCATION, true); # the following options are required if you're using an outdated OpenSSL version # more details: https://www.openssl.org/blog/blog/2021/09/13/LetsEncryptRootCertExpire/ curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, false); curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false); curl_setopt($ch, CURLOPT_TIMEOUT, 180); $json = curl_exec($ch); curl_close($ch); $api_result = json_decode($json, true); print_r($api_result); ?> ``` ::: The Categories API responds with the child categories for parent category with ID `2619526011` on `amazon.com` in the `categories` property. ```json { "request_info": { "success": true }, "current_category": { "domain": "amazon.com", "id": "2619526011", "name": "Appliances", "has_children": true, "is_root": true, "path": "Appliances" }, "categories": [ { "domain": "amazon.com", "id": "17921061011", "name": "Refrigerators, Freezers & Ice Makers", "has_children": true, "is_root": false, "path": "Appliances > Refrigerators, Freezers & Ice Makers", "parent_id": "2619526011", "parent_name": "Appliances" }, { "domain": "amazon.com", "id": "18116194011", "name": "Laundry Appliances", "has_children": true, "is_root": false, "path": "Appliances > Laundry Appliances", "parent_id": "2619526011", "parent_name": "Appliances" } ] } ``` *** **Next Steps**      [Categories API Overview](https://docs.trajectdata.com/rainforestapi/categories-api/overview)