# Best Sellers Rank: Response

> Response fields of the Easyparser BEST_SELLERS_RANK operation for version 2 and legacy version 1, with sample JSON and a migration table.

Source: https://docs.easyparser.com/real-time-integration/best-sellers-rank/response

The `result` object contains the marketplace country code and a `product` object with the product's Best Sellers Rank data. Every response uses the shared [response envelope](/real-time-integration/overview#response-envelope) (`request_info`, `request_parameters`, `request_metadata`, `result`).

The structure of `result.product` depends on the `operation_version` you send. Version `2` is the Live version since November 1, 2026 and is returned when you do not send `operation_version`; version `1` is the legacy structure. The envelope is the same in both versions, and `request_parameters.operation_version` shows the version that was applied.

## Response structure

Version `2`:

```
result
├── country_code
└── product
    ├── asin, title, brand_name, manufacturer, link
    ├── bestseller
    │   ├── category_rank, category_title, category_link
    │   └── sub_category_rank, sub_category_title, sub_category_link
    ├── bestsellers[]
    │   └── rank, title, link, type
    └── image
        └── id, link, variant
```

Version `1` (legacy):

```
result
├── country_code
└── product
    ├── asin, title, brand_name, price, currency, link
    ├── bestseller
    │   └── rank, context_name, sub_category_id
    ├── media
    │   └── image_url, thumb_url
    └── reviews
        └── rating_value, rating_text, full_star_count, total_count
```

## Result fields

### `result`

The same in both versions.

| Field | Type | Description |
|---|---|---|
| `country_code` | string | ISO 3166 alpha-2 country code of the marketplace, for example `US`. |
| `product` | object | Product details and rank data. Its fields depend on the version. |

### `result.product` (version 2)

| Field | Type | Description |
|---|---|---|
| `asin` | string | ASIN of the product. |
| `title` | string | Short product title. |
| `brand_name` | string | Brand of the product. |
| `manufacturer` | string | Manufacturer of the product. |
| `link` | string | URL of the product detail page on Amazon. |
| `bestseller` | object | Rank summary for the main category and the primary subcategory. |
| `bestsellers` | array | Every Best Sellers list the product is ranked in. |
| `image` | object or null | Full-resolution main image. `null` when no image is available. |

### `result.product.bestseller` (version 2)

A summary of the product's rank in its main category and its primary subcategory. For every list the product is ranked in, use `bestsellers[]`.

| Field | Type | Description |
|---|---|---|
| `category_rank` | integer | Rank in the main category. |
| `category_title` | string | Name of the main category, for example `Kitchen & Dining`. |
| `category_link` | string | URL of the main category's Best Sellers list. |
| `sub_category_rank` | integer | Rank in the subcategory. |
| `sub_category_title` | string | Name of the subcategory, for example `Household Stand Mixers`. |
| `sub_category_link` | string | URL of the subcategory's Best Sellers list. |

### `result.product.bestsellers[]` (version 2)

One entry per Best Sellers list the product is ranked in, including the main category and each subcategory. Entries are not returned in a guaranteed order; use `type` to tell the main category apart from subcategories.

| Field | Type | Description |
|---|---|---|
| `rank` | integer | Rank in this list. |
| `title` | string | Name of the category. |
| `link` | string | URL of the category's Best Sellers list. |
| `type` | string | Category level. Allowed: `category` (main category), `sub_category`. |

### `result.product.image` (version 2)

| Field | Type | Description |
|---|---|---|
| `id` | string | Amazon image identifier, for example `71d0Mecy7-L`. |
| `link` | string | URL of the full-resolution image. |
| `variant` | string | Image variant, for example `MAIN` for the primary product image. |

### `result.product` (version 1, legacy)

| Field | Type | Description |
|---|---|---|
| `asin` | string | ASIN of the product. |
| `title` | string | Full product title as shown on the listing. |
| `brand_name` | string | Brand of the product. |
| `price` | number | Current selling price at the time of the request. |
| `currency` | string | ISO 4217 currency code of the marketplace, for example `USD`. |
| `link` | string | URL of the product detail page on Amazon. |
| `bestseller` | object | Main category rank. |
| `media` | object | Primary image links. |
| `reviews` | object | Rating summary. |

### `result.product.bestseller` (version 1, legacy)

| Field | Type | Description |
|---|---|---|
| `rank` | integer | Rank in the main category. `0` when the product has no Best Sellers Rank. |
| `context_name` | string | Name of the main category. |
| `sub_category_id` | string | Browse node ID of the product's subcategory. |

### `result.product.media` (version 1, legacy)

| Field | Type | Description |
|---|---|---|
| `image_url` | string | URL of the primary product image. |
| `thumb_url` | string | URL of the thumbnail version of the primary image. |

### `result.product.reviews` (version 1, legacy)

| Field | Type | Description |
|---|---|---|
| `rating_value` | number | Average rating out of 5. |
| `rating_text` | string | Average rating as text, for example `4.7 out of 5 stars`. |
| `full_star_count` | integer | Number of fully filled stars in the rating display. |
| `total_count` | integer | Total number of customer ratings. |

## Sample response

#### Sample response (BEST_SELLERS_RANK, .com, version 2)

