Operation Versioning

Easyparser versions each operation's response structure separately. You choose the version with the optional operation_version request parameter, so you can test and adopt a new response structure before it becomes the default.

How versioning works

Operations change over time: fields are added, restructured or removed. When an operation's response structure changes, the new structure is released as a new version of that operation, so existing integrations keep working until they switch. Version numbers are integers and are defined per operation: one operation can have versions 1 and 2 while another has only one version.

At any time, an operation has at most two active versions:

• Live: the default version. You receive it when you do not send operation_version.
• Beta: the upcoming version. It is ready for production use and becomes the Live version on an announced date. You receive it only when you send its version number.

Live and Beta are labels, not fixed numbers. When a Beta version is promoted, it becomes the new Live version, and the next change to that operation is released as a new Beta with a higher version number.

Current operation versions

Best Sellers Rank is currently the only versioned operation. All other operations have a single version and do not need operation_version.

Operation	Code	Versions	Live version	Migration guide
Best Sellers Rank	BEST_SELLERS_RANK	1, 2	2 (since November 1, 2026)	Migrating from version 1 to version 2

Since November 1, 2026, version 2 is the Live version of Best Sellers Rank: requests without operation_version receive it. Version 1 is the legacy response structure; it stays documented on the response page to help you migrate. Both versions cost 1 credit per request (see Credit Consumption).

Note

Version 2 of Best Sellers Rank returns the main category and subcategory ranks and responds faster. It does not include price, currency or review data. The response page documents both structures.

Selecting a version

operation_version is an optional parameter in both the Real-Time API and the Bulk API. You send it together with the other parameters of the operation.

Parameter	Type	Required	Description
operation_version	integer	No	Response version to return for a versioned operation. Default: the current Live version. Allowed: 1, 2 (BEST_SELLERS_RANK only).

This Real-Time API request pins version 2 of Best Sellers Rank:

cURL

curl --get "https://realtime.easyparser.com/v1/request" \
  --data-urlencode "api_key=YOUR_API_KEY" \
  --data-urlencode "platform=AMZ" \
  --data-urlencode "operation=BEST_SELLERS_RANK" \
  --data-urlencode "domain=.com" \
  --data-urlencode "asin=B0CJB6V2L5" \
  --data-urlencode "operation_version=2"

Python

import requests

params = {
    "api_key": "YOUR_API_KEY",
    "platform": "AMZ",
    "operation": "BEST_SELLERS_RANK",
    "domain": ".com",
    "asin": "B0CJB6V2L5",
    "operation_version": "2",
}

response = requests.get("https://realtime.easyparser.com/v1/request", params=params)
print(response.json())

Node.js

const params = new URLSearchParams({
  api_key: "YOUR_API_KEY",
  platform: "AMZ",
  operation: "BEST_SELLERS_RANK",
  domain: ".com",
  asin: "B0CJB6V2L5",
  operation_version: "2",
});

const response = await fetch(`https://realtime.easyparser.com/v1/request?${params}`);
const data = await response.json();
console.log(data);

HTTP

GET /v1/request?api_key=YOUR_API_KEY&platform=AMZ&operation=BEST_SELLERS_RANK&domain=.com&asin=B0CJB6V2L5&operation_version=2 HTTP/1.1
Host: realtime.easyparser.com

PHP

<?php
$params = [
    'api_key' => 'YOUR_API_KEY',
    'platform' => 'AMZ',
    'operation' => 'BEST_SELLERS_RANK',
    'domain' => '.com',
    'asin' => 'B0CJB6V2L5',
    'operation_version' => '2',
];

$url = 'https://realtime.easyparser.com/v1/request?' . http_build_query($params);
$response = file_get_contents($url);
$data = json_decode($response, true);
print_r($data);

Go

package main

import (
  "fmt"
  "io"
  "net/http"
  "net/url"
)

