Documentación de Scraping API

URL Base

https://api.asinspotlight.com/v1

Autenticación

Todas las solicitudes requieren una clave API en el encabezado x-api-key:

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

Encontrado vs. No encontrado

Los códigos de estado reflejan el estado de nuestro servicio, no lo que hay en Amazon. Cada respuesta exitosa incluye un booleano found de nivel superior:

• found: true — la entidad fue encontrada; data contiene la carga útil.
• found: false — el scraping fue exitoso pero la entidad no está en Amazon (ASIN/vendedor inválido, listado eliminado). data es null, el estado HTTP sigue siendo 200, y la solicitud cuenta igualmente como un crédito.

Ramifica según found, no según el estado HTTP, para distinguir «encontrado» de «no encontrado». Reserva 4xx para tus errores de solicitud y 5xx para nuestros fallos.

Idioma de visualización

Cada endpoint acepta un parámetro opcional language:

Con language=native, los campos de texto libre (título, nombres de categoría y marca, condition_text, textos de entrega) vuelven en el idioma del marketplace, mientras que los campos normalizados (slugs de condición, precios, fechas, unidades) permanecen canónicos, de modo que los filtros por condición y tu parsing siguen funcionando sin cambios. El idioma solicitado se refleja en meta.language.

Solicitar native en un marketplace sin soporte nativo devuelve HTTP 400 con el código de error NATIVE_LANGUAGE_NOT_SUPPORTED y no se factura.

Ejemplo (página de producto italiana en italiano)

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

Promociones y descuentos

Los datos de producto y las entradas de páginas de listado incluyen un objeto promotion que describe el estado del descuento de la oferta: la insignia de oferta que Amazon muestra solo mientras la promoción está activa, y los precios de referencia tachados contra los que se mide el descuento. Una sola petición responde a "¿este producto está en oferta ahora mismo y de cuánto es el descuento?", sin necesidad de histórico de precios.

promotion aparece en los datos de /v1/product y en cada entrada de shallow_parts[] de las páginas de listado (búsqueda, categoría, más vendidos). Es null cuando la página no muestra ni insignia de oferta ni precio tachado, lo que simplemente significa que el producto se vende a su precio normal.

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

Las tres partes son independientes: una rebaja ordinaria puede mostrarse tachada contra un precio de lista sin insignia alguna, y una oferta con insignia no tiene por qué llevar precio de referencia.

La insignia deal

La presencia es la señal: Amazon muestra la insignia solo mientras la oferta está en marcha, así que un deal no nulo significa que la promoción está activa en el momento de la petición, y null significa que no lo está. Eso hace que "¿ha terminado la promoción?" se responda con una sola petición en lugar de con una serie temporal de precios.

Precios de referencia

list_price y lowest_price_30_days comparten la misma estructura:

list_price es el precio tachado principal. Normalmente es el precio de lista del fabricante, pero Amazon rellena el mismo hueco con un precio típico, mediano o anterior cuando no tiene precio de lista que mostrar ("Typical:", "Prezzo mediano:", "Ancien prix :"); solo el texto de label indica cuál de ellos es. lowest_price_30_days es el precio más bajo de los últimos 30 días, que las tiendas de la UE deben mostrar junto a un descuento (la Directiva Ómnibus); fuera de la UE no aparece.

En páginas de listado. Una entrada de búsqueda, categoría o más vendidos es una tarjeta resumida, así que su promotion es la mitad superficial de lo que devuelve una página de producto: la oferta está identificada (kind, label) y el precio tachado está presente, pero no hay deal_id ni ends_on_text, ends_at aparece solo en insignias con cuenta atrás (que declaran su propio objetivo) y ends_in_days es siempre null. Llama a /v1/product con ese ASIN cuando necesites la identidad de la oferta o su fecha límite exacta.

Los cupones van aparte. Un cupón que hay que aplicar es un mecanismo de descuento distinto y se mantiene en su propio campo coupon ({"unit": "percent", "value": 15} o {"unit": "currency", "value": 5}), tanto en los datos de producto como en las entradas de páginas de listado, y significa lo mismo en ambos sitios: value es lo que descuenta el cupón, nunca el precio que queda después de aplicarlo. Un cupón percent lleva el porcentaje y uno currency el importe en la moneda local del marketplace. El cupón no se refleja en price, así que el precio final lo calculas tú. Un producto puede llevar cupón y oferta a la vez.

Endpoints

GET /v1/product

Obtener detalles de un producto por ASIN.

Parámetros

Ejemplo

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

Respuesta

