AI Integration Guide

https://www.asinspotlight.com/scraping-api-docs/openapi.json

export ASINSPOTLIGHT_API_KEY="sk_live_..."

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

{
  "success": true,
  "page_type": "product",
  "data": {
    "asin": "B0B3ZD8QXJ",
    "title": "Soundcore Q20i Headphones",
    "bb_price": 39.99,
    "rating": 4.6,
    "reviews": 58800,
    "bsr": 12,
    "in_stock": true,
    "bought_past_month": 20000
  },
  "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}
  }
}

Build a script that compares prices for a list of ASINs across multiple Amazon marketplaces using the ASINSpotlight Scraping API.

OpenAPI spec: https://www.asinspotlight.com/scraping-api-docs/openapi.json
API base URL: https://api.asinspotlight.com (note: api., not www.)
Auth: API key in the `x-api-key` header (read from env var `ASINSPOTLIGHT_API_KEY`).
Endpoint: GET /v1/product?asin=...&marketplace=...

Inputs:
  - List of ASINs (e.g., ["B0B3ZD8QXJ", "B0CQXMXJC5"])
  - List of marketplace codes (e.g., ["us", "uk", "de"])

For each (asin, marketplace) pair, fetch product details and collect: asin, marketplace, title, bb_price, in_stock, rating.

Output: CSV with columns asin, marketplace, title, bb_price, in_stock, rating.

Constraints:
  - Stop early and surface the error if a request returns 401, 429, or 5xx.
  - After each successful response, read `meta.usage.requests_remaining` and abort if it drops below 50.
  - Don't run more than 5 requests in parallel — the account has a parallel-request limit.

Build a daily keyword tracker that records the top 10 ASINs for a list of keywords using the ASINSpotlight Scraping API.

OpenAPI spec: https://www.asinspotlight.com/scraping-api-docs/openapi.json
API base URL: https://api.asinspotlight.com (note: api., not www.)
Auth: API key in the `x-api-key` header (env var `ASINSPOTLIGHT_API_KEY`).
Endpoint: GET /v1/search?keyword=...&marketplace=...

For each keyword, fetch the search results page, take the first 10 entries from `data.shallow_parts`, and write one row per (keyword, rank, asin, title, price, rating, reviews, bought_past_month, captured_at).

Storage: append to a SQLite table `keyword_rankings` keyed on (keyword, marketplace, captured_at, rank).

Run cadence: once per day, intended to be invoked by cron.

Don't:
  - Don't try to "follow up" with a /v1/product call for each search result — `shallow_parts` already contains everything we need.
  - Don't paginate past page 1; we only care about the top 10.
  - Don't retry on 4xx errors; only on 5xx and `CAPTCHA_DETECTED` (with backoff).

Build a Buy Box ownership monitor for a watchlist of ASINs using the ASINSpotlight Scraping API.

OpenAPI spec: https://www.asinspotlight.com/scraping-api-docs/openapi.json
API base URL: https://api.asinspotlight.com (note: api., not www.)
Auth: API key in the `x-api-key` header (env var `ASINSPOTLIGHT_API_KEY`).
Endpoint: GET /v1/offers?asin=...&marketplace=...

For each ASIN, call /v1/offers and identify the current Buy Box owner — the seller in `data.product_sellers_info` whose price equals the lowest `price + shipping_price` and who has `is_fba: true` (the typical Amazon Buy Box rule).

Compare against the previously recorded owner stored in a JSON file `buybox_state.json` keyed by asin. When the owner changes, log a line to stdout with: timestamp, asin, previous owner, new owner, new price.

Run as a loop with a 10-minute interval between full sweeps.

Don't:
  - Don't conflate /v1/product and /v1/offers — `/v1/product` returns the Buy Box price but not the full seller list. You need /v1/offers for ownership.
  - Don't ignore `stock_qty: 0` sellers; filter those out before picking a winner.
  - Don't run all watchlist requests at once; respect the parallel limit (default ~5).

