List and Search

8min

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 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:
Curl
Node.js
Python
PHP
$ curl "https://api.bigboxapi.com/categories?api_key=demo"
$ curl "https://api.bigboxapi.com/categories?api_key=demo"
﻿
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"
    }
  ]
}
{
  "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 :
Curl
Node.js
Python
PHP
$ curl "https://api.bigboxapi.com/categories?api_key=demo&parent_id=N-5yc1vZbv1w"
$ curl "https://api.bigboxapi.com/categories?api_key=demo&parent_id=N-5yc1vZbv1w"
﻿
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"
    }
  ]
}
{
  "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﻿

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.

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 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).

Updated 07 Aug 2024

Did this page help you?

Overview