---
title: List and Search
slug: redcircleapi/categories-api/list-and-search
docTags:
createdAt: 2024-07-27T14:22:43.825Z
---
# List and Search Categories
`GET` `/categories`
The Categories API exposes just one endpoint `/categories` .
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. |
| `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.
* `id`
* `string`
* The ID of the category. Can be passed into the `category_id` parameter of a subsequent [category ](https://docs.trajectdata.com/redcircleapi/product-data-api/parameters/category)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` |
| `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:
:::CodeblockTabs
```curl
curl -L --get https://api.redcircleapi.com/categories \
-d api_key="demo"
```
```nodejs
const axios = require('axios');
axios.get('https://api.redcircleapi.com/categories?api_key=demo')
.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'
}
api_result = requests.get('https://api.redcircleapi.com/categories', { params })
api_response = api_result.json()
print "Categories: ", json.dumps(api_response)
```
```php
'demo'
]);
$ch = curl_init('https://api.redcircleapi.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 in the `categories` property.
```json
{
"request_info": {
"success": true
},
"categories": [
{
"id": "5xt1a",
"name": "Grocery",
"has_children": true,
"is_root": true,
"path": "Grocery",
"link": "https://www.target.com/c/grocery/-/N-5xt1a",
"type": "standard",
"domain": "target.com"
},
{
"id": "5xsz1",
"name": "Household Essentials",
"has_children": true,
"is_root": true,
"path": "Household Essentials",
"link": "https://www.target.com/c/household-essentials/-/N-5xsz1",
"type": "standard",
"domain": "target.com"
},
{
"id": "5xtb0",
"name": "Toys",
"has_children": true,
"is_root": true,
"path": "Toys",
"link": "https://www.target.com/c/toys/-/N-5xtb0",
"type": "standard",
"domain": "target.com"
},
{
"id": "5xtg5",
"name": "Video Games",
"has_children": true,
"is_root": true,
"path": "Video Games",
"link": "https://www.target.com/c/video-games/-/N-5xtg5",
"type": "standard",
"domain": "target.com"
},
{
"id": "5xsxe",
"name": "Movies, Music & Books",
"has_children": true,
"is_root": true,
"path": "Movies, Music & Books",
"link": "https://www.target.com/c/movies-music-books/-/N-5xsxe",
"type": "standard",
"domain": "target.com"
},
{
"id": "5xt85",
"name": "Sports & Outdoors",
"has_children": true,
"is_root": true,
"path": "Sports & Outdoors",
"link": "https://www.target.com/c/sports-outdoors/-/N-5xt85",
"type": "standard",
"domain": "target.com"
},
{
"id": "55r1x",
"name": "Beauty",
"has_children": true,
"is_root": true,
"path": "Beauty",
"link": "https://www.target.com/c/beauty/-/N-55r1x",
"type": "standard",
"domain": "target.com"
},
{
"id": "5xtnr",
"name": "Furniture",
"has_children": true,
"is_root": true,
"path": "Furniture",
"link": "https://www.target.com/c/furniture/-/N-5xtnr",
"type": "standard",
"domain": "target.com"
},
{
"id": "hz89j",
"name": "Kitchen & Dining",
"has_children": true,
"is_root": true,
"path": "Kitchen & Dining",
"link": "https://www.target.com/c/kitchen-dining/-/N-hz89j",
"type": "standard",
"domain": "target.com"
},
{
"id": "5xtg6",
"name": "Electronics",
"has_children": true,
"is_root": true,
"path": "Electronics",
"link": "https://www.target.com/c/electronics/-/N-5xtg6",
"type": "standard",
"domain": "target.com"
},
{
"id": "xcoz4",
"name": "Kids",
"has_children": true,
"is_root": true,
"path": "Kids",
"link": "https://www.target.com/c/kids/-/N-xcoz4",
"type": "standard",
"domain": "target.com"
}
]
}
```
***
### Example - Listing Child Categories
In the example below we retrieve child categories for a parent category with ID `5xtg6` :
:::CodeblockTabs
```curl
curl -L --get https://api.redcircleapi.com/categories \
-d api_key="demo" \
-d parent_id="5xtg6"
```
```nodejs
const axios = require('axios');
axios.get('https://api.redcircleapi.com/categories?api_key=demo&parent_id=5xtg6')
.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': '5xtg6'
}
api_result = requests.get('https://api.redcircleapi.com/categories', { params })
api_response = api_result.json()
print "Categories: ", json.dumps(api_response)
```
```php
'demo',
'parent_id' => '5xtg6'
]);
$ch = curl_init('https://api.redcircleapi.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 `5xtg6` in the `categories` property.
```json
{
"request_info": {
"success": true
},
"current_category": {
"id": "5xtg6",
"name": "Electronics",
"has_children": true,
"is_root": true,
"path": "Electronics",
"link": "https://www.target.com/c/electronics/-/N-5xtg6",
"type": "standard",
"domain": "target.com"
},
"categories": [
{
"id": "5xtez",
"name": "Cameras",
"has_children": true,
"is_root": false,
"path": "Electronics > Cameras",
"link": "https://www.target.com/c/cameras-camcorders-electronics/-/N-5xtez",
"parent_id": "5xtg6",
"parent_name": "Electronics",
"type": "standard",
"domain": "target.com"
},
{
"id": "5xte8",
"name": "Cell Phones",
"has_children": true,
"is_root": false,
"path": "Electronics > Cell Phones",
"link": "https://www.target.com/c/cell-phones-electronics/-/N-5xte8",
"parent_id": "5xtg6",
"parent_name": "Electronics",
"type": "standard",
"domain": "target.com"
},
{
"id": "5xtfc",
"name": "Computers & Office",
"has_children": true,
"is_root": false,
"path": "Electronics > Computers & Office",
"link": "https://www.target.com/c/computers-office-electronics/-/N-5xtfc",
"parent_id": "5xtg6",
"parent_name": "Electronics",
"type": "standard",
"domain": "target.com"
},
{
"id": "5xte2",
"name": "Speakers & Audio Systems",
"has_children": true,
"is_root": false,
"path": "Electronics > Speakers & Audio Systems",
"link": "https://www.target.com/c/speakers-audio-systems-electronics/-/N-5xte2",
"parent_id": "5xtg6",
"parent_name": "Electronics",
"type": "standard",
"domain": "target.com"
},
{
"id": "551ss",
"name": "Wearable Technology",
"has_children": true,
"is_root": false,
"path": "Electronics > Wearable Technology",
"link": "https://www.target.com/c/wearable-technology-electronics/-/N-551ss",
"parent_id": "5xtg6",
"parent_name": "Electronics",
"type": "standard",
"domain": "target.com"
},
{
"id": "5xteg",
"name": "Headphones",
"has_children": true,
"is_root": false,
"path": "Electronics > Headphones",
"link": "https://www.target.com/c/headphones-electronics/-/N-5xteg",
"parent_id": "5xtg6",
"parent_name": "Electronics",
"type": "standard",
"domain": "target.com"
}
]
}
```
***
**Next Steps**
[Categories API Overview](https://docs.trajectdata.com/redcircleapi/categories-api/overview)