Документация 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",
  "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 }
}

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 — для наших сбоев.

Язык отображения

Каждый эндпоинт принимает необязательный параметр language:

С language=native текстовые поля (название, категория и бренд, condition_text, тексты о доставке) возвращаются на языке маркетплейса, а нормализованные поля (слаги состояний, цены, даты, единицы измерения) остаются каноническими, поэтому фильтры по состоянию и ваш парсинг продолжают работать без изменений. Запрошенный язык дублируется в meta.language.

Запрос native для маркетплейса без поддержки родного языка возвращает HTTP 400 с кодом ошибки NATIVE_LANGUAGE_NOT_SUPPORTED и не тарифицируется.

Пример (итальянская карточка товара на итальянском)

curl -H "x-api-key: YOUR_API_KEY" \
  "https://api.asinspotlight.com/v1/product?asin=B0BWSCJ13H&marketplace=it&language=native"

Акции и скидки

Данные товара и элементы списковых страниц содержат объект promotion, описывающий состояние скидки на предложение: бейдж акции, который Amazon показывает только пока акция активна, и зачёркнутые справочные цены, относительно которых считается скидка. Один запрос отвечает на вопрос «действует ли сейчас акция на этот товар и насколько глубока скидка» без истории цен.

promotion присутствует в данных /v1/product и в каждом элементе shallow_parts[] списковых страниц (поиск, категория, бестселлеры). Значение null означает, что на странице нет ни бейджа акции, ни зачёркнутой цены: товар продаётся по обычной цене.

"promotion": {
  "deal": {
    "kind": "limited_time",
    "label": "Limited time deal",
    "deal_id": "amzn1.deal.b12c9bd2",
    "ends_at": "2026-08-16T04:00:00Z",
    "ends_on": "2026-08-16",
    "ends_in_days": 15,
    "ends_on_text": null
  },
  "list_price": {
    "amount": 199.99,
    "label": "List Price:",
    "savings_amount": 50.99,
    "savings_percent": 25.0
  },
  "lowest_price_30_days": null
}

Три части объекта независимы: обычная уценка может показываться зачёркнутой ценой без бейджа, а акция с бейджем может вовсе не иметь справочной цены.

Бейдж deal

Сигналом служит само присутствие бейджа: Amazon показывает его только пока акция идёт, поэтому непустой deal означает, что акция активна в момент запроса, а null означает, что нет. Вопрос «закончилась ли акция?» решается одним запросом вместо анализа истории цен.

Справочные цены

list_price и lowest_price_30_days имеют одинаковую структуру:

list_price содержит основную зачёркнутую цену. Обычно это рекомендованная цена производителя, но когда её нет, Amazon подставляет в тот же слот типичную, медианную или прежнюю цену («Typical:», «Prezzo mediano:», «Ancien prix :»); только формулировка label говорит, какая именно цена перед вами. lowest_price_30_days содержит минимальную цену за последние 30 дней, которую европейские витрины обязаны показывать рядом со скидкой (директива Omnibus); за пределами ЕС поле отсутствует.

На списковых страницах. Элемент выдачи поиска, категории или бестселлеров представляет собой краткий тайл, поэтому его promotion содержит сокращённую версию того, что отдаёт карточка товара: тип и текст бейджа (kind, label) и зачёркнутая цена присутствуют, но нет deal_id и ends_on_text, ends_at появляется только у бейджей с обратным отсчётом (они сами указывают свой дедлайн), а ends_in_days всегда null. Когда нужны идентификатор акции или точный дедлайн, запросите /v1/product по этому ASIN.

Купоны учитываются отдельно. Купон, который нужно «применить», представляет собой другой механизм скидки и остаётся в собственном поле coupon ({"unit": "percent", "value": 15} или {"unit": "currency", "value": 5}) как в данных товара, так и в элементах списковых страниц, и означает одно и то же в обоих случаях: value — это размер скидки, а не цена, которая останется после её применения. Купон с percent содержит процент, купон с currency — сумму в местной валюте маркетплейса. В поле price купон не учитывается, итоговую цену вы считаете сами. Товар может одновременно иметь и купон, и акцию.

