# Response

## API Response Structure Overview

The JSON response is organized into four primary sections:

1. `request_info`: Contains the status of the API call, unique request ID, and detailed credit consumption info.
2. `request_parameters`: Echoes back the parameters you sent (ASIN, history\_range, etc.) to confirm what was processed.
3. `request_metadata`: Timestamps regarding when the request was created and processed.
4. `result`:  The core payload containing the product's sales analysis, traffic data, and history.

## 1 - Top-Level Meta Fields (Outside of `result`)

These fields provide essential information about the transaction status, parameters, and processing timing.

### `request_info`(object)

Contains the status of the API call and credit usage details.

| `id`                        | String            | A unique identifier for this specific request.                           |
| --------------------------- | ----------------- | ------------------------------------------------------------------------ |
| `status_code`               | Number            | Standard HTTP status code (e.g., `200` for success).                     |
| `error_details`             | Array             | An array of error messages if the request failed. Empty `[]` on success. |
| `credits_used`              | Number            | The total cumulative credits used by your account to date.               |
| `credits_used_this_request` | Number            | The specific cost deducted for this call (Base Cost + History Cost).     |
| `credits_remaining`         | Number            | Your current remaining credit balance.                                   |
| `credits_reset_at`          | String (ISO Date) | The date and time when your monthly credit limit will reset.             |

### `request_parameters` (object)

Echoes back the parameters sent in the request to confirm what was processed.

| `type`          | String  | The operation type executed (`SALES_ANALYSIS_HISTORY`).           |
| --------------- | ------- | ----------------------------------------------------------------- |
| `asin`          | String  | The target ASIN processed.                                        |
| `history_range` | Number  | The historical depth (in months) processed.                       |
| `output`        | String  | The response format (default: `"json"`).                          |
| `language`      | String  | The localization language used for the request (e.g., `"en_US"`). |
| `include_html`  | Boolean | Indicates if raw HTML was requested (default: `false`).           |

### `request_metadata` (object)

| `created_at`       | String (ISO Date) | The timestamp when the request was received by the system.              |
| ------------------ | ----------------- | ----------------------------------------------------------------------- |
| `processed_at`     | String (ISO Date) | The timestamp when the processing was completed.                        |
| `total_time_taken` | Number            | The total duration (in seconds) the system took to process the request. |

## 2 - Core Response Payload – `result` Section

This section contains the actual market intelligence data, categorized into logical groups.

The API response is divided into two main sections within the `result` object:

1. `product`: Contains all static details, current performance metrics, pricing, and categorization.
2. `history`: Contains the weekly historical data array based on the requested range.

### A- Product Identity & Details (`result.product`)

| `asin`                  | String  | The unique Amazon Standard Identification Number (e.g., `"B07C2Z21X5"`).    |
| ----------------------- | ------- | --------------------------------------------------------------------------- |
| `main_asin`             | String  | The marketplace-specific unique identifier (e.g., `"B07C2Z21X5-US"`).       |
| `marketplace`           | String  | The two-letter country code of the marketplace (e.g., `"US"`).              |
| `name`                  | String  | The full product title.                                                     |
| `brand`                 | String  | The brand name associated with the product.                                 |
| `category`              | String  | The category breadcrumb path (e.g., `"Camera & Photo/Digital Cameras..."`). |
| `currency`              | String  | The ISO currency code (e.g., `"USD"`).                                      |
| `age`                   | Number  | The product's age in years, calculated from the launch date.                |
| `image_url`             | String  | The URL of the main product image.                                          |
| `launch_date`           | String  | The ISO date when the product was first listed (e.g., `"2019-02-24..."`).   |
| `is_exact_match`        | Boolean | Returns `true` if the result matches the requested ASIN exactly.            |
| `product_type`          | String  | Amazon's internal product type classification (e.g., `"CAMERA_DIGITAL"`).   |
| `product_type_id`       | Number  | The numeric ID for the product type.                                        |
| `gl_product_group`      | Number  | The General Ledger (GL) product group ID.                                   |
| `gl_product_group_desc` | String  | The description of the GL product group (e.g., `"gl_camera"`).              |

```json
"product": {
    "asin": "B07C2Z21X5",
    "main_asin": "B07C2Z21X5-US",
    "marketplace": "US",
    "name": "Canon EOS Rebel T7 DSLR Camera with 18-55mm Lens...",
    "brand": "Canon",
    "category": "Camera & Photo/Digital Cameras/DSLR Cameras",
    "currency": "USD",
    "age": 6.7,
    "image_url": "41ZurL2c2rL.jpg",
    "launch_date": "2019-02-24T00:00:00.000Z",
    "is_exact_match": true,
    "product_type": "CAMERA_DIGITAL",
    "product_type_id": 686,
    "gl_product_group": 421,
    "gl_product_group_desc": "gl_camera"
}
```

### **Physical (`result.product.physical`)**

Dimensions and weight information.

| `weight`         | String | The weight of the product.             |
| ---------------- | ------ | -------------------------------------- |
| `weight_unit`    | String | The unit of mass (e.g., `"pounds"`).   |
| `height`         | String | The height dimension.                  |
| `length`         | String | The length dimension.                  |
| `dimension_unit` | String | The unit of length (e.g., `"inches"`). |

```json
"physical": {
    "weight": "1.04",
    "weight_unit": "pounds",
    "height": "4.0",
    "length": "3.1",
    "dimension_unit": "inches"
}
```

### **Performance (`result.product.performance`)**

