Core API
...
Product Data API
Parameters

Category

3min

Category Parameters

GET /request

The Category Parameters are applicable when making a request with type=category to retrieve category results for an Amazon category. Categories can be specified either via passing an Amazon category URL in to the url parameter, or by passing a Category ID in the category_id and an Amazon domain in the amazon_domain parameter. The parameters should be appended as querystring parameters to the Product Data API GET HTTP request.

Category results are retrieved from the category listing page on Amazon.

Category Listing Page
Category Listing Page


For example, to request category results for the category ID 1069664 , on amazon.com , the request would be:

HTTP
Curl
Node.js
Python
PHP



Category Parameters

The following parameters are available for all requests made when type=category .

Parameter

Required

Description

category_id

optional

A category ID to retrieve results from. You may supply any arbitary value in the category_id parameter.

ASIN Data API will use the category_id in the following form: https:// amazon_domain /s?node= category_id .

Note that pagination for top-level categories is not supported by the Amazon sites. If you wish to iterate the contents of a category the recommended approach is to pick the lowest level categories to perform your iteration / pagination on.

amazon_domain

optional

The Amazon domain to retrieve category results from. For a full list of supported Amazon domains see Supported Amazon Domains .

url

optional

The Amazon category results page URL to retrieve category results from. Be sure to URL-encode the url parameter.

Note the url parameter is supplied, the category_id parameter cannot be used (as the url itself defines the category ID used).

sort_by

optional

Determines the sort order of category results to return. Valid values are:

  1. most_recent
  2. Sort category results by newest arrivals.



  1. price_low_to_high
  2. Sort category results by lowest to highest price.



  1. price_high_to_low
  2. Sort category results by highest to lowest price.



  1. featured
  2. Sort category results by featured first.



  1. average_review
  2. Sort category results by average customer review.
  • 

    Document image
    

page

optional

The current page of category results to retrieve. Inspect the pagination.total_pages property in the Category results to see how many pages of category results are available.

max_page

optional

Use the max_page parameter to get multiple pages of results in one request. The API will automatically paginate through pages and concatenate the results into one response.

See the Pagination docs for more information.

refinements

optional

A comma-seperated list of refinement values to filter the category results by. These allow you to refine your category results by values such as "Reviews rating 4 and over", "price range" and "brand".

Refinement values are returned in the refinements array of each type=category result. Refinement values are dynamic and change by category area or search term used. If you wish to use refinements you should first issue a type=category request without specifying any refinements to retrieve a master list of the avaialble refinements for the given category area/search term. You can then cache these refinement values for use on subsequent requests.

For example, to run a type=search request specifying two refinements with values p_85/2470955011 and p_36/2421886011 the value of the refinements parameter would be refinements=p_85/2470955011,p_36/2421886011

Note that sometimes Amazon do not present a explicit refinement value and instead a link is returned. In this instance you should pass the link into the url request parameter of your type=category request to retrieve data from that refinement-filtered page.

  • 

    Document image
    


Next Steps      Category Results

Updated 11 Aug 2024
Did this page help you?