--- title: List and Search slug: bigboxapi/categories-api/list-and-search docTags: createdAt: 2024-07-22T08:01:06.003Z --- # 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`*
| 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/bigboxapi/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 "https://api.bigboxapi.com/categories?api_key=demo" ``` ```nodejs const axios = require('axios'); axios.get('https://api.bigboxapi.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.bigboxapi.com/categories', { params }) api_response = api_result.json() print "Categories: ", json.dumps(api_response) ``` ```php 'demo' ]); $ch = curl_init('https://api.bigboxapi.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": "N-5yc1vZbv1w", "name": "Appliances", "has_children": true, "is_root": true, "path": "Appliances", "link": "https://www.homedepot.com/b/Appliances/N-5yc1vZbv1w", "type": "standard", "domain": "homedepot.com" }, { "id": "N-5yc1vZbqsi", "name": "Cleaning", "has_children": true, "is_root": true, "path": "Cleaning", "link": "https://www.homedepot.com/b/Cleaning/N-5yc1vZbqsi", "type": "standard", "domain": "homedepot.com" }, { "id": "N-5yc1vZc1jw", "name": "Smart Home", "has_children": true, "is_root": true, "path": "Smart Home", "link": "https://www.homedepot.com/b/Smart-Home/N-5yc1vZc1jw", "type": "standard", "domain": "homedepot.com" } ] } ``` *** ### Example - Listing Child Categories In the example below we retrieve child categories for a parent category with ID `N-5yc1vZbv1w` : :::CodeblockTabs ```curl $ curl "https://api.bigboxapi.com/categories?api_key=demo&parent_id=N-5yc1vZbv1w" ``` ```nodejs const axios = require('axios'); axios.get('https://api.bigboxapi.com/categories?api_key=demo&parent_id=N-5yc1vZbv1w') .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': 'N-5yc1vZbv1w' } api_result = requests.get('https://api.bigboxapi.com/categories', { params }) api_response = api_result.json() print "Categories: ", json.dumps(api_response) ``` ```php 'demo', 'parent_id' => 'N-5yc1vZbv1w' ]); $ch = curl_init('https://api.bigboxapi.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 `N-5yc1vZbv1w` in the `categories` property. ```json { "request_info": { "success": true }, "current_category": { "id": "N-5yc1vZbv1w", "name": "Appliances", "has_children": true, "is_root": true, "path": "Appliances", "link": "https://www.homedepot.com/b/Appliances/N-5yc1vZbv1w", "type": "standard", "domain": "homedepot.com" }, "categories": [ { "id": "N-5yc1vZc3pi", "name": "Refrigerators", "has_children": false, "is_root": false, "path": "Appliances > Refrigerators", "link": "https://www.homedepot.com/b/Appliances-Refrigerators/N-5yc1vZc3pi", "parent_id": "N-5yc1vZbv1w", "parent_name": "Appliances", "type": "standard", "domain": "homedepot.com" }, { "id": "N-5yc1vZc3po", "name": "Dishwashers", "has_children": false, "is_root": false, "path": "Appliances > Dishwashers", "link": "https://www.homedepot.com/b/Appliances-Dishwashers/N-5yc1vZc3po", "parent_id": "N-5yc1vZbv1w", "parent_name": "Appliances", "type": "standard", "domain": "homedepot.com" }, { "id": "N-5yc1vZc3no", "name": "Garbage Disposals", "has_children": false, "is_root": false, "path": "Appliances > Garbage Disposals", "link": "https://www.homedepot.com/b/Appliances-Garbage-Disposals/N-5yc1vZc3no", "parent_id": "N-5yc1vZbv1w", "parent_name": "Appliances", "type": "standard", "domain": "homedepot.com" } ] } ``` *** **Next Steps**      [Categories API Overview](https://docs.trajectdata.com/bigboxapi/categories-api/overview)