Contains Traffic (Views) and Sales (Purchases) data, including comparisons.

<table data-header-hidden><thead><tr><th width="319">Field</th><th width="148.6666259765625">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>traffic.total_views</code></td><td>Number</td><td>Cumulative lifetime views.</td></tr><tr><td><code>traffic.views_last_30_days</code></td><td>Number</td><td>Views in the last 30 days.</td></tr><tr><td><code>traffic.views_last_90_days</code></td><td>Number</td><td>Views in the last 90 days.</td></tr><tr><td><code>traffic.views_last_360_days</code></td><td>Number</td><td>Views in the last year.</td></tr><tr><td><code>traffic.month_over_month_change</code></td><td>Number</td><td>Growth/decline rate compared to the previous month.</td></tr><tr><td><code>sales.purchases_last_30_days</code></td><td>Number</td><td>Sales in the last 30 days.</td></tr><tr><td><code>sales.purchases_last_90_days</code></td><td>Number</td><td>Sales in the last 90 days.</td></tr><tr><td><code>sales.purchases_last_360_days</code></td><td>Number</td><td>Sales in the last year.</td></tr></tbody></table>

```json
"performance": {
    "traffic": {
        "total_views": 1232772,
        "views_last_30_days": 106497,
        "views_previous_30_days": 97873,
        "month_over_month_change": 0.08811418879568422,
        "quarter_over_quarter_change": -0.00492777124036603
    },
    "sales": {
        "purchases_last_30_days": 1054,
        "purchases_last_90_days": 3123,
        "purchases_last_360_days": 12206
    }
}
```

### **Pricing (`result.product.pricing`)**

<table data-header-hidden><thead><tr><th width="326.33331298828125"></th><th width="135.333251953125"></th><th></th></tr></thead><tbody><tr><td><strong>Field</strong></td><td><strong>Type</strong></td><td><strong>Description</strong></td></tr><tr><td><code>average_price_last_90_days</code></td><td>Number</td><td>Average Buy Box price (last 3 months).</td></tr><tr><td><code>average_price_last_360_days</code></td><td>Number</td><td>Average Buy Box price (last 12 months).</td></tr><tr><td><code>fees.fba_fee_last_360_days</code></td><td>Number</td><td>Current FBA fulfillment fee.</td></tr><tr><td><code>fees.referral_fee_last_360_days</code></td><td>Number</td><td>Estimated referral (commission) fee.</td></tr><tr><td><code>offers.total_offers_last_90_days</code></td><td>Number</td><td>Total unique offers seen in the last quarter.</td></tr><tr><td><code>offers.new_offer_average_depth</code></td><td>Number</td><td>The average stock quantity (inventory depth) for "New" condition offers.</td></tr><tr><td><code>offers.new_offer_min_price</code></td><td>Number</td><td>Lowest price observed for "New" condition.</td></tr><tr><td><code>offers.new_offer_max_price</code></td><td>Number</td><td>Highest price observed for "New" condition.</td></tr></tbody></table>

```json
"pricing": {
    "average_price_last_90_days": 523.542275,
    "average_price_last_360_days": 488.450272,
    "offers": {
        "total_offers_last_90_days": 22,
        "new_offer_average_depth": 18.6836614202,
        "new_offer_max_price": 579.99,
        "new_offer_min_price": 7.99
    },
    "fees": {
        "fba_fee_last_360_days": 8.332521,
        "referral_fee_last_360_days": 37.15606
    }
}
```

### **Reviews & Ranking (`result.product.reviews_and_ranking`),**

Social proof and Best Seller Rank (BSR) details.

| `reviews.total_count`    | Number | Total review count.                    |
| ------------------------ | ------ | -------------------------------------- |
| `reviews.average_rating` | Number | Average star rating (0-5).             |
| `ranking.current_rank`   | Number | Current BSR.                           |
| `ranking.average_rank`   | Number | Average BSR over time.                 |
| `ranking.category`       | String | The category associated with the rank. |

```json
"reviews_and_ranking": {
    "reviews": {
        "total_count": 8175,
        "average_rating": 4.7
    },
    "ranking": {
        "current_rank": 1,
        "category": "DSLR Cameras",
        "average_rank": 1
    }
}
```

### B- Historical Data (`result.history`)

This array sits at the root of `result` (sibling to `product`). It contains weekly aggregated data points based on the `history_range` parameter.

| `date`             | String | The starting date of the week for this data point.               |
| ------------------ | ------ | ---------------------------------------------------------------- |
| `views`            | Number | Total views generated during this specific week.                 |
| `purchases`        | Number | Total units sold during this specific week.                      |
| `average_price`    | Number | Average selling price observed during this week.                 |
| `total_offers`     | Number | Number of active sellers on the listing during this week.        |
| `best_seller_rank` | Number | BSR position during this week.                                   |
| `review_count`     | Number | The total number of new reviews added during this specific week. |
| `review_rating`    | Number | The average rating of the new reviews added during this week.    |

```json
{
    "date": "2025-11-09T00:00:00.000Z",
    "views": 22277,
    "purchases": 220,
    "average_price": 466.96411048432157,
    "total_offers": 20,
    "review_count": 213,
    "review_rating": 4.8,
    "best_seller_rank": 1
},
{
    "date":"2025-11-02T00:00:00.000Z",
    "views":8232,
    "purchases":636,
    "average_price":111.04167739439139,
    "total_offers":3,
    "review_count":124,
    "review_rating":4.7,
    "best_seller_rank":4
}
```