# Common Request Fields

> Parameters shared by every Easyparser Real-Time API request: required fields, operation identifiers, shared options, pagination and formatting rules.

Source: https://docs.easyparser.com/real-time-integration/common-required-request-fields

Every Real-Time API request needs the same four parameters plus the identifier of the operation you call. This page describes those fields, the optional parameters that several operations share, and the rules for formatting values. Each operation's request page lists the parameters it accepts; `output` is accepted by every operation and is not repeated there.

## Required parameters

| Parameter | Type | Required | Description |
|---|---|---|---|
| `api_key` | string | Yes | Your API key, sent as a query parameter. Find it at https://app.easyparser.com/account/plan. |
| `platform` | string | Yes | Target platform. Allowed: `AMZ` (Amazon). |
| `operation` | string | Yes | Operation code in upper case. Allowed: `DETAIL`, `OFFER`, `SALES_ANALYSIS_HISTORY`, `BEST_SELLERS_RANK`, `PACKAGE_DIMENSION`, `SEARCH`, `PRODUCT_LOOKUP`, `SELLER_PROFILE`, `SELLER_PRODUCTS`, `SELLER_FEEDBACK`, `SIMILAR_PRODUCTS`. |
| `domain` | string | Yes | Amazon marketplace, written with a leading dot. Example: `.com`, `.co.uk`, `.de`. See [Supported Marketplaces](/essentials/supported-marketplaces). |

When you send a `url` or an `address_id`, use the `domain` of that URL or address. For example, a `url` on `amazon.co.uk` goes with `domain=.co.uk`.

## Operation identifiers

Each operation also needs an identifier that tells it which product, search or seller to fetch. Where an operation accepts two identifiers, send exactly one of them. For example, `DETAIL` rejects a request that sends both `asin` and `url`.

| Operation | Code | Identifier |
|---|---|---|
| Detail | `DETAIL` | `asin` or `url` (product URL) |
| Offer | `OFFER` | `asin` |
| Sales Analysis and History | `SALES_ANALYSIS_HISTORY` | `asin` |
| Best Sellers Rank | `BEST_SELLERS_RANK` | `asin` |
| Package Dimension | `PACKAGE_DIMENSION` | `asin` |
| Similar Products | `SIMILAR_PRODUCTS` | `asin` |
| Search | `SEARCH` | `keyword` or `url` (search URL) |
| Product Lookup | `PRODUCT_LOOKUP` | `identifier_type` and `identifier` |
| Seller Profile | `SELLER_PROFILE` | `seller_id` or `url` (seller profile URL) |
| Seller Products | `SELLER_PRODUCTS` | `seller_id` or `url` (storefront URL) |
| Seller Feedback | `SELLER_FEEDBACK` | `seller_id` or `url` (seller profile URL) |

The identifier parameters and their formats are below. Conditional means the parameter is required for the operations that take it, as listed in the table above.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `asin` | string | Conditional | Amazon product ID: 10 upper-case letters or digits, for example `B0CJB6V2L5`. |
| `url` | string | Conditional | Full Amazon URL of the product, search results page or seller page, depending on the operation. URL-encode it. |
| `keyword` | string | Conditional | Search term for `SEARCH`. Maximum 255 characters. |
| `seller_id` | string | Conditional | Amazon seller ID: starts with `A`, 11 to 15 characters, for example `A1MCYUGJD2ILFU`. It is the `seller=` or `me=` value in an Amazon seller URL. |
| `identifier_type` | string | Conditional | Type of `identifier` for `PRODUCT_LOOKUP`. Allowed: `ASIN`, `EAN`, `GTIN`, `ISBN`, `JAN`, `MINSAN`, `UPC`. |
| `identifier` | string | Conditional | Value to look up with `PRODUCT_LOOKUP`. Maximum 18 characters. Keep leading zeros. |

You can read the `asin` and the `seller_id` from Amazon URLs: the ASIN follows `/dp/` in a product URL, and the seller ID is the `seller=` value of a seller page URL.

