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
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 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.backyardapi.com/categories?api_key=demo"
$ curl "https://api.backyardapi.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.backyardapi.com/categories?api_key=demo&parent_id=N-5yc1vZbv1w"
$ curl "https://api.backyardapi.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	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.

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 08 Aug 2024

Did this page help you?

Overview