func main() {
  params := url.Values{}
  params.Add("api_key", "YOUR_API_KEY")
  params.Add("platform", "AMZ")
  params.Add("operation", "BEST_SELLERS_RANK")
  params.Add("domain", ".com")
  params.Add("asin", "B0CJB6V2L5")
  params.Add("operation_version", "2")

  resp, err := http.Get("https://realtime.easyparser.com/v1/request?" + params.Encode())
  if err != nil {
    panic(err)
  }
  defer resp.Body.Close()

  body, _ := io.ReadAll(resp.Body)
  fmt.Println(string(body))
}

C#

using System;
using System.Collections.Generic;
using System.Linq;
using System.Net.Http;

var parameters = new Dictionary<string, string>
{
    ["api_key"] = "YOUR_API_KEY",
    ["platform"] = "AMZ",
    ["operation"] = "BEST_SELLERS_RANK",
    ["domain"] = ".com",
    ["asin"] = "B0CJB6V2L5",
    ["operation_version"] = "2",
};

var query = string.Join("&", parameters.Select(p =>
    $"{Uri.EscapeDataString(p.Key)}={Uri.EscapeDataString(p.Value)}"));

using var client = new HttpClient();
var response = await client.GetStringAsync($"https://realtime.easyparser.com/v1/request?{query}");
Console.WriteLine(response);

Java

import java.net.URI;
import java.net.URLEncoder;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.charset.StandardCharsets;
import java.util.LinkedHashMap;
import java.util.Map;
import java.util.stream.Collectors;

public class EasyparserRequest {
    public static void main(String[] args) throws Exception {
        Map<String, String> params = new LinkedHashMap<>();
        params.put("api_key", "YOUR_API_KEY");
        params.put("platform", "AMZ");
        params.put("operation", "BEST_SELLERS_RANK");
        params.put("domain", ".com");
        params.put("asin", "B0CJB6V2L5");
        params.put("operation_version", "2");

        String query = params.entrySet().stream()
            .map(e -> URLEncoder.encode(e.getKey(), StandardCharsets.UTF_8) + "="
                + URLEncoder.encode(e.getValue(), StandardCharsets.UTF_8))
            .collect(Collectors.joining("&"));

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://realtime.easyparser.com/v1/request?" + query))
            .GET()
            .build();

        HttpResponse<String> response = HttpClient.newHttpClient()
            .send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(response.body());
    }
}

Bulk API jobs also accept operation_version. Send it at the root of each group, next to operation, not inside payload. See Bulk Service Request for the request body format.

Confirming the applied version

The response echoes the version that was applied in request_parameters.operation_version. The operation itself is echoed as type.

"request_parameters": {
    "asin": "B0CJB6V2L5",
    "type": "BEST_SELLERS_RANK",
    "operation_version": 2
}

See the response envelope for the other request_parameters fields.

Version lifecycle

A response structure change goes through three stages:

1. Beta release: the new structure is released as the Beta version, and the date it becomes Live is announced. Requests without operation_version keep receiving the Live version.
2. Transition period: you test the Beta version by sending its version number and update your integration using the operation's migration guide.
3. Promotion: on the announced date, the Beta version becomes the new Live version. From then on, every request to the operation returns the new Live version, including requests that send an older version number.

Caution

After a Beta version is promoted, older versions are no longer returned. Make sure your integration works with the Beta version before its promotion date.

Best practices

• Switch early: start sending the Beta version number as soon as a Beta is released, so your integration is already compatible on the promotion date.
• Pin the version you built for: send the version number explicitly instead of relying on the default. Every request then states the response structure your code expects.
• Check the echo: read request_parameters.operation_version in the response to confirm which version was applied.

Unsupported version values

If you send a version number that does not exist for the operation, the request fails with this error:

{"error": "[!] The operation_version is not supported for this operation."}

Related

• Best Sellers Rank request
• Best Sellers Rank response
• Common Request Fields
• Bulk Service Request
• Credit Consumption