```json
{
    "request_info": {
        "id": "437a2cea-cae7-40a7-b96c-30780beba220",
        "success": true,
        "status_code": 200,
        "error_details": [],
        "credits_used": 9752,
        "credit_used_this_request": 1,
        "credits_remaining": 990248,
        "credits_reset_at": "2028-12-09T08:46:47.000Z"
    },
    "request_parameters": {
        "asin": "B09NHWJRFM",
        "type": "BEST_SELLERS_RANK",
        "operation_version": 2
    },
    "request_metadata": {
        "created_at": "2026-09-29T11:40:48.332Z",
        "processed_at": "2026-09-29T11:40:51.648Z",
        "total_time_taken": 3.316
    },
    "result": {
        "country_code": "US",
        "product": {
            "asin": "B09NHWJRFM",
            "bestseller": {
                "category_link": "https://www.amazon.com/gp/bestsellers/kitchen",
                "category_rank": 374,
                "category_title": "Kitchen & Dining",
                "sub_category_link": "https://www.amazon.com/gp/bestsellers/kitchen/289932",
                "sub_category_rank": 1,
                "sub_category_title": "Household Stand Mixers"
            },
            "brand_name": "KitchenAid",
            "image": {
                "id": "71d0Mecy7-L",
                "link": "https://m.media-amazon.com/images/I/71d0Mecy7-L.jpg",
                "variant": "MAIN"
            },
            "link": "https://www.amazon.com/gp/product/B09NHWJRFM",
            "manufacturer": "KitchenAid",
            "title": "KitchenAid Artisan, 5-Qt Tilt Head Stand Mixer, KSM150PS, Scorched Orange"
        },
        "bestsellers": [
    {
        "link": "https://www.amazon.com/gp/bestsellers/kitchen",
        "rank": 886,
        "title": "Kitchen & Dining",
        "type": "category"
    },
    {
        "link": "https://www.amazon.com/gp/bestsellers/kitchen/289932",
        "rank": 1,
        "title": "Household Stand Mixers",
        "type": "sub_category"
    }
]
    }
}
```

#### Sample response (BEST_SELLERS_RANK, .com, version 1, legacy)

```json
{
    "request_info": {
        "id": "161ac5ec-8e7e-4610-940d-0b7297f5170e",
        "success": true,
        "status_code": 200,
        "error_details": [],
        "credits_used": 9751,
        "credit_used_this_request": 1,
        "credits_remaining": 990249,
        "credits_reset_at": "2028-12-09T08:46:47.000Z"
    },
    "request_parameters": {
        "asin": "B09NHWJRFM",
        "type": "BEST_SELLERS_RANK",
        "operation_version": 1
    },
    "request_metadata": {
        "created_at": "2026-09-29T11:21:45.401Z",
        "processed_at": "2026-09-29T11:21:49.759Z",
        "total_time_taken": 4.358
    },
    "result": {
        "country_code": "US",
        "product": {
            "asin": "B09NHWJRFM",
            "bestseller": {
                "context_name": "Kitchen & Dining",
                "rank": 393,
                "sub_category_id": "7904803"
            },
            "brand_name": "KitchenAid",
            "currency": "USD",
            "link": "https://www.amazon.com/gp/product/B09NHWJRFM",
            "media": {
                "image_url": "https://m.media-amazon.com/images/I/41Ne2tYcuBL._SL120_.jpg",
                "thumb_url": "https://m.media-amazon.com/images/I/41Ne2tYcuBL._SL120_SL80_.jpg"
            },
            "price": 379.99,
            "reviews": {
                "full_star_count": 4,
                "rating_text": "4.7 out of 5 stars",
                "rating_value": 4.7,
                "total_count": 23203
            },
            "title": "KitchenAid Artisan, 5-Qt Tilt Head Stand Mixer, KSM150PS, Scorched Orange | Includes Pouring Shield for Mess-Free Mixing, 10 Speed Settings, Easily add Ingredients with the Tilt-Head Design"
        }
    }
}
```

## Notes

- `request_info.credit_used_this_request` is `1` in both versions.
- In the version 2 sample above, `bestsellers` appears next to `product` (`result.bestsellers`) instead of inside it. The field tables document it as `result.product.bestsellers`. Read the array from either location.

### Migrating from version 1 to version 2

Version `2` replaced version `1` as the Live version on November 1, 2026. If your integration still reads the version 1 structure, update the field paths below. The envelope and `country_code`, `product.asin`, `product.brand_name` and `product.link` are unchanged (see [Operation Versioning](/essentials/operation-versioning)).

| Version 1 field | Version 2 field | Change |
|---|---|---|
| `product.bestseller.rank` | `product.bestseller.category_rank` | Renamed |
| `product.bestseller.context_name` | `product.bestseller.category_title` | Renamed |
| `product.bestseller.sub_category_id` | (none) | Removed |
| (none) | `product.bestseller.category_link` | Added |
| (none) | `product.bestseller.sub_category_rank` | Added |
| (none) | `product.bestseller.sub_category_title` | Added |
| (none) | `product.bestseller.sub_category_link` | Added |
| (none) | `product.bestsellers` | Added (all category and subcategory ranks) |
| `product.media.image_url` | `product.image.link` | Replaced (full-resolution image) |
| `product.media.thumb_url` | (none) | Removed |
| (none) | `product.image.id` | Added |
| (none) | `product.image.variant` | Added |
| `product.title` | `product.title` | Now the short product title |
| (none) | `product.manufacturer` | Added |
| `product.price` | (none) | Removed |
| `product.currency` | (none) | Removed |
| `product.reviews` (all fields) | (none) | Removed |

> **INFO:** Version 2 does not return price, currency or review data. If you need them, use the [Detail](/real-time-integration/detail) operation.