List and Search

8min

List and Search Categories
﻿GET  /categories
The Categories API exposes just one endpoint  /categories . You can use this endpoint to list or search for categories on a given Amazon  domain .
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.
domain
required
Filters the Categories returned to only those from the Amazon Domain i.e. domain=amazon.de .
type
optional
Determines the type of Category to search for.  
Valid values are:  standard - for regular Amazon categories compatible with the category_id parameter on type=search or type=category requests. 
 bestsellers , gift_ideas , most_wished_for , movers_and_shakers or new_releases - for Bestseller Amazon categories compatible with the category_id parameter on type=bestseller requests. 
deals - for Deals Amazon categories compatible with the category_id parameter on type=deals requests.  
Defaults to standard when the type parameter is not specified.
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.
domain
string
The Amazon Domain the category belongs to.
﻿
id
string
The ID of the category. Can be passed into the category_id parameter of a subsequent category , search , deals or bestsellers 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
﻿
type
string
The type of category - either standard , bestsellers , gift_ideas , most_wished_for , movers_and_shakers , new_releases or deals .
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 for the  amazon.com  domain:
Curl
Node.js
Python
PHP
curl -L --get https://api.rainforestapi.com/categories \
  -d api_key="demo" \
  -d domain="amazon.com"
curl -L --get https://api.rainforestapi.com/categories \
  -d api_key="demo" \
  -d domain="amazon.com"
﻿
The Categories API responds with the top-level (root) categories for  amazon.com  in the  categories  property.
JSON
{
  "request_info": {
    "success": true,
    "credits_used": 1,
    "credits_remaining": 999,
    "credits_used_this_request": 1,
    "credits_reset_at": "2020-01-01T00:00:00.000Z"
  },
  "categories": [
    {
      "domain": "amazon.com",
      "id": "2619526011",
      "name": "Appliances",
      "has_children": true,
      "is_root": true,
      "path": "Appliances"
    },
    {
      "domain": "amazon.com",
      "id": "2617942011",
      "name": "Arts, Crafts & Sewing",
      "has_children": true,
      "is_root": true,
      "path": "Arts, Crafts & Sewing"
    }
  ]
}
{
  "request_info": {
    "success": true,
    "credits_used": 1,
    "credits_remaining": 999,
    "credits_used_this_request": 1,
    "credits_reset_at": "2020-01-01T00:00:00.000Z"
  },
  "categories": [
    {
      "domain": "amazon.com",
      "id": "2619526011",
      "name": "Appliances",
      "has_children": true,
      "is_root": true,
      "path": "Appliances"
    },
    {
      "domain": "amazon.com",
      "id": "2617942011",
      "name": "Arts, Crafts & Sewing",
      "has_children": true,
      "is_root": true,
      "path": "Arts, Crafts & Sewing"
    }
  ]
}
﻿
﻿
Example - Listing Child Categories
In the example below we retrieve child categories for a parent category with ID  2619526011  on  amazon.com :
Curl
Node.js
Python
PHP
curl -L --get https://api.rainforestapi.com/categories \
  -d api_key="demo" \
  -d parent_id="2619526011" \
  -d domain="amazon.com"
curl -L --get https://api.rainforestapi.com/categories \
  -d api_key="demo" \
  -d parent_id="2619526011" \
  -d domain="amazon.com"
﻿
The Categories API responds with the child categories for parent category with ID  2619526011  on  amazon.com  in the  categories  property.
JSON
{
  "request_info": {
    "success": true
  },
  "current_category": {
    "domain": "amazon.com",
    "id": "2619526011",
    "name": "Appliances",
    "has_children": true,
    "is_root": true,
    "path": "Appliances"
  },
  "categories": [
    {
      "domain": "amazon.com",
      "id": "17921061011",
      "name": "Refrigerators, Freezers & Ice Makers",
      "has_children": true,
      "is_root": false,
      "path": "Appliances > Refrigerators, Freezers & Ice Makers",
      "parent_id": "2619526011",
      "parent_name": "Appliances"
    },
    {
      "domain": "amazon.com",
      "id": "18116194011",
      "name": "Laundry Appliances",
      "has_children": true,
      "is_root": false,
      "path": "Appliances > Laundry Appliances",
      "parent_id": "2619526011",
      "parent_name": "Appliances"
    }
  ]
}
{
  "request_info": {
    "success": true
  },
  "current_category": {
    "domain": "amazon.com",
    "id": "2619526011",
    "name": "Appliances",
    "has_children": true,
    "is_root": true,
    "path": "Appliances"
  },
  "categories": [
    {
      "domain": "amazon.com",
      "id": "17921061011",
      "name": "Refrigerators, Freezers & Ice Makers",
      "has_children": true,
      "is_root": false,
      "path": "Appliances > Refrigerators, Freezers & Ice Makers",
      "parent_id": "2619526011",
      "parent_name": "Appliances"
    },
    {
      "domain": "amazon.com",
      "id": "18116194011",
      "name": "Laundry Appliances",
      "has_children": true,
      "is_root": false,
      "path": "Appliances > Laundry Appliances",
      "parent_id": "2619526011",
      "parent_name": "Appliances"
    }
  ]
}
﻿
﻿
Next Steps
     Categories API Overview﻿

Parameter	Required	Description
api_key	required	The API key for your account.
domain	required	Filters the Categories returned to only those from the Amazon Domain i.e. domain=amazon.de .
type	optional	Determines the type of Category to search for. Valid values are: standard - for regular Amazon categories compatible with the category_id parameter on type=search or type=category requests. bestsellers , gift_ideas , most_wished_for , movers_and_shakers or new_releases - for Bestseller Amazon categories compatible with the category_id parameter on type=bestseller requests. deals - for Deals Amazon categories compatible with the category_id parameter on type=deals requests. Defaults to standard when the type parameter is not specified.
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. domain string The Amazon Domain the category belongs to. id string The ID of the category. Can be passed into the category_id parameter of a subsequent category , search , deals or bestsellers 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 type string The type of category - either standard , bestsellers , gift_ideas , most_wished_for , movers_and_shakers , new_releases or deals .
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 11 Aug 2024

Did this page help you?

Overview