Response

🌳API Response Structure Overview

Root ├── request_info # Meta info about the API request (timestamps, client info, vs.) ├── request_parameters # Parameters sent with the search query (keywords, filters, sort options) ├── request_metadata # Pagination, timing, and server processing details ├── result # Main response container │ ├── search_results[] # Array of product search results │ │ ├── product_id │ │ ├── title │ │ ├── price │ │ ├── rating │ │ ├── images │ │ └── ... # Other product-level fields │ └── refinements # Filter facets for the search (categories, brands, price, colors, etc.) │ ├── 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[] ├── delivered_to # User’s delivery location info (city, zip code)

📦 Top-Level Meta Fields (Outside of result)

These fields provide high-level metadata about the request, including tracking, billing, parameters used, and processing information.

📌request_info(object)

Contains information related to request execution, credit usage, and geo-location details.

Field	Type	Parent	Description
id	string (UUID)	request_info	Unique identifier for this request. Useful for logging and tracking.
success	boolean	request_info	Indicates if the request was successfully processed.
status_code	integer	request_info	Similar to HTTP status codes (e.g., 200, 400).
error_details	array of strings	request_info	List of any encountered error messages.
credits_used	integer	request_info	Total API credits used on the account to date.
credit_used_this_request	integer	request_info	Number of credits consumed by this specific request.
credits_remaining	integer	request_info	Available credits after this request.
credits_reset_at	string (datetime)	request_info	Timestamp when the credits will reset.
address.city	string/null	request_info > address	City of the requesting user, if available.
address.district	string/null	request_info > address	District information, if available.
address.country_code	string/null	request_info > address	ISO country code.
address.zipCode	array of strings	request_info > address	Zip/postal codes.

📌request_parameters (object)

Shows the input parameters that shaped this particular request.

Field	Type	Parent	Description
output	string	request_parameters	Requested response format (e.g., json).
language	string	request_parameters	Language preference for returned content.
include_html	boolean	request_parameters	Whether HTML formatting is included in result text.
keyword	string	request_parameters	Search keyword used in this request.
type	string	request_parameters	Request type, always "SEARCH" in this context.

📌request_metadata (object)

Provides details about how the request was handled, including timing and pagination state.

Field	Type	Parent	Description
created_at	string (datetime)	request_metadata	Time when the request was initiated.
processed_at	string (datetime)	request_metadata	Time when processing of the request completed.
total_time_taken	float (seconds)	request_metadata	Time (in seconds) taken to process the full request.
end_of_pagination	integer	request_metadata	Final page number available for pagination.
pages[].current_page	integer	request_metadata > pages[]	The current page index.
pages[].current_page_link	string	request_metadata > pages[]	URL to current result page on Amazon.
pages[].result_count	integer	request_metadata > pages[]	Number of search results returned on this page.
pages[].next_page_link	string	request_metadata > pages[]	URL to the next page of search results, if available.
pages[].not_match	array of strings	request_metadata > pages[]	Expected fields that were not returned.
pages[].ms	integer (ms)	request_metadata > pages[]	Time in milliseconds spent to fetch this page.

🧪 Sample Output-request_info ,request_parameters ,request_metadata

{
  "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
      }
    ]
  }
}

📦Core Response Payload – result Section

This section contains the core data returned from the search operation. It is an object composed of multiple key fields that represent the actual results and supporting contextual data.

➡️search_results (array of objects)

This array holds the actual list of search results. Each element represents a product (or listing) with various attributes such as title, price, rating, and other commercial metadata.

Field	Type	Parent	Description
position	integer	search_results[]	The ranking or order of the item within the result list.
title	string	search_results[]	The full product title or name.
asin	string	search_results[]	Amazon's unique product identifier (ASIN).
brand	string	search_results[]	The brand name of the product.
link	string	search_results[]	Relative URL path to the product’s detail page.
image	string	search_results[]	Image identifier for displaying the product thumbnail.
is_sponsored	boolean	search_results[]	Indicates whether the item is a sponsored listing.
is_prime	boolean	search_results[]	Indicates Prime eligibility for the product.
rating_text	string	search_results[]	Textual representation of the product rating (e.g., "4.6 out of 5 stars").
rating	string	search_results[]	Numeric product rating (e.g., "4.6").
ratings_total	integer	search_results[]	Total number of customer reviews.

🔸bought_activity (object)

Shows recent purchase activity for the product.

Field	Type	Parent	Description
bought_activity.raw	string	search_results[] > bought_activity	Human-readable summary (e.g., "2K+ bought...").
bought_activity.value	integer	search_results[] > bought_activity	Estimated number of units purchased.
bought_activity.period	string	search_results[] > bought_activity	Time period for purchase data (e.g., "past month").
bought_activity.symbol	string	search_results[] > bought_activity	Abbreviation used in raw (e.g., "K", "M").

🔸color_options (object)

Represents available color variations for the product.

