Core APIs
...
Results
Core Requests

Category

2min

Category Results

When making a request with the type parameter set to type=category Rainforest API will return category listing results from the URL specified in the url parameter or the Category ID specified in the category_id parameter (where the category_id is returned from the Categories API) and the Amazon domain in amazon_domain parameter.

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

Category Listing Page
Category Listing Page


An example of the JSON object returned from a Category request is shown below:

JSON


Rainforest API returns the following properties for Category requests:

Property

Type

Description

category_results

array

An array of Category Result objects, containing each of the product results shown on the category listing page. The Category Result object has the following properties:

  • position
  • number
  • The position of the result on the category listing page.



  • title
  • string
  • The product name.



  • asin
  • string
  • The Amazon product ID (ASIN) for the product.



  • link
  • string
  • The product page link.



  • is_prime
  • boolean
  • Determines whether the product is Prime-eligible or not.



  • image
  • string
  • A link to the image of the product.



  • sponsored
  • boolean
  • Set to true or false depending on whether the category result is a sponsored listing, or not.



  • add_on_item
  • object
  • Add-On Item Object The add-on item object is present when the item is part of the Amazon 'add-on item' program. The property will be omitted if the product is not an add-on item.
    • 
      1. is_add_on_item
      2. boolean
      3. True/false indicating whether the product is an add-on item.



  • categories
  • array
  • Categories Array An array containing details of the categories shown with this product as displayed next to the search bar at the top of the page. Each object in the array contains the following properties:
    • 
      1. name
      2. string
      3. The name of the category (i.e. "Toys & Games").



  • bestseller
  • object
  • Bestseller Object An object containing details of whether the product is a bestseller and if so, in which category. The bestseller object has the following properties:
    • 
      1. category
      2. string
      3. The name of the category (i.e. "Toys & Games") in which this product is a bestseller.



  • rating
  • number
  • The overall rating of the product, out of 5.



  • ratings_total
  • number
  • The total number of customer ratings the product has received.



  • prices
  • array
  • Prices Array The prices array contains details about the products pricing, as shown underneath the product title. It is an array of price objects, the properties of which are described below:
    • 
      1. symbol
      2. string
      3. The currency symbol, i.e. $ for USD.
    • 
      1. value
      2. number
      3. The price of the Offer.
    • 
      1. currency
      2. string
      3. The currency of the Offer as a ISO 4217 currency code.
    • 
      1. raw
      2. string
      3. The raw price as displayed on the Offer listing.
    • 
      1. name
      2. string
      3. The name of the price if applicable, for example "Kindle", "Hardcover".



  • price
  • object
  • A price object representing the first item in the prices array. This is normally the "main" price for the product and is included as a convienience to make extracting the main price easier.

category_list

array

An array of Category List objects. This property is populated when an "intermediate" category URL is specified in the requests' url parameter (see example ). "Intermediate" category URLs are category landing pages that typically show a branded list of sub-categories.

Note that the categories returned in category_list are retrieved from the category listing page itself, rather than via the Categories API .

The Category List object has the following properties:

  • title
  • string
  • The title of the sub-category linked-to from the intermediate category page.



  • link
  • string
  • A link to the sub-category from the intermediate category page. Could we passed to a subsequent type=category request via the url request parameter to retrieve category listings from that page.



  • image
  • string
  • The image of the sub-category from the intermediate category page, if shown.

refinements

object

An object containing details of the available refinements for the given category results. These allow you to refine your category by values such as "Reviews rating 4 and over", "price range" and "brand". To refine your category results by a given refinement value you should specify refinement values, comma seperated, in your request's refinements parameter .

Refinement values are dynamic and change by category area 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/category term. You can then cache these refinement values for use on subsequent requests.

The refinements object has a property name for each refinement that is available. This property contains an array showing the full-text refinement name and an value. It is this value that you should specify, comma seperated, in your request's refinements parameter .

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 a subsequent type=category request to retrieve data from that refinement-filtered page.

  • name
  • string
  • The full-text name of the refinement, for example "Brand".



  • value
  • string
  • The value of the refinement, you should specify the refinement value(s), comma seperated, in your request's refinements parameter .



  • link
  • string
  • The link shown for the refinement, you can use the link in a new type=category request's url parameter to navigate to the category results filtered by this refinement.

category_information

object

An object containing details of the current page of category results.

  • is_landing_page
  • boolean
  • Set to true when the current page is a category landing page (see example ). A category landing page is a higher level summary page. If you encounter one you should iterate to a lower level category, or use the refinements request parameter, to traverse down to a category listing page.

pagination

object

An object containing details of the current category listing page and the total number of pages that are available.

  • current_page
  • number
  • The current page number.



  • total_pages
  • number
  • The total number of pages available.


Next Steps      Category Parameters

Updated 11 Aug 2024
Did this page help you?
PREVIOUS
Search
NEXT
Offers
Docs powered by Archbee