Core APIs
...
Results
Core Requests

Search

2min

Search Results

When making a request with the type parameter set to type=search Rainforest API will return search results from the Amazon domain specified in the amazon_domain parameter.

Search results are retrieved from the search results page on Amazon.

Search Results Page
Search Results Page


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

JSON


Rainforest API returns the following properties for Search requests:

Property

Type

Description

search_results

array

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

  • position
  • number
  • The position of the result on the search results page.



  • title
  • string
  • The product name.



  • brand
  • string
  • The product brand (where shown, note that not all search results page layouts break out the brand separately to the title).



  • 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.

    • 

      Document image
      



  • kindle_unlimited
  • boolean
  • Boolean set to true when the "Kindle Unlimited" badge was shown next to the search result.



  • prime_video
  • boolean
  • Determines whether the product is a Amazon Prime Video product, or not.

    • 

      Document image
      



  • is_amazon_brand
  • boolean
  • Set to true when the "Amazon Brand" banner is shown next to the search result.

    • 

      Document image
      



  • is_exclusive_to_amazon
  • boolean
  • Set to true when the "Exclusive to Amazon" banner is shown next to the search result.

    • 

      Document image
      



  • is_small_business
  • boolean
  • Set to true when the "Small Business" banner is shown next to the search result.

    • 

      Document image
      



  • is_amazon_fresh
  • boolean
  • Determines whether the product is an Amazon Fresh product, or not.

    • 

      Document image
      



  • is_whole_foods_market
  • boolean
  • Determines whether the product is a Whole Foods Market product, or not.

    • 

      Document image
      



  • coupon
  • object
  • Coupon Object Present when the "Coupon" badge is shown next to the search result. Contains the following properties:

    • 

      Document image
      
    • 
      1. badge_text
      2. string
      3. The text shown inside the coupon badge (i.e. "Save 5%").
    • 
      1. text
      2. string
      3. The text shown next to the coupon badge (i.e. "with coupon").



  • deal
  • object
  • Deal Object Present when the "Deal" badge is shown next to the search result. Contains the following properties:

    • 

      Document image
      
    • 
      1. link
      2. string
      3. A link to the deal landing page.
    • 
      1. text
      2. string
      3. The text shown next to the deal badge (i.e. "Limited time deal").
    • 
      1. badge_text
      2. string
      3. The text shown inside the deal badge (i.e. "16% off").



  • climate_pledge_friendly
  • object
  • Climate Pledge Friendly Object Present when the "Climate Pledge Friendly" badge is shown next to the search result. Contains the following properties:

    • 

      Document image
      
    • 
      1. link
      2. string
      3. A link to the product landing page showing more detail on the Climate Pledge Friendly messaging.
    • 
      1. text
      2. string
      3. The text of the Climate Pledge Friendly certification.
    • 
      1. image
      2. string
      3. An image URL to the logo of the Climate Pledge Friendly certification logo, if shown.



  • gift_guide
  • object
  • Gift Guide Object Present when the "Gift Guide" badge is shown next to the search result. Contains the following properties:

    • 

      Document image
      
    • 
      1. link
      2. string
      3. A link to the deal landing page.
    • 
      1. badge_text
      2. string
      3. The text shown inside the gift guide badge (i.e. "Holiday gift guide"). Can be useful in determining the "type" of gift guide the search result appears in.



  • amazons_choice
  • object
  • Amazons Choice Object Present when the "Amazon's Choice" badge is shown next to the search result. Contains the following properties:

    • 

      Document image
      
    • 
      1. link
      2. string
      3. A link to the product.
    • 
      1. keywords
      2. string
      3. The keywords for which this search result is "Amazon's Choice".



  • bestseller
  • object
  • BestSeller Object Present when the "BestSeller" badge is shown next to the search result. More detailed bestseller information can be retrieved from the product page by making a type=product request specifying this search results ASIN. Contains the following properties:

    • 

      Document image
      
    • 
      1. link
      2. string
      3. A link to the Bestsellers page to which this bestseller badge relates.
    • 
      1. category
      2. string
      3. The category name for which this product is a best seller, i.e. "USB Cables".



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



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



  • featured_from_our_brands
  • boolean
  • Set to true when the product is flagged as "Featured from our Brands", omitted otherwise.

    • 

      Document image
      



  • authors
  • array
  • Authors Array The authors property contains the authors or artists of the product. Mainly applies to books, music and video products. The author object has the following properties:
    • 
      1. name
      2. string
      3. The name of the author or artist.
    • 
      1. link
      2. string
      3. The link to the author or artist on the Amazon domain, if present.



  • narrated_by
  • array
  • Narrated-By Array The narrated-by property contains the narrators of the product. Only applies for Audible Amazon Domains . The narrated-by object has the following properties:
    • 
      1. name
      2. string
      3. The name of the narrator.
    • 
      1. link
      2. string
      3. The link to the narrator on the Audible Amazon domain, if present.



  • runtime
  • object
  • Runtime Object The runtime object contains runtime of the podcast. Only applies for Audible Amazon Domains . The runtime object has the following properties:
    • 
      1. raw
      2. string
      3. The raw runtime as shown on the Audible domain.



  • 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.



  • availability
  • object
  • Availability Object The Availability object is present when Amazon show availability (i.e. stock level) data next to the search reult. The availability property will be omitted if availability information is not shown alongside the search result. The availability object contains the following properties:
    • 
      1. raw
      2. string
      3. The raw availability as shown next to the search result, for example "Only 1 left in stock - order soon".



  • 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").



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



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



  • delivery
  • object
  • Delivery Object The Delivery object is present when Amazon show delivery information neat to the search result. The delivery object contains the following properties:
    • 
      1. tagline
      2. string
      3. A string containing the tagline associated with the delivery option, for example "Get it as soon as Sat, Oct 3".
    • 
      1. price
      2. object
      3. A price object representing the price and currency of the delivery option. The delivery price object has the same properties as the price objects in the prices array



  • is_carousel
  • boolean
  • Set to true when this search result is part of a carousel. It is not present if the search result is not part of a carousel. If is_carousel=true then the carousel property describes the properties of the carousel this search result if part of.



  • carousel
  • object
  • Carousel Object When a search result is part of a "carousel" (a horizontally scrolling row of search results nested within the main search results) then the carousel object is present. The carousel object contains details of the carousel that this search result is part of. Examples of carousels could be "Highly Rated" or "Today's Deals". The carousel object contains the following properties:

    • 

      Document image
      
    • 
      1. title
      2. string
      3. The title of the carousel that this search result is part of, for example "Highly Rated".
    • 
      1. sub_title
      2. string
      3. The subtitle of the carousel that this search result is part of, for example "Based on star rating and number of customer ratings".
    • 
      1. sponsored
      2. boolean
      3. Set to true when the carousel itself (as-shown in the carousel header section) indicates that the contents of the carousel are all sponsored results.
    • 
      1. id
      2. boolean
      3. The ID of the carousel that this search result is part of.
    • 
      1. total_items
      2. boolean
      3. The total number of items in the carousel that this search result is part of.



  • 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".
    • 
      1. list_price
      2. string
      3. The product's list price.



  • 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.



  • information
  • string
  • The information text, typically shown in bold below the product title and showing the pack quantity. For example 25.4 Fl Oz (Pack of 2) .



  • unit_price
  • string
  • The product unit price, where shown. For example $0.57/Fl Oz .



  • other_formats
  • string
  • An array of objects containing asin , link and title properties showing the 'other format' links shown next to the search result. Typically found on books or music categories. .

    • 

      Document image
      



  • recent_sales
  • string
  • The product recent sales, where shown. For example 200+ bought in past week .



  • recent_views
  • string
  • The product recent views, where shown. For example 300+ viewed in past week .