![Animation: the ASIN after /dp/ in an Amazon product URL becomes the asin parameter, and the seller= value of a seller page URL becomes the seller_id parameter](https://docs.easyparser.com/media/animations/docs-common-request-fields-url-ids.jpg)

*Animation: the ASIN after /dp/ in an Amazon product URL becomes the asin parameter, and the seller= value of a seller page URL becomes the seller_id parameter* ([MP4](https://docs.easyparser.com/media/animations/docs-common-request-fields-url-ids.mp4))

## Shared optional parameters

These parameters work the same way on every operation that accepts them. The Description column lists those operations.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `language` | string | No | Language of the returned content, as a locale code valid for the `domain`, for example `en_US`. Operations: `DETAIL`, `OFFER`, `SEARCH`, `SELLER_PROFILE`, `SELLER_PRODUCTS`. Default: marketplace default. |
| `currency` | string | No | Currency of returned prices, as a lower-case ISO 4217 code valid for the `domain`, for example `usd`. Case-sensitive: `USD` returns HTTP `400`. Operations: `DETAIL`, `OFFER`, `SEARCH`, `SELLER_PRODUCTS`. Default: marketplace default. |
| `address_id` | integer | No | ID of an Active saved address for the same `domain`. Operations: `DETAIL`, `OFFER`, `SEARCH`, `SELLER_PRODUCTS`. Default: marketplace default address. |
| `zip_code` | string | No | Inline delivery address: zip or postal code. Join two-part codes with a comma, for example `N0E,1Y0`. Operations: same as `address_id`. |
| `city` | string | No | Inline delivery address: city. Required with `zip_code` on `.com.au` and with `district` on `.ae`; send it alone on `.sa` and `.eg`. Operations: same as `address_id`. |
| `district` | string | No | Inline delivery address: area within `city`. Only on `.ae`, together with `city`. Operations: same as `address_id`. |
| `country_code` | string | No | Inline delivery address: ISO 3166 alpha-2 country code, for example `CA`. Operations: same as `address_id`. |
| `associate_id` | string | No | Amazon Associates tag added to product links in the response, for example `mytag-20`. Operations: `DETAIL`, `OFFER`, `SEARCH`, `SELLER_PROFILE`, `SELLER_PRODUCTS`. |
| `parameters` | string | No | Extra Amazon URL query parameters, URL-encoded as one value, for example `tag%3Dmytag-20%26ref%3Dcustom` for `tag=mytag-20&ref=custom`. Separate pairs with an encoded `&` (`%26`); semicolons do not work. Operations: same as `associate_id`. |
| `cookie` | string | No | Cookies forwarded to Amazon in the HTTP `Cookie` header: `key=value` pairs separated by `;`, URL-encoded as one value. Operations: same as `associate_id`. |
| `output` | string | No | Response format. Accepted by every operation; you do not need to send it. Default: `json`. Allowed: `json`. |
| `operation_version` | integer | No | Version of a versioned operation. Operations: `BEST_SELLERS_RANK` only, where `2` is the Live version since November 1, 2026 and `1` is the legacy version. Default: `2`. Allowed: `1`, `2`. See [Operation Versioning](/essentials/operation-versioning). |

Valid `language` and `currency` values differ by marketplace; see [Supported Marketplaces](/essentials/supported-marketplaces). A `language` the marketplace does not offer returns `MSG1015` (`Invalid language for domain`).

You can set the delivery address in two ways: `address_id` for an address saved in the web app, or the inline fields `zip_code`, `city`, `district` and `country_code`. Inline fields take precedence over `address_id` and raise the server-side timeout from 15 to 45 seconds. Operations not listed above do not support an address. See [Address Management](/essentials/address-management) for formats per marketplace.

## Pagination

`OFFER`, `SEARCH`, `SELLER_PRODUCTS` and `SELLER_FEEDBACK` return results in pages. You choose a window of pages with `min_page` and `max_page`. `SEARCH`, `SELLER_PRODUCTS` and `SELLER_FEEDBACK` also accept a single `page` instead of the window.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `min_page` | integer | No | First page to fetch. Default: `1`. Allowed: `1` to `400`. |
| `max_page` | integer | No | Last page to fetch. Must be greater than or equal to `min_page`, and one request covers at most 5 pages. Default: `1`. Allowed: `1` to `400`. |
| `page` | integer | No | One results page to fetch, as an alternative to `min_page` and `max_page`. Operations: `SEARCH`, `SELLER_PRODUCTS`, `SELLER_FEEDBACK`. Send either `page` or `min_page` and `max_page`, not both. Default: `1`. |

- One request can fetch at most 5 pages: `max_page - min_page + 1` must be `5` or less.
- Every requested page is charged, even when it has no results. Read the pagination details of a first request before you ask for more pages.
- The window can start after page 5. For example, `min_page=6&max_page=10` fetches pages 6 to 10.
- A `max_page` lower than `min_page` returns `MSG1010` (`Maximum page count must be more than minimum page count`).

> **WARNING:** Each fetched page costs 1 credit, so `min_page=1&max_page=5` costs 5 credits. See [Credit Consumption](/essentials/credit-consumption).

## Formatting rules

- Send operation codes in upper case (`PRODUCT_LOOKUP`, not `product_lookup`).
- Write `domain` with a leading dot (`.com`, not `com`).
- URL-encode every value that contains spaces or reserved characters, for example `keyword=wireless%20earbuds`.
- Leave out parameters you do not use. Do not send empty or `null` values.
- Send boolean options only when you enable them, as `=true` (for example `a_plus_content=true`).

## Related

- [Real-Time API overview](/real-time-integration/overview)
- [Supported Marketplaces](/essentials/supported-marketplaces)
- [Address Management](/essentials/address-management)
- [Credit Consumption](/essentials/credit-consumption)
- [Operation Versioning](/essentials/operation-versioning)