Эндпоинты

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,
    "promotion": {
      "deal": {
        "kind": "limited_time",
        "label": "Limited time deal",
        "deal_id": "amzn1.deal.b12c9bd2",
        "ends_at": "2026-08-16T04:00:00Z",
        "ends_on": "2026-08-16",
        "ends_in_days": 15,
        "ends_on_text": null
      },
      "list_price": {
        "amount": 39.99,
        "label": "List Price:",
        "savings_amount": 10.00,
        "savings_percent": 25.0
      },
      "lowest_price_30_days": null
    },
    "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://api.asinspotlight.com/v1/product?asin=B0B3ZD8QXJ&marketplace=us",
    "timestamp": "2026-04-03T12:00:00.000Z",
    "request_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

promotion показывает, действует ли на предложение акция, и зачёркнутые цены, относительно которых считается скидка; null означает, что товар продаётся по обычной цене. См. Акции и скидки.

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.

Рекомендуемое предложение (Buy Box) помечено флагом is_pinned. В ответе его несёт не более одного предложения, поэтому победителя Buy Box можно прочитать напрямую, а не выводить из цены. Позиция в массиве не заменяет этот флаг: в ответе может быть много предложений и ни одного помеченного, что означает, что Amazon не показал рекомендуемое предложение для этого ASIN. Фильтр condition также может убрать помеченное предложение из ответа, поскольку Amazon возвращает рекомендуемое предложение независимо от запрошенного состояния.

Каждое предложение содержит массив delivery с обещаниями доставки, которые показал Amazon. Значение kind равно standard для основного слота и fastest для дополнительного, который Amazon также использует для рекламы Prime, поэтому его стоит читать как «другой показанный вариант», а не как гарантированно более быструю доставку. Поля date_min / date_max дают обещанный интервал в виде абсолютных дат, а days_min / days_max выражают то же обещание в целых днях от даты запроса, где 0 означает доставку сегодня. Если обещание не удалось разобрать в дату, все поля дат и дней равны null, а не подставному числу, поэтому null следует трактовать как «неизвестно». Чтобы отличить бесплатную доставку от стоимости, которую не удалось разобрать, используйте is_free, а не shipping_price. Поле text содержит дословную формулировку 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,
        "is_pinned": true,
        "delivery": [
          {
            "kind": "standard",
            "days_min": 8,
            "days_max": 8,
            "date_min": "2026-07-25",
            "date_max": "2026-07-25",
            "is_free": true,
            "text": "FREE delivery Saturday, July 25."
          },
          {
            "kind": "fastest",
            "days_min": 5,
            "days_max": 7,
            "date_min": "2026-07-22",
            "date_max": "2026-07-24",
            "is_free": null,
            "text": "Or fastest delivery July 22 - 24."
          }
        ]
      },
      {
        "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,
        "is_pinned": false,
        "delivery": [
          {
            "kind": "standard",
            "days_min": 6,
            "days_max": 11,
            "date_min": "2026-07-23",
            "date_max": "2026-07-28",
            "is_free": false,
            "text": "$3.99 delivery July 23 - 28."
          }
        ]
      }
    ]
  },
  "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",
        "index_on_page": 1,
        "page_number": 1,
        "price": 39.99,
        "shipping": 0,
        "is_prime": true,
        "rating": 4.6,
        "reviews": 58800,
        "bought_past_month": 20000,
        "in_stock": true,
        "coupon": null,
        "image_url": "https://m.media-amazon.com/images/I/...",
        "promotion": {
          "deal": {
            "kind": "limited_time",
            "label": "Limited time deal",
            "deal_id": null,
            "ends_at": null,
            "ends_on": null,
            "ends_in_days": null,
            "ends_on_text": null
          },
          "list_price": {
            "amount": 49.99,
            "label": "List:",
            "savings_amount": 10.00,
            "savings_percent": 20.0
          },
          "lowest_price_30_days": null
        }
      }
    ]
  },
  "meta": { "..." : "..." }
}

Каждый элемент также содержит promotion тайла (бейдж акции и зачёркнутую справочную цену) в сокращённом виде, описанном в разделе Акции и скидки: без deal_id, ends_at только у бейджей с обратным отсчётом, ends_in_days всегда null. Поле присутствует в shallow_parts[] на всех списковых страницах (поиск, категория, бестселлеры).

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.