Search Response

The result object contains the ranked product listings of the search page, the filters Amazon offers for the search, related searches and the delivery location. Every response uses the shared response envelope (request_info, request_parameters, request_metadata, result).

Response structure

result
├── search_results[]
│   ├── position, asin, title, brand, link, image
│   ├── product_type, is_sponsored, is_prime, source_page
│   ├── rating, rating_text, ratings_total
│   ├── price            symbol, value, currency, raw
│   ├── prices[]         same fields as price, plus is_rrp
│   ├── bought_activity  raw, value, period, symbol
│   ├── color_options    raw, additional_count, total_count
│   ├── more_buying_choices  raw, min_offers_count, link, price
│   └── shipping_details
├── refinements
│   ├── customer_reviews[], eligible_for_free_shipping[], delivery_day[]
│   ├── brands[], price[], deals_discounts[], condition[], seller[]
│   ├── department[], color[], grade[], premium_brands[]
│   └── moresustainable_products[], subscription_options[]
├── related_searches[]    query, link
└── delivered_to

Not every listing has every field (for example bought_activity or more_buying_choices), so check that a field exists before you read it.

Result fields

result

Field	Type	Description
search_results	array	Products on the requested pages, in ranking order.
refinements	object	Filter groups shown in the Amazon search sidebar. Each key is one filter group.
related_searches	array	Related search suggestions that Amazon shows for the query.
delivered_to	string	Delivery location Amazon used for the results, for example "Wilmington 19805".

search_results[]

Field	Type	Description
position	integer	Rank of the item in the results list.
asin	string	ASIN of the product.
title	string	Product title.
brand	string	Brand name.
link	string	Link to the product page, usually a relative path. Prefix a relative path with the marketplace host, for example https://www.amazon.com.
image	string	Image ID of the thumbnail, not a full URL.
product_type	string	Product type of the listing.
is_sponsored	boolean	true when the item is a sponsored (ad) listing.
is_prime	boolean	true when the product is Prime eligible.
source_page	integer	Results page the item came from. Useful when you fetch several pages.
rating	string	Average rating as a numeric string, for example "4.6".
rating_text	string	Rating as displayed, for example "4.6 out of 5 stars".
ratings_total	integer	Total number of customer ratings.
price	object	Current price. Fields are listed below.
prices	array	All prices shown for the item, such as the current price and the list price.
bought_activity	object	Recent purchase activity.
color_options	object	Color variants of the product.
more_buying_choices	object	Other offers for the same product.
shipping_details	string	Delivery text shown on the listing, such as free or paid delivery and the estimated arrival date.

search_results[].price and prices[]

price and each item in prices use the same fields.

Field	Type	Description
symbol	string	Currency symbol, for example $.
value	string	Amount as a numeric string, for example "34.40".
currency	string	Currency code, for example USD.
raw	string	Price as displayed, for example $34.40.
is_rrp	boolean	In prices only: true when the entry is the list price (recommended retail price).

search_results[].bought_activity

Field	Type	Description
raw	string	Text as displayed, for example "2K+ bought in past month".
value	integer	Estimated number of units bought.
period	string	Period the count covers, for example "past month".
symbol	string	Abbreviation used in raw, for example K or M.

search_results[].color_options

Field	Type	Description
raw	string	Variant count as displayed, for example "+32".
additional_count	integer	Number of additional color variants.
total_count	integer	Total number of color variants.

search_results[].more_buying_choices

Field	Type	Description
raw	string	Text as displayed, for example "$25.82 (6+...)".
min_offers_count	integer	Minimum number of other offers.
link	string	Link to the offer listing page.
price	object	Lowest price among the other offers, with the same fields as price.

refinements.<group>[]

Each filter group is an array of filter options. Every option has these fields (the price group differs, see below).

Field	Type	Description
heading_id	string	ID of the filter element.
name	string	Option label, for example "4 Stars & Up" or a brand name.
value	string	Amazon filter value, for example p_123:315576. Send it in the refinements request parameter to apply the filter.
link	string	Link to the Amazon search with the filter applied.
refinement_display_name	string	Name of the filter group as displayed, for example "Brands".

Filter groups:

Group	refinement_display_name	Filters by
customer_reviews	Customer Reviews	Average customer rating
eligible_for_free_shipping	Eligible for Free Shipping	Free shipping by Amazon
delivery_day	Delivery Day	Delivery speed, for example "Get It by Tomorrow"
brands	Brands	Brand
price	Price	Price range (different fields, see below)
deals_discounts	Deals & Discounts	Active deals, for example "Today's Deals"
condition	Condition	Item condition, for example New or Used
seller	Seller	Seller, for example Amazon.com or a third-party seller
department	Department	Amazon category (browse node)
color	Color	Product color
grade	Grade	Usage grade, for example "Commercial Grade"
premium_brands	Premium Brands	Premium brands
moresustainable_products	More-sustainable Products	Sustainability programs, for example "Climate Pledge Friendly"
subscription_options	Subscription Options	Subscription programs, for example "Subscribe & Save"

Amazon only returns the groups that apply to the search, so the set of keys varies from query to query.

refinements.price[]

Field	Type	Description
heading_id	string	ID of the filter element.
name	string	Option label, usually "Price".
range	string	Price range as displayed, for example "$0–$1,900+".
min_value	string	Lowest price of the range as displayed, for example "$0".
max_value	string	Highest price of the range as displayed, for example "$1,900+".
refinement_display_name	string	Always "Price".

related_searches[]

Field	Type	Description
query	string	Suggested search term, for example "car accessories".
link	string	Relative Amazon path of the suggested search.

Sample response

This sample shows the response envelope with pagination details; the result object is omitted.

Sample response (SEARCH, .com): envelope only

{
  "request_info": {
    "id": "a12b3456-caed-491b-8a91-d5ff517d63dc",
    "success": true,
    "status_code": 200,
    "error_details": [],
    "credits_used": 759040,
    "credit_used_this_request": 1,
    "credits_remaining": 759050,
    "credits_reset_at": "2035-01-30T00:00:00.000Z",
    "address": {
      "city": null,
      "district": null,
      "country_code": null,
      "zipCode": [
        "19805"
      ]
    }
  },
  "request_parameters": {
    "output": "json",
    "language": "en_US",
    "include_html": false,
    "keyword": "winter",
    "type": "SEARCH"
  },
  "request_metadata": {
    "created_at": "2025-05-27T13:15:00.496Z",
    "processed_at": "2025-05-27T13:15:03.561Z",
    "total_time_taken": 3.065,
    "end_of_pagination": 7,
    "pages": [
      {
        "current_page": 1,
        "current_page_link": "/s?k=winter&language=en_US&xpid=GUHHVwhvUwDys&qid=1748351701",
        "result_count": 60,
        "next_page_link": "/s?k=winter&page=2&language=en_US&xpid=GUHHVwhvUwDys&qid=1748351701&ref=sr_pg_1",
        "not_match": [
          "related_searches"
        ],
        "ms": 2790
      }
    ]
  }
}

Notes

Pagination details

The Search operation returns its paging details in result.pagination and result.result_information, both arrays with one object per fetched page. The envelope's request_metadata can also carry end_of_pagination and pages[] with per-page timing, as in the sample above.

Fields in result:

Field	Type	Description
pagination[].current_page	integer	Page number.
pagination[].current_page_link	string	Query string of the page.
pagination[].next_page_link	string	Relative Amazon path of the next page, when there is one.
pagination[].last_visible_page	integer	Highest page number shown in Amazon's page navigation.
pagination[].result_count	integer	Number of results on the page.
pagination[].not_match	array	Names of expected page elements that were not found, for example amazon_no_results_text.
result_information[].begin	integer	Position of the first result on the page.
result_information[].end	integer	Position of the last result on the page.
result_information[].total_product_count	integer	Total number of results Amazon reports for the search.
result_information[].raw	string	Result count as displayed, for example "1-16 of over 100,000 results for 'car'".
result_information[].search_term	string	Search term the results belong to.

Fields in request_metadata, when present:

Field	Type	Description
end_of_pagination	integer	Last results page available for the search.
pages	array	One entry per page fetched.
pages[].current_page	integer	Page number.
pages[].current_page_link	string	Relative Amazon path of the page.
pages[].result_count	integer	Number of results on the page.
pages[].next_page_link	string	Relative Amazon path of the next page, when there is one.
pages[].not_match	array	Names of expected fields that were not found on the page, for example related_searches.
pages[].ms	integer	Time spent fetching the page, in milliseconds.

In Data Service results, pagination and result_information can be single objects with the same fields.

Errors

• Search-specific error messages: MSG1019 ("Invalid Search Term"), MSG1011 ("Invalid url") and MSG1010 ("Maximum page count must be more than minimum page count").
• Always check request_info.success and request_info.error_details, even when the HTTP status is 200. On failure, result is an empty object. See Errors and status codes for the general list.