Field	Type	Parent	Description
color_options.raw	string	search_results[] > color_options	Raw string showing variation count (e.g., "+32").
color_options.additional_count	integer	search_results[] > color_options	Number of additional color variants.
color_options.total_count	integer	search_results[] > color_options	Total number of color variants available.

🔸price (object) & prices[] (array)

Represents the primary product price and optionally other price variants.

Field	Type	Parent	Description
price.symbol	string	search_results[] > price	Currency symbol (e.g., "$").
price.value	string	search_results[] > price	Price as a stringified number (e.g., "34.40").
price.currency	string	search_results[] > price	Currency code (e.g., "USD").
price.raw	string	search_results[] > price	Raw formatted price text (e.g., "$34.40").

🔸more_buying_choices (object)

Alternative offers or listings for the same product.

Field	Type	Parent	Description
more_buying_choices.raw	string	search_results[] > more_buying_choices	Human-readable text showing offers (e.g., "$25.82 (6+...)").
more_buying_choices.min_offers_count	integer	search_results[] > more_buying_choices	Minimum number of available alternative offers.
more_buying_choices.link	string	search_results[] > more_buying_choices	URL to the offer comparison page.
more_buying_choices.price.*	mixed	search_results[] > more_buying_choices > price	Nested price details for the offer.

🔸 shipping_details

Field	Type	Parent	Description
shipping_details	string	search_results[]	Free/paid delivery options and estimated arrival date.

➡️refinements (object)

This field represents the available filtering options shown on the left sidebar of the Amazon search results page (e.g., customer reviews, shipping options, delivery time). Each refinement allows the user to narrow down search results based on specific criteria.

🔸customer_reviews (array of objects)

Allows users to filter products based on the average customer rating. Common values are "4 Stars", "3 Stars & Up", etc.

Field	Type	Parent	Description
name	string	refinements > customer_reviews	Display label like "4 Stars".
value	string	refinements > customer_reviews	Amazon query parameter (e.g., n:1055398,p_72:1248915011).
link	string	refinements > customer_reviews	URL with rating filter applied.
refinement_display_name	string	refinements > customer_reviews	Always "Customer Reviews".

🔸eligible_for_free_shipping (array of objects)

Filters products eligible for free shipping by Amazon.

Field	Type	Parent	Description
name	string	refinements > eligible_for_free_shipping	Always "Free Shipping by Amazon".
value	string	refinements > eligible_for_free_shipping	Amazon filter value like n:1055398,p_76:1249155011.
link	string	refinements > eligible_for_free_shipping	URL that applies the free shipping filter.
refinement_display_name	string	refinements > eligible_for_free_shipping	Always "Eligible for Free Shipping".

🔸delivery_day (array of objects)

Lets users filter products based on delivery speed, such as "Get it by Tomorrow".

Field	Type	Parent	Description
name	string	refinements > delivery_day	Typically "Get It by Tomorrow".
value	string	refinements > delivery_day	Amazon query value (e.g., p_90:8308921011).
link	string	refinements > delivery_day	URL that applies the delivery day filter.
refinement_display_name	string	refinements > delivery_day	Always "Delivery Day".

🔸 brands (array of objects)

This section lists all brand filters available for the current search. Each entry allows users to narrow the results by selecting a specific brand (e.g., STANLEY, YETI). These appear under the "Brands" filter group on the Amazon sidebar.

Field	Type	Parent	Description
name	string	refinements > brands	Brand name shown to the user (e.g., "STANLEY", "YETI").
value	string	refinements > brands	Amazon query string to filter by brand (e.g., p_123:315576).
link	string	refinements > brands	The full URL to apply the filter for this brand.
refinement_display_name	string	refinements > brands	Always "Brands" — the filter group this entry belongs to.

🔸 price (array of objects)

This section represents the price filter displayed in the Amazon sidebar. It shows the full price range (min–max) that users can select to filter search results by cost.

Field	Type	Parent	Description
name	string	refinements > price	Display label, typically "Price".
range	string	refinements > price	The visible range label shown to users (e.g., "$0–$1,900+").
min_value	string	refinements > price	Minimum price in the filter range (as string, e.g., "$0").
max_value	string	refinements > price	Maximum price in the filter range (as string, e.g., "$1,900+").
refinement_display_name	string	refinements > price	Always "Price" — the name of the filter group it belongs to.

🔸deals_discounts (array of objects)

This section shows the active deals and discount filters in the Amazon sidebar (e.g., "Today's Deals"). Users can filter search results to show only discounted items or those part of promotional events.

Field	Type	Parent	Description
name	string	refinements > deals_discounts	The label shown to users (e.g., "Today's Deals", "All Discounts").
value	string	refinements > deals_discounts	Filter parameter used in query strings (e.g., p_n_deal_type:23566064011).
link	string	refinements > deals_discounts	Full URL path used to apply the specific deal/discount filter.
refinement_display_name	string	refinements > deals_discounts	Group name of the refinement filter (always "Deals & Discounts").