Build an ASIN-list batch refresh that updates cached product data using the ASINSpotlight Scraping API.

OpenAPI spec: https://www.asinspotlight.com/scraping-api-docs/openapi.json
API base URL: https://api.asinspotlight.com (note: api., not www.)
Auth: API key in the `x-api-key` header (env var `ASINSPOTLIGHT_API_KEY`).
Endpoint: GET /v1/product?asin=...&marketplace=...

Inputs: a JSON file `watchlist.json` of `{asin, marketplace, last_refreshed_at}` records.

Refresh strategy:
  1. Sort the list by `last_refreshed_at` ascending (oldest first).
  2. For each entry, call /v1/product. On a successful 200, write the response data and the new timestamp back to the file.
  3. After every response, read `meta.usage.requests_remaining`. If it would dip below the configured floor (default 1000), stop the run and log how many entries were skipped.
  4. Run requests in batches of 5 in parallel.

Error handling:
  - `PAGE_NOT_FOUND` (404): mark the entry as `status: gone` and continue. PAGE_NOT_FOUND consumes 1 credit — that's expected.
  - `CAPTCHA_DETECTED` (503): retry up to 3 times with exponential backoff.
  - `RATE_LIMIT_EXCEEDED` (429): wait 30 seconds and retry the same entry.
  - Any other error: log and stop.

Build a search-to-database pipeline that captures the full first 5 pages of results for a keyword using the ASINSpotlight Scraping API.

OpenAPI spec: https://www.asinspotlight.com/scraping-api-docs/openapi.json
API base URL: https://api.asinspotlight.com (note: api., not www.)
Auth: API key in the `x-api-key` header (env var `ASINSPOTLIGHT_API_KEY`).

The /v1/search endpoint returns page 1 by default. To walk further pages, use POST /v1/scrape with an explicit Amazon search URL containing `&page=N`:

  POST /v1/scrape
  Body: {"url": "https://www.amazon.com/s?k=wireless+headphones&page=2", "marketplace": "us"}

Steps:
  1. Call GET /v1/search?keyword=...&marketplace=us — this is page 1. Read `data.last_page_number` to know the upper bound.
  2. For pages 2..min(5, last_page_number), call POST /v1/scrape with the page-N URL.
  3. Append every entry to a Postgres table `search_results` with columns (keyword, marketplace, page, rank, asin, title, price, rating, reviews, captured_at).

Don't:
  - Don't try `?page=2` on the typed /v1/search endpoint — that endpoint doesn't accept a `page` parameter.
  - Don't fetch past `last_page_number` — Amazon will return an empty result set and you'll waste credits.

---
description: ASINSpotlight Amazon Scraping API
globs: ["**/*.py", "**/*.ts", "**/*.js"]
alwaysApply: false
---

When working with the ASINSpotlight Scraping API:

- Spec: https://www.asinspotlight.com/scraping-api-docs/openapi.json
- Auth: `x-api-key` header, value from env var `ASINSPOTLIGHT_API_KEY`
- Base URL: https://api.asinspotlight.com/v1
- Endpoints: /product (asin, marketplace), /search (keyword, marketplace), /offers (asin, marketplace), POST /scrape (body: {url, marketplace})
- Read `meta.usage.requests_remaining` after every successful response
- Cap parallelism at 5 unless told otherwise
- For search pagination beyond page 1, use POST /scrape with an explicit Amazon URL containing `&page=N`

{
  "docs": [
    {
      "title": "ASINSpotlight Scraping API",
      "startUrl": "https://www.asinspotlight.com/scraping-api-docs/openapi.json",
      "rootUrl": "https://www.asinspotlight.com/scraping-api-docs/openapi.json"
    }
  ]
}

for (const asin of asins) {
  const res = await fetchProduct(asin);
  if (!res.success) handleError(res.error.code);
  if (res.meta.usage.requests_remaining < FLOOR) break;
  store(res.data);
}