Amazon Rankings

Return ranked Amazon listing rows for a query or search/category URL with marketplace, delivery, pagination, sorting, and price filters.

Execution Model

Live request

Runtime depends on endpoint, target, pagination, rendering mode, and active plan limits.

Credit Weight

Live catalog

Current weights are managed from the Data API Weights admin table and shown on pricing before use.

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, 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.
time_taken	number	API response time in seconds.

cURL Example

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
}'

System Responses

200 OK

Request processed successfully.

401 UNAUTHORIZED

Missing or invalid API key.

429 RATE LIMIT

System capacity exceeded.

500 SYSTEM FAILURE

Internal core exception.

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
    }
  ]
}