Документация Scraping API

Базовый URL

https://api.asinspotlight.com/v1

Аутентификация

Все запросы требуют API-ключ в заголовке x-api-key:

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

Метаданные ответа

Каждый успешный ответ содержит объект meta с метаданными по конкретному запросу. Блок meta.usage позволяет строить циклы с учётом квоты, не обращаясь к отдельному эндпоинту:

"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 равно 1 для любого успешного скрейпинга (HTTP 200) — включая результаты «не найдено», где found равно false, поскольку страница всё равно была загружена и разобрана; 0 для любой неудачи. Блок meta.usage также включается в ошибки 429 (превышение лимита запросов и квоты), чтобы вы могли узнать остаток кредитов даже при отклонённом запросе.

Found vs. Not Found

Коды состояния отражают работоспособность нашего сервиса, а не содержимое Amazon. Каждый успешный ответ содержит логическое поле верхнего уровня found:

• found: true — сущность найдена; data содержит данные.
• found: false — скрейпинг выполнен успешно, но сущность отсутствует на Amazon (неверный ASIN/продавец, удалённый листинг). data равно null, HTTP-статус по-прежнему 200, и запрос всё равно списывает один кредит.

Ориентируйтесь на found, а не на HTTP-статус, чтобы отличить «найдено» от «не найдено». Оставьте 4xx для ошибок ваших запросов, а 5xx — для наших сбоев.

Эндпоинты

GET /v1/product

Получить информацию о товаре по ASIN.

Параметры

Пример

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

Ответ

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

GET /v1/offers

Получить все предложения продавцов для товара — полную панель Buy Box и список всех предложений (All Offers Display) — с указанием для каждого предложения состояния, цены, стоимости доставки, способа исполнения заказа, рейтинга продавца и наличия на складе.

Параметры

Фильтрация по состоянию

По умолчанию (condition=all) возвращаются предложения любого состояния. Передайте condition, чтобы ограничить результат одним состоянием или градацией состояния «бывший в употреблении»:

Фильтр применяется к итоговому condition каждого предложения, поэтому ответ содержит только предложения запрошенного состояния, а fba_count / fbm_count / sold_by_amazon отражают отфильтрованный набор. Каждый запрос списывает один кредит независимо от фильтра.

Пример

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

Пример (только б/у предложения)

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

Ответ

Каждая запись в product_sellers_info содержит нормализованное состояние condition (new, used_like_new, used_very_good, used_good, used_acceptable или collectible) и дословный заголовок condition_text, который Amazon показывает для этого предложения. condition равно null, когда заголовок Amazon отсутствует или не распознан (например, Renewed/Refurbished или некоторые неанглийские формулировки) — исходная подпись по-прежнему доступна в condition_text. seller_id равно null для предложений, продаваемых напрямую 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

Поиск товаров по ключевому слову.

Параметры

Пример

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

Ответ

{
  "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

Получить профиль витрины продавца по его ID.

Параметры

Пример

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

Ответ

Возвращает имя продавца, рейтинг отзывов и долю положительных отзывов за последние 12 месяцев, общее количество оценок, ссылку на витрину, а также блок «Detailed Seller Information» (юридическое название компании и адрес), если Amazon его публикует. Неверный ID продавца возвращает 200 с found: false и 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

Извлечь данные с любой страницы Amazon. Тип страницы определяется автоматически.

Тело запроса (JSON)

Пример

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"

Ответ

Форма data соответствует определённому page_type. Для product, search, offers и seller она совпадает с данными типизированных эндпоинтов выше. category, bestseller, storefront и reviews возвращают структурированные данные, адаптированные под страницу. Страница «не найдено» возвращает found: false и data: null.

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

Поддерживаемые маркетплейсы

Ответы с ошибками

Все ошибки возвращаются в едином формате:

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Описание ошибки"
  }
}

Отсутствующая сущность (неверный ASIN/продавец, удалённый листинг) не является ошибкой — возвращается 200 с found: false и data: null, и списывается один кредит. См. Found vs. Not Found.