Search Request

Send a GET request with operation=SEARCH to the Real-Time API. You identify the search with either a keyword or the url of an Amazon search results page.

Endpoint

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

Required parameters

All parameters go in the query string. See Common Request Fields for details on the shared parameters.

Parameter	Type	Required	Description
api_key	string	Yes	Your API key, sent as a query parameter. Find it at Account > Plan.
platform	string	Yes	Target platform. Allowed: AMZ (Amazon).
operation	string	Yes	Operation code in upper case. Allowed: SEARCH.
domain	string	Yes	Amazon marketplace, written with a leading dot, for example .com. When you send url or address_id, use the domain of that URL or address. See Supported Marketplaces.
keyword	string	Conditional	Search term, for example wireless earbuds. Maximum 255 characters. Required when url is not sent. Send keyword or url, not both.
url	string	Conditional	Full URL of an Amazon search results page, URL-encoded, for example https://www.amazon.com/s?k=wireless+mouse. Required when keyword is not sent. Send keyword or url, not both.

Optional parameters

Parameter	Type	Required	Description
sort_by	string	No	Sort order of the results. Default: featured. Allowed: featured, price-asc-rank, price-desc-rank, review-rank, date-desc-rank, exact-aware-popularity-rank.
refinements	string	No	Comma-separated Amazon filters in the form n:<category_id>,p_<group>:<id>, for example n:7141123011,p_123:502215.
exclude_refinements	boolean	No	When true, Amazon's default refinements are not applied. Default: false.
exclude_sponsored	boolean	No	Removes sponsored (ad) listings from the results when true. Default: false.
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. Costs 1 credit. Send either page or min_page and max_page, not both. Default: 1.
language	string	No	Language of the returned content, as a locale code valid for the domain, for example en_US. Default: marketplace default.
currency	string	No	Currency of returned prices, as a lower-case ISO 4217 code valid for the domain, for example usd. Default: marketplace default.
address_id	integer	No	ID of an Active saved address for the same domain, from the Addresses page. 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.
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.
district	string	No	Inline delivery address: area within city. Only on .ae, together with city.
country_code	string	No	Inline delivery address: ISO 3166 alpha-2 country code, for example CA.
associate_id	string	No	Amazon Associates tag added to product links in the response, for example mytag-20.
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.
cookie	string	No	Cookies forwarded to Amazon in the HTTP Cookie header: key=value pairs separated by ;, URL-encoded as one value.

sort_by values

Value	Order
featured	Featured (Amazon's default order)
price-asc-rank	Price: low to high
price-desc-rank	Price: high to low
review-rank	Average customer review
date-desc-rank	Newest arrivals
exact-aware-popularity-rank	Best sellers

refinements format

A refinement is a key:value pair taken from Amazon's search filters. Separate several refinements with commas.

• n:<category_id> limits results to a category (browse node), for example n:7141123011.
• p_<group>:<id> applies a sidebar filter such as brand, color or rating, for example p_123:502215.

Credit cost

Condition	Credits
Each results page fetched (max_page - min_page + 1)	1
Maximum per request (5 pages)	5

Failed requests are not charged. See Credit Consumption.

Danger

Every page in the min_page to max_page range costs 1 credit. For example, min_page=1&max_page=5 costs 5 credits. To fetch pages beyond the fifth, send another request with a new window, such as min_page=6&max_page=10.

Example request

cURL

curl --get "https://realtime.easyparser.com/v1/request" \
  --data-urlencode "api_key=YOUR_API_KEY" \
  --data-urlencode "platform=AMZ" \
  --data-urlencode "operation=SEARCH" \
  --data-urlencode "domain=.com" \
  --data-urlencode "keyword=wireless earbuds" \
  --data-urlencode "sort_by=featured" \
  --data-urlencode "min_page=1" \
  --data-urlencode "max_page=1"

Python

import requests

params = {
    "api_key": "YOUR_API_KEY",
    "platform": "AMZ",
    "operation": "SEARCH",
    "domain": ".com",
    "keyword": "wireless earbuds",
    "sort_by": "featured",
    "min_page": "1",
    "max_page": "1",
}

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: "SEARCH",
  domain: ".com",
  keyword: "wireless earbuds",
  sort_by: "featured",
  min_page: "1",
  max_page: "1",
});

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=SEARCH&domain=.com&keyword=wireless%20earbuds&sort_by=featured&min_page=1&max_page=1 HTTP/1.1
Host: realtime.easyparser.com

PHP

<?php
$params = [
    'api_key' => 'YOUR_API_KEY',
    'platform' => 'AMZ',
    'operation' => 'SEARCH',
    'domain' => '.com',
    'keyword' => 'wireless earbuds',
    'sort_by' => 'featured',
    'min_page' => '1',
    'max_page' => '1',
];

$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", "SEARCH")
  params.Add("domain", ".com")
  params.Add("keyword", "wireless earbuds")
  params.Add("sort_by", "featured")
  params.Add("min_page", "1")
  params.Add("max_page", "1")

  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"] = "SEARCH",
    ["domain"] = ".com",
    ["keyword"] = "wireless earbuds",
    ["sort_by"] = "featured",
    ["min_page"] = "1",
    ["max_page"] = "1",
};

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", "SEARCH");
        params.put("domain", ".com");
        params.put("keyword", "wireless earbuds");
        params.put("sort_by", "featured");
        params.put("min_page", "1");
        params.put("max_page", "1");

        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());
    }
}

Notes

• keyword is usually simpler to automate than url. When you send url, set domain to the marketplace of the URL host (for example .com for www.amazon.com).
• An invalid keyword returns MSG1019 ("Invalid Search Term"), and an invalid url returns MSG1011 ("Invalid url").
• If max_page is lower than min_page, the request fails with MSG1010 ("Maximum page count must be more than minimum page count").
• A language that the domain does not offer returns MSG1015 ("Invalid language for domain"). See Supported Marketplaces for the languages and currencies of each domain.
• Sending inline address fields (zip_code, city, district, country_code) raises the server-side timeout from 15 to 45 seconds. address_id does not change it.
• In the Bulk API, you send keywords or urls as arrays and choose one page per input value with page instead of min_page and max_page.

Note

To find refinement IDs, send a Search request first and read result.refinements in the response: each filter's value field holds the ID to send back in refinements. You can also copy the IDs from the filter parameters of an Amazon search URL.