# Request

### Endpoint

```
GET https://realtime.easyparser.com/v1/request
```

### Required Parameters

This operation requires certain common parameters to be included in every request. For more details, see [Common Required Request Fields](https://easyparser.gitbook.io/easyparser-documentation/real-time-integration/common-required-request-fields).

### Optional Parameters

| Parameter           | Type    | Description                                                                                 |
| ------------------- | ------- | ------------------------------------------------------------------------------------------- |
| `associate_id`      | string  | Adds your Amazon Associate (Affiliate) ID to product URLs in the response.                  |
| `address_id`        | string  | Performs the search using a predefined shipping address (zip code) saved in your account.   |
| `parameters`        | string  | Appends additional query parameters in `key=value` format, separated by semicolons.         |
| `language`          | string  | Displays the Amazon page in the specified language (e.g. `en_US`, `de_DE`).                 |
| `currency`          | string  | Requests product prices in the selected currency (e.g. `usd`, `eur`).                       |
| `sort_by`           | string  | Sorts search results by criteria like `featured`, `price-asc-rank`, `price-desc-rank`, etc. |
| `refinements`       | string  | Applies filters like category or attributes (format: `n:category_id,p_123:filter_id`).      |
| `include_html`      | boolean | If `true`, includes raw HTML of the search result page in the response.                     |
| `cookie`            | string  | Custom cookies in `key=value` format, separated by semicolons. Sent via HTTP header.        |
| `exclude_sponsored` | boolean | If `true`, excludes sponsored (ad) products from the search results.                        |
| `min_page`          | integer | Starting page number for paginated search results.                                          |
| `max_page`          | integer | Ending page number for paginated search results.                                            |

{% hint style="info" %}
💡 **Note:** When using pagination parameters (`min_page` and `max_page`), each page consumes **1 credit**.\
You can request up to **5 pages per operation**.\
For more details, see the [Credit Consumption](https://easyparser.gitbook.io/easyparser-documentation/amazon/credit-consumption).
{% endhint %}

### Notes on Selected Parameters

* **Examples of `sort_by` values:**
  * `featured` – Default sorting (Amazon’s featured order)
  * `price-asc-rank` – Sort by lowest to highest price
  * `price-desc-rank` – Sort by highest to lowest price
  * `review-rank` – Sort by most reviewed products
  * `date-desc-rank` – Sort by newest listings
* **`refinements` format:**
  * Used to target categories and filters. Example:\
    `n:7141123011,p_123:502215`\
    Where:
    * `n:` → category ID
    * `p_123:` → specific filter ID (e.g., size, color, brand)

{% hint style="info" %}
You can extract these IDs from Amazon search URLs or define them based on your own filtering needs.\
Alternatively, you can also send a **Search** request first and refer to the `refinements` field in the response to discover available filters and their corresponding IDs dynamically.
{% endhint %}

### Example Request

{% tabs %}
{% tab title="cURL" %}
{% code overflow="wrap" %}

```javascript

curl --location 'https://realtime.easyparser.com/v1/request?api_key=YOUR_API_KEY&
  platform=AMZ&
  operation=SEARCH&
  address_id=756&
  domain=.com&
  keyword=winter&
  exclude_refinements=false&
  refinements=n%3A7141123011%2Cp_123%3A502215&
  sort_by=price-asc-rank&
  exclude_sponsored=true&
  associate_id=helloexample&
  language=en_US&
  cookie=key%3Dvalue%3Bkey%3Dvalue&
  min_page=1&
  max_page=5&
  currency=mxn&
  parameters=tag%3Dmytag'
```

{% endcode %}
{% endtab %}

{% tab title="Python" %}
{% code overflow="wrap" %}

```python

import requests
import json

# set up the request parameters
params = {
  "api_key": "YOUR_API_KEY",
  "platform": "AMZ",
  "operation": "SEARCH",
  "address_id": "756",
  "domain": ".com",
  "keyword": "winter",
  "exclude_refinements": "false",
  "refinements": "n:7141123011,p_123:502215",
  "sort_by": "price-asc-rank",
  "exclude_sponsored": "true",
  "associate_id": "helloexample",
  "language": "en_US",
  "cookie": "key=value;key=value",
  "min_page": "1",
  "max_page": "5",
  "currency": "mxn",
  "parameters": "tag=mytag",
}

# make the http GET request to Easyparser API
api_result = requests.get("https://realtime.easyparser.com/v1/request", params=params)

# print the JSON response from Easyparser API
print(json.dumps(api_result.json(), indent=2))
```

{% endcode %}
{% endtab %}

{% tab title="Node.js" %}
{% code overflow="wrap" %}

```javascript

const axios = require("axios");

// set up the request parameters
const params = {
  api_key: "YOUR_API_KEY",
  platform: "AMZ",
  operation: "SEARCH",
  address_id: "756",
  domain: ".com",
  keyword: "winter",
  exclude_refinements: "false",
  refinements: "n:7141123011,p_123:502215",
  sort_by: "price-asc-rank",
  exclude_sponsored: "true",
  associate_id: "helloexample",
  language: "en_US",
  cookie: "key=value;key=value",
  min_page: "1",
  max_page: "5",
  currency: "mxn",
  parameters: "tag=mytag",
}

// make the http GET request to Easyparser API
axios.get("https://realtime.easyparser.com/v1/request", { params })
.then(response => {
  // print the JSON response from Easyparser API
  console.log(JSON.stringify(response.data, null, 2));
})
```

{% endcode %}
{% endtab %}

{% tab title="HTTP" %}
{% code overflow="wrap" %}

```http

GET /v1/request?api_key=YOUR_API_KEY&
  platform=AMZ&
  operation=SEARCH&
  address_id=756&
  domain=.com&
  keyword=winter&
  exclude_refinements=false&
  refinements=n%3A7141123011%2Cp_123%3A502215&
  sort_by=price-asc-rank&
  exclude_sponsored=true&
  associate_id=helloexample&
  language=en_US&
  cookie=key%3Dvalue%3Bkey%3Dvalue&
  min_page=1&
  max_page=5&
  currency=mxn&
  parameters=tag%3Dmytag HTTP/1.1
Host: realtime.easyparser.com
```

{% endcode %}
{% endtab %}

{% tab title="PHP" %}
{% code overflow="wrap" %}

```php

<?php

# set up the request parameters
$params = [
  "api_key" => "YOUR_API_KEY",
  "platform" => "AMZ",
  "operation" => "SEARCH",
  "address_id" => "756",
  "domain" => ".com",
  "keyword" => "winter",
  "exclude_refinements" => "false",
  "refinements" => "n:7141123011,p_123:502215",
  "sort_by" => "price-asc-rank",
  "exclude_sponsored" => "true",
  "associate_id" => "helloexample",
  "language" => "en_US",
  "cookie" => "key=value;key=value",
  "min_page" => "1",
  "max_page" => "5",
  "currency" => "mxn",
  "parameters" => "tag=mytag",
];

# make the http GET request to Easyparser API
$response = file_get_contents("https://realtime.easyparser.com/v1/request?" . http_build_query($params));

# print the JSON response from Easyparser API
echo $response;
```

{% endcode %}
{% endtab %}

{% tab title="GO" %}

```go

package main

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

func main() {
  // set up the request parameters
  url := "https://realtime.easyparser.com/v1/request?params := url.Values{}
params.Add("api_key", "YOUR_API_KEY")
params.Add("platform", "AMZ")
params.Add("operation", "SEARCH")
params.Add("address_id", "756")
params.Add("domain", ".com")
params.Add("keyword", "winter")
params.Add("exclude_refinements", "false")
params.Add("refinements", "n:7141123011,p_123:502215")
params.Add("sort_by", "price-asc-rank")
params.Add("exclude_sponsored", "true")
params.Add("associate_id", "helloexample")
params.Add("language", "en_US")
params.Add("cookie", "key=value;key=value")
params.Add("min_page", "1")
params.Add("max_page", "5")
params.Add("currency", "mxn")
params.Add("parameters", "tag=mytag")
fullURL := fmt.Sprintf("%s?%s", baseURL, params.Encode())
"
  
  // make the http GET request to Easyparser API
  res, _ := http.Get(url)
  defer res.Body.Close()
  
  // print the JSON response from Easyparser API
  body, _ := io.ReadAll(res.Body)
  fmt.Println(string(body))
}
```

{% endtab %}

{% tab title="C#" %}
{% code overflow="wrap" %}

```csharp

using System.Net.Http;

// set up the request parameters
var client = new HttpClient();

// make the http GET request to Easyparser API
var response = await client.GetAsync("https://realtime.easyparser.com/v1/request?var query = HttpUtility.ParseQueryString(string.Empty);
query["api_key"] = "YOUR_API_KEY";
query["platform"] = "AMZ";
query["operation"] = "SEARCH";
query["address_id"] = "756";
query["domain"] = ".com";
query["keyword"] = "winter";
query["exclude_refinements"] = "false";
query["refinements"] = "n:7141123011,p_123:502215";
query["sort_by"] = "price-asc-rank";
query["exclude_sponsored"] = "true";
query["associate_id"] = "helloexample";
query["language"] = "en_US";
query["cookie"] = "key=value;key=value";
query["min_page"] = "1";
query["max_page"] = "5";
query["currency"] = "mxn";
query["parameters"] = "tag=mytag";
var fullUrl = baseUrl + "?" + query.ToString();
");

// print the JSON response from Easyparser API
var result = await response.Content.ReadAsStringAsync();
Console.WriteLine(result);
```

{% endcode %}
{% endtab %}

{% tab title="Java" %}
{% code overflow="wrap" %}

```java

import okhttp3.*;

// set up the request parameters
OkHttpClient client = new OkHttpClient();

// make the http GET request to Easyparser API
Request request = new Request.Builder()
  .url("https://realtime.easyparser.com/v1/request?URIBuilder builder = new URIBuilder(baseUrl);
builder.addParameter("api_key", "YOUR_API_KEY");
builder.addParameter("platform", "AMZ");
builder.addParameter("operation", "SEARCH");
builder.addParameter("address_id", "756");
builder.addParameter("domain", ".com");
builder.addParameter("keyword", "winter");
builder.addParameter("exclude_refinements", "false");
builder.addParameter("refinements", "n:7141123011,p_123:502215");
builder.addParameter("sort_by", "price-asc-rank");
builder.addParameter("exclude_sponsored", "true");
builder.addParameter("associate_id", "helloexample");
builder.addParameter("language", "en_US");
builder.addParameter("cookie", "key=value;key=value");
builder.addParameter("min_page", "1");
builder.addParameter("max_page", "5");
builder.addParameter("currency", "mxn");
builder.addParameter("parameters", "tag=mytag");
String fullUrl = builder.build().toString();
")
  .build();

// print the JSON response from Easyparser API
Response response = client.newCall(request).execute();
System.out.println(response.body().string());
```

{% endcode %}
{% endtab %}
{% endtabs %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://easyparser.gitbook.io/easyparser-documentation/real-time-integration/search/request.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.