search_information

object

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

  • spelling_correction
  • string
  • Populated with the spelling correction shown when a misspelled search_term is provided.

    • 

      Document image
      
    • Note you can control whether the spelling correction is automatically followed by using the direct_search=true request parameter.



  • original_search_term
  • string
  • Populated with the spelling correction shown when a misspelled search_term is provided.



  • did_you_mean
  • string
  • Populated with the "did you mean" spelling correction shown when a misspelled search_term is provided and the direct_search=true request parameter is set.

    • 

      Document image
      



  • no_results_found
  • boolean
  • Set to true when the "no results found, showing results from all departments" banner is shown at the top of the search result page.

    • 

      Document image
      

related_searches

array

An array of "related_search" objects detailing the related searches shown at the bottom of the search results page.

  • 

    Document image
    



  • link
  • string
  • The link to the related search results.



  • query
  • string
  • The query text of the related search. Could be used in a future type=search request to retrieve the related search results.

related_brands

array

An array of "related_brand" objects detailing the sponsored related brands shown at the bottom of the search results page.

  • 

    Document image
    



  • logo
  • string
  • A link to the brand logo image of the related brand, if shown.



  • image
  • string
  • A link to the product image shown in the related brand, if shown.



  • title
  • string
  • The title text of the related brand.



  • link
  • string
  • The link shown in the related brand section.



  • store_name
  • string
  • The name of the store of the related brand (if shown).



  • store_id
  • string
  • The ID of the store of the related brand (if shown). Can be used in the store_id parameter of subsequent a Store request to retrieve listings from the store.



  • store_link
  • string
  • A link to the store of the related brand (if shown).

