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

<details>

<summary>Sample Output-<code>request_info</code> ,<code>request_parameters</code> ,<code>request_metadata</code> </summary>

{% code overflow="wrap" fullWidth="true" %}

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

{% endcode %}

</details>

## 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`&#x20;

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

<table><thead><tr><th width="219">Field</th><th>Type</th><th>Parent</th><th>Description</th></tr></thead><tbody><tr><td><code>name</code></td><td>string</td><td>refinements > delivery_day</td><td>Typically <code>"Get It by Tomorrow"</code>.</td></tr><tr><td><code>value</code></td><td>string</td><td>refinements > delivery_day</td><td>Amazon query value (e.g., <code>p_90:8308921011</code>).</td></tr><tr><td><code>link</code></td><td>string</td><td>refinements > delivery_day</td><td>URL that applies the delivery day filter.</td></tr><tr><td><code>refinement_display_name</code></td><td>string</td><td>refinements > delivery_day</td><td>Always <code>"Delivery Day"</code>.</td></tr></tbody></table>

### `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). |