🔸 condition (array of objects)

This section refers to the item condition filters (such as New or Used) found in Amazon's sidebar. It allows users to narrow search results by product condition.

Field	Type	Parent	Description
name	string	refinements > condition	Display label of the condition (e.g., "New", "Used").
value	string	refinements > condition	Filter code representing the condition (used in query parameters).
link	string	refinements > condition	URL to apply this condition filter in search.
refinement_display_name	string	refinements > condition	Filter group name (always "Condition" in this case).

🔸 seller (array of objects)

This section lists available sellers on Amazon for the current search query. It allows users to filter products based on which seller offers them (e.g., "Amazon.com", "third-party sellers"). This area allows users to filter products with options from specific sellers.

Field	Type	Parent	Description
name	string	refinements > seller	Name of the seller (e.g., "Amazon.com", or a marketplace seller name).
value	string	refinements > seller	Encoded value used in query params to filter by this seller.
link	string	refinements > seller	URL to directly apply the seller filter.
refinement_display_name	string	refinements > seller	Filter category label (always "Seller" in this case).

🔸 department (array of objects)

The department field allows filtering by Amazon's category hierarchy (also known as browse nodes). It represents the product departments or categories relevant to the search results (e.g., "Insulated Beverage Containers", "Glassware & Drinkware"). This area shows the categories that search results belong to and allows users to list only products that belong to a specific department.

Field	Type	Parent	Description
name	string	refinements > department	Name of the product department (category label shown in UI).
value	string	refinements > department	Encoded department identifier (used in filter queries).
link	string	refinements > department	URL to apply the filter for the selected department.
refinement_display_name	string	refinements > department	Always "Department"; identifies the refinement category.

🔸 color (array of objects)

The color field under refinements provides filtering options based on the color of the products. This allows users to narrow down search results to specific color preferences like Black, Pink, etc. Amazon provides this filter especially for categories like fashion, home goods, or decorative items to help users make quick decisions.

Field	Type	Parent	Description
name	string	refinements > color	Name of the color option (e.g., "Black", "Pink").
value	string	refinements > color	Encoded filter value to apply the color refinement (used in query string).
link	string	refinements > color	URL to apply this specific color filter.
refinement_display_name	string	refinements > color	Always "Color"; identifies this as the color refinement section.

🔸 grade (array of objects)

This refinement offers filtering based on product grade or usage classification, such as "Commercial Grade". It's typically used in product categories where build quality or usage context (residential vs. commercial) matters.

Field	Type	Parent	Description
name	string	refinements > grade[]	The label displayed to the user (e.g., "Commercial Grade").
value	string	refinements > grade[]	Encoded query string used for Amazon's internal filtering logic.
link	string	refinements > grade[]	Direct search URL applying this specific grade filter.
refinement_display_name	string	refinements > grade[]	The filter category name shown in the UI, usually "Grade".

🔸premium_brands(array of objects)

This refinement allows users to filter for products from high-end or recognized premium brands, often associated with superior quality, higher price points, or reputation. It is typically used in categories like fashion, home goods, or consumer electronics.

Field	Type	Parent	Description
name	string	refinements > premium_brands[]	Display label of the refinement, often "Premium Brands".
value	string	refinements > premium_brands[]	Amazon query string value for backend filtering.
link	string	refinements > premium_brands[]	URL to directly apply this filter in the search results.
refinement_display_name	string	refinements > premium_brands[]	UI section title under which this filter appears (e.g., "Premium Brands").

🔸moresustainable_products(array of objects)

This filter category highlights products that meet certain sustainability criteria set by Amazon, such as the "Climate Pledge Friendly" badge. It helps customers quickly find environmentally conscious or eco-friendly products.

Field	Type	Parent	Description
name	string	refinements > moresustainable_products[]	The display name of the sustainability tag, e.g., “Climate Pledge Friendly”.
value	string	refinements > moresustainable_products[]	Amazon's internal query value used for filtering sustainable items.
link	string	refinements > moresustainable_products[]	URL to apply the sustainability filter directly in search results.
refinement_display_name	string	refinements > moresustainable_products[]	The UI section title (e.g., "More-sustainable Products").

🔸subscription_options(array of objects)

This filter category includes options related to product subscriptions, allowing users to find items eligible for subscription programs like “Subscribe & Save.”

Field	Type	Parent	Description
subscription_options[].name	string	refinements.subscription_options[]	Display name of the subscription option.
subscription_options[].value	string	refinements.subscription_options[]	Internal filter code used for refining search results.
subscription_options[].link	string	refinements.subscription_options[]	URL link to apply the subscription filter on Amazon.
subscription_options[].refinement_display_name	string	refinements.subscription_options[]	Label describing the filter category (“Subscription Options”).

➡️related_searches (array)

➡️delivered_to (string)

Field	Type	Parent	Description
delivered_to	string	root object	The delivery location shown to the user (e.g., city and ZIP code).