pagination

object

An object containing details of the current search results page and the total number of pages that are available. To paginate you should specify the page number in your request's page parameter .

  • total_results
  • number
  • The total number of results Amazon show in the header bar. Note that it will not normally be possible to paginate through to very high page numbers however total_results is useful as an indication of market size.



  • current_page
  • number
  • The current page number.



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

refinements

object

An object containing details of the available refinements for the given search results. These allow you to refine your search by values such as "Reviews rating 4 and over", "price range" and "brand". To refine your search 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 or search term used. If you wish to use refinements you should first issue a type=search 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.

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 .

  • 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=search request's url parameter to navigate to the search results filtered by this refinement.

shopping_advisors

array

An array of "shopping advisor" objects detailing the shopping advisor sections shown inline in the search results page. These can have headings such as "Editorial recommendations" or "Highly rated and well-priced products". The typically contain editorial content along with a selection of recommended products.

  • 

    Document image
    



  • position
  • number
  • The position of the shopping advisor within the search results. For example, position=5 indicates the shopping advisor was shown after the product at position=4 in the search_results array.



  • title
  • number
  • The title of the shopping advisor section.



  • profile
  • object
  • Profile Object The profile object contains details about the person or organisation who is the author or content-provider for the Shopping Advisor's Amazon profile:
    • 
      1. name
      2. string
      3. The profile name of the author.
    • 
      1. link
      2. string
      3. A link to the Amazon profile for the author.
    • 
      1. id
      2. string
      3. The Amazon profile ID of the author or content-provider.



  • article
  • object
  • Article Object The article object is present when the author of content-provider has provided editorial or article content to accompany the Shopping Advisor section.
    • 
      1. title
      2. string
      3. The title of the article.
    • 
      1. body
      2. string
      3. The body text of the article.
    • 
      1. link
      2. string
      3. A link to the article.
    • 
      1. date
      2. string
      3. A text representation of the publication date of the article.
    • 
      1. total
      2. number
      3. The total number of product recommendations shown in this Shopping Advisor.



  • recommendations
  • object
  • Recommendations Array The recommendations array contains a list of recommended products shown in the Shopping Advisor.
    • 
      1. position
      2. number
      3. The position of the recommended product in the Shopping Advisor.
    • 
      1. title
      2. string
      3. The title as-provided by the author or content-provider as to why this product is recommended, i.e. "Good Value".
    • 
      1. sub_title
      2. string
      3. The subtitle of the recommendation, i.e. "Durable Design".
    • 
      1. body
      2. string
      3. The body text of the recommendation.
    • 
      1. product
      2. object
      3. An object representing the recommended product. It has the same properties as objects in the main search_results array (i.e. title , asin , link , image , price , is_prime , rating and ratings_total

ad_blocks

array

An array of "ad block" objects detailing the sponsored ad blocks shown above or inline on the search results page. Typically ad blocks contain detail about the creative (the ad launch date, title) along with a link to the target Ad page and a selection of ASIN details.

  • 

    Document image
    



  • creative_id
  • string
  • The ID of the creative shown in the Ad Block.



  • campaign_id
  • string
  • The ID of the campaign the ads in the Ad Block belong to (if shown).



  • advertiser_id
  • string
  • The advertiser ID of the advertiser the video block belongs to (if shown).



  • ad_id
  • string
  • The ID of the Ad Block.



  • brand_logo
  • string
  • A link to the brand logo image of the Ad Block, if shown.



  • background_image
  • string
  • A link to the background image of the Ad Block, if shown.



  • creative_type
  • string
  • The name of the type of creative used in the Ad Block.



  • link
  • number
  • The link the user is redirected to when clicking the Ad Block.



  • title
  • number
  • The title of the Ad Block, if shown.



  • sub_title
  • number
  • The subtitle of the Ad Block, if shown.



  • store_name
  • string
  • The name of the store of the advertiser the Ad Block belongs to (if shown).



  • store_id
  • string
  • The ID of the store of the advertiser the Ad Block belongs to (if shown). Can be used in the store_id parameter of subsequent a Store request to retrieve listings from the store.



  • store_link
  • string
  • A link to the store of the advertiser the Ad Block belongs to (if shown).



  • date
  • object
  • Date Object The date object contains details about the date the Ad Block was launched (if shown). It contains the following properties
    • 
      1. raw
      2. number
      3. The raw date, expressed as an Unix EPOCH.
    • 
      1. utc
      2. string
      3. The date, parsed from the raw date, in ISO 8601 format. If Rainforest API cannot parse the raw date then this property will be null.



  • products
  • array
  • Products Array The products array contains an array of objects containing details of products shown in the Ad Block:
    • 
      1. asin
      2. string
      3. The ASIN of the product shown in the Ad Block.
    • 
      1. link
      2. string
      3. The product page link of the product shown in the Ad Block.
    • 
      1. image
      2. string
      3. A link to the image for the product shown in the Ad Block.
    • 
      1. title
      2. string
      3. A title of the product shown in the Ad Block.
    • 
      1. price
      2. object
      3. A price object describing the price of the product shown in the Ad Block, if shown.
    • 
      1. is_prime
      2. boolean
      3. Set to true if the Amazon Prime indicator is shown next to the product in the Ad Block.
    • 
      1. rating
      2. number
      3. The rating of the product shown in the Ad Block, out of 5.
    • 
      1. rating_total
      2. number
      3. The total number of ratings the product shown in the Ad Block has received.

video_blocks

array

An array of "video block" objects detailing the full-row sponsored video sections shown on the search results page. Typically video blocks contain a video, along with a link to one or more products related to the video.

  • 

    Document image
    



  • video_link
  • string
  • A link to the video (typically a MP4 file) that plays in the video block.



  • thumbnail_link
  • string
  • A link to the thumbnail image that is shown before the video starts playing (typically while the video is buffering).



  • campaign_id
  • string
  • The campaign ID the video block belongs to.



  • advertiser_id
  • string
  • The advertiser ID of the advertiser the video block belongs to.



  • has_audio
  • boolean
  • Set to true if the video includes audio.



  • store_name
  • string
  • The name of the store of the advertiser the video block belongs to (if shown).



  • store_id
  • string
  • The ID of the store of the advertiser the video block belongs to (if shown). Can be used in the store_id parameter of subsequent a Store request to retrieve listings from the store.



  • store_link
  • string
  • A link to the store of the advertiser the video block belongs to (if shown).



  • products
  • array
  • Products Array The products array contains an array of objects containing details of products shown in the Video Block:
    • 
      1. asin
      2. string
      3. The ASIN of the product shown in the Video Block.
    • 
      1. link
      2. string
      3. The product page link of the product shown in the Video Block.
    • 
      1. is_prime
      2. boolean
      3. Set to true if the Amazon Prime indicator is shown next to the product in the Video Block.
    • 
      1. image
      2. string
      3. A link to the image for the product shown in the Video Block.
    • 
      1. title
      2. string
      3. A title of the product shown in the Video Block.
    • 
      1. rating
      2. number
      3. The rating of the product shown in the Video Block, out of 5.
    • 
      1. rating_total
      2. number
      3. The total number of ratings the product shown in the Video Block has received.
    • 
      1. price
      2. object
      3. A price object describing the price of the product shown in the Video Block, if shown.


Next Steps      Search Parameters

Updated 23 Oct 2024
Did this page help you?
PREVIOUS
Product
NEXT
Category
Docs powered by Archbee