{
  "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 indica si la oferta está en una promoción activa y los precios tachados contra los que se mide el descuento; null significa que el producto se vende a su precio normal. Ver Promociones y descuentos.

GET /v1/offers

Obtén todas las ofertas de vendedores de un producto — el panel completo del Buy Box y la visualización de Todas las ofertas — con la condición, el precio, el envío, el método de gestión logística, la valoración del vendedor y el stock de cada oferta.

Parámetros

Filtrado por condición

Por defecto (condition=all) se devuelven las ofertas de todas las condiciones. Pasa condition para limitar el resultado a una sola condición o nivel de usado:

El filtro se aplica a la condition resuelta de cada oferta, por lo que la respuesta contiene únicamente ofertas de la condición solicitada, y fba_count / fbm_count / sold_by_amazon reflejan el conjunto filtrado. Cada solicitud cuenta como un crédito independientemente del filtro.

Ejemplo

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

Ejemplo (solo ofertas usadas)

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

Respuesta

Cada entrada de product_sellers_info lleva una condition normalizada (new, used_like_new, used_very_good, used_good, used_acceptable o collectible) y el encabezado condition_text literal que Amazon muestra para esa oferta. condition es null cuando el encabezado de Amazon está ausente o no se reconoce (p. ej. Renovado/Reacondicionado, o algunas redacciones en otros idiomas) — la etiqueta original sigue disponible en condition_text. seller_id es null para las ofertas vendidas directamente por Amazon.

La oferta destacada (Buy Box) se marca con is_pinned. Como máximo una oferta por respuesta lo lleva, así que puedes leer el ganador del Buy Box directamente en lugar de deducirlo del precio. La posición en el array no sustituye a este indicador: una respuesta puede listar muchas ofertas y no tener ninguna destacada, lo que significa que Amazon no mostró oferta destacada para ese ASIN. Un filtro condition también puede eliminar la oferta destacada de la respuesta, porque Amazon la devuelve sea cual sea la condición solicitada.

Cada oferta lleva un array delivery con las promesas de entrega que mostró Amazon. kind es standard para la franja principal y fastest para la secundaria, que Amazon también usa para promocionar Prime, así que conviene leerlo como «la otra opción mostrada» y no como una entrega garantizada más rápida. date_min / date_max dan la ventana prometida como fechas absolutas, y days_min / days_max expresan esa misma promesa en días enteros desde la fecha de la solicitud, donde 0 significa entrega hoy. Cuando una promesa no se puede resolver en una fecha, todos los campos de fecha y de días son null en lugar de un número de relleno, así que trata null como desconocido. Usa is_free en lugar de shipping_price para distinguir la entrega gratuita de un coste que no se pudo interpretar. text es la redacción literal de Amazon y puede incluir una cuenta atrás, así que evita usarlo como clave de caché.

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

Buscar productos por palabra clave.

Parámetros

Ejemplo

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

Respuesta

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

Cada entrada incluye también el promotion de la tarjeta (insignia de oferta y precio de referencia tachado) en la forma reducida de las páginas de listado descrita en Promociones y descuentos: sin deal_id, ends_at solo en insignias con cuenta atrás, ends_in_days siempre null. Aparece en shallow_parts[] de todas las páginas de listado (búsqueda, categoría, más vendidos).

GET /v1/seller

Obtener el perfil de la tienda de un vendedor por ID de vendedor.

Parámetros

Ejemplo

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

Respuesta

Devuelve el nombre del vendedor, la calificación de valoraciones y el porcentaje de valoraciones positivas de los últimos 12 meses, el total de valoraciones, el enlace a la tienda y el bloque de Información detallada del vendedor (nombre legal de la empresa y dirección) cuando Amazon lo publica. Un ID de vendedor inválido devuelve 200 con found: false y 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

Extraer datos de cualquier URL de Amazon. El tipo de página se detecta automáticamente.

Cuerpo de la solicitud (JSON)

Ejemplo

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"

Respuesta

La forma de data coincide con el page_type detectado. Para product, search, offers y seller coincide con las cargas útiles de los endpoints tipados anteriores. category, bestseller, storefront y reviews devuelven una carga útil estructurada adaptada a la página. Una página no encontrada devuelve found: false y data: null.

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

Marketplaces compatibles

Respuestas de error

Todos los errores siguen un formato consistente:

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Descripción legible"
  }
}

Una entidad inexistente (ASIN/vendedor inválido, listado eliminado) no es un error: devuelve 200 con found: false y data: null, y cuenta como un crédito. Consulta Encontrado vs. No encontrado.