Amazon Rankings — DataBlue API Docs

Amazon Rankings Endpoint

Return ranked Amazon listings for a query or category URL.

Getting Started

Send your API key as a bearer token. Start with the smallest request below.

Run Amazon Rankings

Send the smallest useful request and read the structured response.

curl -X POST "https://api.datablue.dev/v1/data/amazon/rankings" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "query": "kiro beauty",
  "domain": "amazon.in",
  "num_results": 20,
  "page": 1
}'

Example response

{
  "success": true,
  "query": "kiro beauty",
  "domain": "amazon.in",
  "total_results": "32",
  "pages_fetched": 1,
  "time_taken": 2.9,
  "products": [
    {
      "position": 1,
      "asin": "B0XXXXXXX1",
      "title": "Kiro Beauty Lipstick",
      "price": "₹799",
      "rating": 4.3
    }
  ]
}

Options

Query and Target

Set the search term, identifier, or source URL that defines the request.

curl -X POST "https://api.datablue.dev/v1/data/amazon/rankings" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "query": "web scraping tools",
  "domain": "amazon.in",
  "num_results": 20,
  "page": 1,
  "url": "https://example.com/products/widget"
}'

Example response

{
  "success": true,
  "query": "kiro beauty",
  "domain": "amazon.in",
  "total_results": "32",
  "pages_fetched": 1,
  "time_taken": 2.9,
  "products": [
    {
      "position": 1,
      "asin": "B0XXXXXXX1",
      "title": "Kiro Beauty Lipstick",
      "price": "₹799",
      "rating": 4.3
    }
  ]
}

Results and Pagination

Control how many records or pages are returned.

curl -X POST "https://api.datablue.dev/v1/data/amazon/rankings" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "query": "kiro beauty",
  "domain": "amazon.in",
  "num_results": 20,
  "page": 1,
  "page_limit": 10
}'

Example response

{
  "success": true,
  "query": "kiro beauty",
  "domain": "amazon.in",
  "total_results": "32",
  "pages_fetched": 1,
  "time_taken": 2.9,
  "products": [
    {
      "position": 1,
      "asin": "B0XXXXXXX1",
      "title": "Kiro Beauty Lipstick",
      "price": "₹799",
      "rating": 4.3
    }
  ]
}

Location and Language

Localize results with country, language, coordinates, or delivery-location fields.

curl -X POST "https://api.datablue.dev/v1/data/amazon/rankings" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "query": "kiro beauty",
  "domain": "amazon.in",
  "num_results": 20,
  "page": 1,
  "country": "us",
  "postal_code": "10001"
}'

Example response

{
  "success": true,
  "query": "kiro beauty",
  "domain": "amazon.in",
  "total_results": "32",
  "pages_fetched": 1,
  "time_taken": 2.9,
  "products": [
    {
      "position": 1,
      "asin": "B0XXXXXXX1",
      "title": "Kiro Beauty Lipstick",
      "price": "₹799",
      "rating": 4.3
    }
  ]
}

Filters and Sorting

Narrow or order the returned records.

curl -X POST "https://api.datablue.dev/v1/data/amazon/rankings" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "query": "kiro beauty",
  "domain": "amazon.in",
  "num_results": 20,
  "page": 1,
  "sort_by": "example",
  "min_price": 10,
  "max_price": 10,
  "prime_only": false
}'

Example response

{
  "success": true,
  "query": "kiro beauty",
  "domain": "amazon.in",
  "total_results": "32",
  "pages_fetched": 1,
  "time_taken": 2.9,
  "products": [
    {
      "position": 1,
      "asin": "B0XXXXXXX1",
      "title": "Kiro Beauty Lipstick",
      "price": "₹799",
      "rating": 4.3
    }
  ]
}

Response

Read success first, then consume the endpoint-specific records and pagination fields shown below.

Error Handling

Handle 401 for authentication, 422 for invalid input, 429 for limits, and retry only transient failures.

Parameters

Name	Type	Requirement	Description
query	string	Optional	Amazon product search query. Required unless url is supplied.
url	string	Optional	Amazon search or category URL. Required unless query is supplied.
domain	string	Optional	Amazon domain.
country	string	Optional	Delivery or marketplace country code.
postal_code	string	Optional	Delivery postal code.
num_results	number	Optional	Maximum ranked products to return (1-200).
page	number	Optional	Starting page (1-20).
page_limit	number	Optional	Maximum listing pages to fetch (1-20).
sort_by	string	Optional	Sort order: relevance, popularity, price_low, price_high, rating, newest.
min_price	number	Optional	Minimum price filter.
max_price	number	Optional	Maximum price filter.
prime_only	boolean	Optional	Filter to Prime-eligible products only.

Response fields

Field	Type	Description
success	boolean	Whether ranking extraction completed.
products	array	Ranked listing rows with position, ASIN, title, URL, price, rating, review count, image, sponsored, and badge fields.
total_results	string	Amazon total results text when visible.
pages_fetched	number	Number of pages fetched.
job_id / status_url	string	Present only when unfinished multi-page work returns HTTP 202 for polling.
time_taken	number	API response time in seconds.

Request and response

curl -X POST "https://api.datablue.dev/v1/data/amazon/rankings" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "query": "kiro beauty",
  "domain": "amazon.in",
  "num_results": 20,
  "page": 1
}'

Example response

{
  "success": true,
  "query": "kiro beauty",
  "domain": "amazon.in",
  "total_results": "32",
  "pages_fetched": 1,
  "time_taken": 2.9,
  "products": [
    {
      "position": 1,
      "asin": "B0XXXXXXX1",
      "title": "Kiro Beauty Lipstick",
      "price": "₹799",
      "rating": 4.3
    }
  ]
}