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.

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

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.

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

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

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.