Scraping API Documentation

Base URL

https://api.asinspotlight.com/v1

Authentication

All requests require an API key passed in the x-api-key header:

curl -H "x-api-key: YOUR_API_KEY" "https://api.asinspotlight.com/v1/product?asin=B0B3ZD8QXJ"

Response Metadata

Every successful response carries a meta object with per-request metadata. The meta.usage block lets you drive quota-aware loops without polling a separate endpoint:

"meta": {
  "marketplace": "us",
  "timing_ms": 1842,
  "request_url": "https://www.amazon.com/dp/B0B3ZD8QXJ",
  "timestamp": "2026-05-03T10:14:22.318Z",
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "usage": { "requests_consumed": 1, "requests_remaining": 49999 }
}

requests_consumed is 1 for any successful scrape (HTTP 200) — including not-found results where found is false, since the page was still fetched and parsed; 0 for any failure. meta.usage is also included on 429 rate-limit and quota-exceeded errors so you can read remaining credits even when a request is rejected.

Found vs. Not Found

Status codes reflect our service health, not what's on Amazon. Every successful response carries a top-level found boolean:

• found: true — the entity was found; data holds the payload.
• found: false — the scrape succeeded but the entity isn't on Amazon (invalid ASIN/seller, removed listing). data is null, the HTTP status is still 200, and the request still counts as one credit.

Branch on found, not on the HTTP status, to tell "found" from "not found". Reserve 4xx for your request errors and 5xx for our failures.

Endpoints

GET /v1/product

Retrieve product details by ASIN.

Parameters

Example

curl -H "x-api-key: YOUR_API_KEY" \
  "https://api.asinspotlight.com/v1/product?asin=B0B3ZD8QXJ&marketplace=us"

Response

{
  "success": true,
  "found": true,
  "page_type": "product",
  "data": {
    "asin": "B0B3ZD8QXJ",
    "title": "Product Title",
    "buybox": true,
    "bb_price": 29.99,
    "rating": 4.5,
    "reviews": 1234,
    "bsr": 5678,
    "in_stock": true,
    "is_prime": true,
    "brand": { "name": "BrandName", "url": "/stores/BrandName" },
    "category": { "name": "Electronics", "url": "/b?node=123" },
    "image_url": "https://m.media-amazon.com/images/I/...",
    "sellers_all": 5,
    "bought_past_month": 1000
  },
  "meta": {
    "marketplace": "us",
    "timing_ms": 2340,
    "request_url": "https://www.amazon.com/dp/B0B3ZD8QXJ",
    "timestamp": "2026-04-03T12:00:00.000Z",
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "usage": { "requests_consumed": 1, "requests_remaining": 49999 }
  }
}

bought_past_month is coerced from Amazon's Xk+ bought in past month label to an integer (e.g. 2K+ → 2000).

GET /v1/offers

Retrieve every seller offer for a product — the full Buy Box panel and All Offers Display — with each offer's condition, price, shipping, fulfillment method, seller rating, and stock.

Parameters

Filtering by condition

By default (condition=all) offers of every condition are returned. Pass condition to narrow the result to a single condition or used tier:

The filter is applied to each offer's resolved condition, so the response contains only offers of the requested condition, and fba_count / fbm_count / sold_by_amazon reflect the filtered set. Each request counts as one credit regardless of the filter.

Example

curl -H "x-api-key: YOUR_API_KEY" \
  "https://api.asinspotlight.com/v1/offers?asin=B0B3ZD8QXJ&marketplace=us"

Example (used offers only)

curl -H "x-api-key: YOUR_API_KEY" \
  "https://api.asinspotlight.com/v1/offers?asin=B0B3ZD8QXJ&marketplace=us&condition=used"

Response

Each entry in product_sellers_info carries a normalized condition (new, used_like_new, used_very_good, used_good, used_acceptable, or collectible) and the verbatim condition_text heading Amazon shows for that offer. condition is null when Amazon's heading is absent or not recognized (e.g. Renewed/Refurbished, or some non-English wordings) — the raw label is still available in condition_text. seller_id is null for offers sold directly by Amazon.

