Core APIs
Categories API

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


The Categories API responds with the top-level (root) categories in the categories property.

JSON



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


The Categories API responds with the child categories for parent category with ID N-5yc1vZbv1w in the categories property.

JSON



Next Steps      Categories API Overview

Updated 07 Aug 2024
Did this page help you?