Гайд по интеграции с ИИ

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,
  "found": 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",
    "language": "en",
    "timing_ms": 1842,
    "request_url": "https://api.asinspotlight.com/v1/product?asin=B0B3ZD8QXJ&marketplace=us",
    "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=...&condition=new

For each ASIN, call /v1/offers with `condition=new` and identify the current Buy Box owner: the seller in `data.product_sellers_info` whose `is_pinned` is `true`. At most one offer per response carries that flag, so read the owner from it directly instead of inferring it from price. If no offer is pinned (Amazon rendered no featured offer for that ASIN), fall back to the lowest `price + shipping_price` among `is_fba: true` sellers.

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 compare used and new offers as interchangeable — each offer carries a `condition`; the Buy Box is a `new` offer, so pass `condition=new` (or filter on `condition`) before picking the lowest price.
  - Don't ignore `stock_qty: 0` sellers; filter those out before picking a winner.
  - Don't treat the first entry in `product_sellers_info` as the Buy Box owner; array order does not encode it. Use `is_pinned`.
  - 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:
  - Not found (HTTP 200 with `found: false` and `data: null`): mark the entry as `status: gone` and continue. A not-found result still 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 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`).
Endpoint: GET /v1/search?keyword=...&marketplace=...&page=N

Steps:
  1. Call GET /v1/search?keyword=...&marketplace=us (page 1 by default). Read `data.last_page_number` to know the upper bound.
  2. For pages 2..min(5, last_page_number), call the same endpoint with `page=N`.
  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 fetch past `last_page_number`: Amazon returns an empty result set and you'll waste credits.
  - Don't run more than 5 requests in parallel; the account has a parallel-request limit.

---
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, language), /search (keyword, marketplace, page, language), /offers (asin, marketplace, condition, language), /seller (sellerId, marketplace, language), POST /scrape (body: {url, marketplace, language})
- Read `meta.usage.requests_remaining` after every successful response
- A missing entity returns HTTP 200 with `found: false` and `data: null` — branch on `found`, not the status code
- Optional `language` param: `en` (default) or `native` (the marketplace's own language; currently `it`/`fr`/`de`/`es`, unsupported combos return 400 `NATIVE_LANGUAGE_NOT_SUPPORTED`)
- Cap parallelism at 5 unless told otherwise
- For search pagination beyond page 1, pass `page=N` to /search

{
  "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);
}