{
  "success": true,
  "found": true,
  "page_type": "offers",
  "data": {
    "sold_by_amazon": true,
    "fba_count": 3,
    "fbm_count": 2,
    "product_sellers_info": [
      {
        "name": "Amazon.com",
        "price": 29.99,
        "shipping_price": 0,
        "is_fba": true,
        "is_amazon": true,
        "stock_qty": 100,
        "rating_percent": 95,
        "reviews_count": 50000,
        "condition": "new",
        "condition_text": "New",
        "seller_id": null,
        "domain": "com",
        "is_just_launched": false
      },
      {
        "name": "ThriftBooks",
        "price": 18.50,
        "shipping_price": 3.99,
        "is_fba": false,
        "is_amazon": false,
        "stock_qty": 5,
        "rating_percent": 97,
        "reviews_count": 4200,
        "condition": "used_like_new",
        "condition_text": "Used - Like New",
        "seller_id": "A3XYZ123456",
        "domain": "com",
        "is_just_launched": false
      }
    ]
  },
  "meta": { "..." : "..." }
}

GET /v1/search

Search products by keyword.

Parameters

Pagination

Pass page=N to fetch deeper pages of the same query. The response's data.current_page and data.last_page_number tell you where you are and how many pages Amazon exposes for that query. Each paginated request counts as one credit.

Example

curl -H "x-api-key: YOUR_API_KEY" \
  "https://api.asinspotlight.com/v1/search?keyword=wireless+headphones&marketplace=us"

Example (page 2)

curl -H "x-api-key: YOUR_API_KEY" \
  "https://api.asinspotlight.com/v1/search?keyword=wireless+headphones&marketplace=us&page=2"

Response

{
  "success": true,
  "found": true,
  "page_type": "search",
  "data": {
    "title": "wireless headphones",
    "current_page": 1,
    "last_page_number": 20,
    "total_results_count": 10000,
    "shallow_parts": [
      {
        "asin": "B0CQXMXJC5",
        "title": "Soundcore Q20i Headphones",
        "price": 39.99,
        "rating": 4.6,
        "reviews": 58800,
        "bought_past_month": 20000,
        "in_stock": true,
        "image_url": "https://m.media-amazon.com/images/I/..."
      }
    ]
  },
  "meta": { "..." : "..." }
}

GET /v1/seller

Retrieve a seller storefront profile by seller ID.

Parameters

Example

curl -H "x-api-key: YOUR_API_KEY" \
  "https://api.asinspotlight.com/v1/seller?sellerId=A1PXYTJNWCR133&marketplace=us"

Response

Returns the seller name, feedback rating and positive-feedback percentage over the last 12 months, total rating count, the storefront link, and the Detailed Seller Information block (legal business name and address) when Amazon publishes it. An invalid seller ID returns 200 with found: false and data: null.

{
  "success": true,
  "found": true,
  "page_type": "seller",
  "data": {
    "seller_id": "A1PXYTJNWCR133",
    "name": "Lovinio",
    "storefront_url": "/s?ie=UTF8&marketplaceID=ATVPDKIKX0DER&me=A1PXYTJNWCR133",
    "rating": 3.4,
    "positive_percent": 59,
    "ratings_count": 217,
    "business_name": "Lovinio Inc",
    "business_address": ["4652 Eagle Falls Pl", "Tampa", "FL", "33619", "US"]
  },
  "meta": { "..." : "..." }
}

POST /v1/scrape

Scrape any Amazon URL. The page type is auto-detected.

Body (JSON)

Example

curl -X POST -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://www.amazon.com/s?k=laptop+stand", "marketplace": "us"}' \
  "https://api.asinspotlight.com/v1/scrape"

Response

The data shape matches the detected page_type. For product, search, offers, and seller it matches the typed-endpoint payloads above. category, bestseller, storefront, and reviews return a structured payload tailored to the page. A not-found page returns found: false and data: null.

{
  "success": true,
  "found": true,
  "page_type": "search",
  "data": { "...": "..." },
  "meta": { "...": "..." }
}

Supported Marketplaces

Error Responses

All errors follow a consistent format:

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description"
  }
}

429 rate-limit and quota responses also include a top-level meta.usage block so you can read remaining credits even when the request is rejected.

A missing entity (invalid ASIN/seller, removed listing) is not an error — it returns 200 with found: false and data: null, and counts as one credit. See Found vs. Not Found.