Guía de la API de Alexa Scraper: Extraer respuestas, citas y productos

TL;DR:

• Alexa Scraper convierte un aviso en datos de respuesta estructurados. El actor scraper.alexa devuelve respuestas en Markdown y texto plano junto con referencias, fuentes, sugerencias y registros de productos condicionales.
• La solicitud tiene dos entradas de actor requeridas. Envía un aviso en lenguaje natural y un código de país al actor Alexa.
• El punto de acceso documentado actual es /api/v2/scraper/request. Autentica con el encabezado x-api-token y envía JSON a través de HTTP POST.
• Los campos de producto son anulables por diseño. El array productos puede estar vacío cuando una respuesta de Alexa no tiene contexto de producto.
• Las referencias y fuentes deben permanecer adjuntas a la respuesta. Mantener estos registros secundarios con la captura preserva la evidencia detrás del análisis de marca, GEO y producto posteriores.
• Gratis para comenzar. Las nuevas cuentas de Scrapeless incluyen acceso a un plan gratuito en app.scrapeless.com.

Introducción: Las Respuestas de Alexa Necesitan una Interfaz de Datos Estable

Una respuesta de Alexa contiene más que una oración. Puede llevar Markdown, texto plano, referencias, enlaces de fuente, preguntas de seguimiento sugeridas, identificadores de conversación, directivas de procesamiento y registros de productos. Copiar la respuesta visible pierde gran parte de esa estructura.

El Scraper de Alexa de Scrapeless expone la respuesta a través del actor scraper.alexa. Un cliente envía un aviso y un país, y el actor devuelve campos que pueden almacenarse sin analizar una interfaz de asistente de voz. Eso hace que el mismo formato de solicitud sea útil para el monitoreo GEO, la revisión de calidad de respuestas, el análisis de fuentes y el trabajo de visibilidad de productos.

Esta guía utiliza la actual documentación del Scraper de Alexa. Cubre el punto de acceso, la autenticación, los parámetros de solicitud, los campos de respuesta, una solicitud cURL, un cliente Python y un patrón de almacenamiento para la salida estructurada.

Lo Que Puedes Hacer Con el Scraper de Alexa

El Scraper de Alexa admite flujos de trabajo que necesitan la respuesta y sus evidencias relacionadas en un solo registro.

• Capturar texto de respuesta. Almacena md_text para contenido renderizado y raw_text para procesamiento de texto plano.
• Inspeccionar citas. Lee IDs de referencia, títulos y URL de references.
• Mapear enlaces de fuente. Almacena el texto de visualización de la fuente, URL, tipo y URI de fragmento de sources.
• Descubrir avisos de seguimiento. Reúne los valores de texto y mensaje que Alexa presenta en suggestions.
• Rastrear el contexto de respuesta. Preserva el estado de finalización, revisión de respuestas, ID de solicitud de diálogo, ID de punto de acceso, conteo de fragmentos y ID de conversación.
• Analizar la aparición de productos. Lee identificadores de productos, enlaces de cita, títulos, imágenes, URLs, precios, texto de entrega, detalles y propósito cuando se aplican datos de producto.

El actor devuelve datos de captura. Métricas como la tasa de mención, la concentración de fuentes, la consistencia de respuestas y la tasa de aparición de productos son cálculos posteriores definidos por el equipo que utiliza los datos.

Por Qué el Scraper de Alexa de Scrapeless

El Scraper de Alexa de Scrapeless proporciona una interfaz de actor documentada para capturar respuestas de Alexa en diferentes mercados.

El valor de implementación proviene de la estructura de respuesta:

• El texto de respuesta llega en formatos de Markdown y texto plano.
• Las citas y enlaces de fuente son arrays separados en lugar de enlaces incrustados solo en prosa.
• Se devuelven avisos sugeridos como registros estructurados.
• La información del producto está disponible como un array condicional.
• El país es una entrada de solicitud explícita para la captura específica del mercado.
• Los identificadores de conversación y respuesta pueden ser retenidos para rastreabilidad.

El Scraper de Chat de LLM de Scrapeless es parte de la línea de API de Scraping Universal. La página del producto de API de Scraping Universal es el hogar del producto, y los detalles del plan actual se enumeran en la página de precios de Scrapeless.

Requisitos Previos

Necesitas:

• Una cuenta de Scrapeless y una clave API de app.scrapeless.com
• cURL para el ejemplo de shell
• Python y el paquete requests para el ejemplo en Python
• Un código de país respaldado para el mercado que deseas capturar

La entrada country utiliza un código de país corto. El estándar de código de país ISO 3166 explica el formato común alpha-2; usa la lista de países respaldados de Scrapeless para confirmar la disponibilidad de productos para un código específico.

Nota: Las solicitudes autenticadas a continuación requieren una clave de API de Scrapeless válida y un webhook accesible. Sin esos credenciales, los bloques se pueden verificar por sintaxis pero no pueden producir un resultado en vivo de Alexa.

Cómo funciona la API de Scraper de Alexa

La solicitud de Scraper de Alexa es un POST HTTP que nombra al actor, proporciona el mensaje y el país, y proporciona un destino de webhook.

El punto final documentado actual es:

https://api.scrapeless.com/api/v2/scraper/request

HTTP define los métodos de solicitud y los campos de cabecera a través de el estándar de semántica HTTP. En esta solicitud, Content-Type: application/json describe el formato del cuerpo y x-api-token lleva la clave de API de Scrapeless.

Guarda esa clave de API en un almacén de secretos o variable de entorno protegida en lugar de en el código fuente. La guía de gestión de secretos de OWASP describe controles prácticos para el almacenamiento, la rotación y el acceso.

Parámetros de Solicitud

Mantén el mensaje y el país en el mismo registro de base de datos que la respuesta devuelta. Esas dos entradas definen la observación y hacen que las comparaciones posteriores sean reproducibles.

Captura Rápida con cURL

Configura SCRAPELESS_API_KEY y SCRAPELESS_WEBHOOK_URL en la terminal antes de ejecutar la solicitud.

Nota: Este bloque es una solicitud restringida por credenciales. Necesita una clave de API de Scrapeless válida y una URL de webhook pública.

curl 'https://api.scrapeless.com/api/v2/scraper/request' \
  --header 'Content-Type: application/json' \
  --header "x-api-token: ${SCRAPELESS_API_KEY}" \
  --data-binary @- <<JSON
{
  "actor": "scraper.alexa",
  "input": {
    "prompt": "Atracciones recomendadas en Nueva York",
    "country": "US"
  },
  "webhook": {
    "url": "${SCRAPELESS_WEBHOOK_URL}"
  }
}
JSON

La carga útil es JSON, cuya gramática interoperable está definida por RFC 8259. Mantén los valores de cadena entre comillas y evita comentarios dentro del cuerpo enviado.

Campos de Respuesta

El resultado del actor agrupa los campos en contenido de respuesta, identificadores, directrices, referencias, fuentes, sugerencias y productos.

El siguiente JSON es una forma ilustrativa construida a partir de la lista de campos documentados. Los valores son ejemplos, no una ejecución capturada del actor.

{
  "user_text": "¿Qué cafetera se adapta a una cocina pequeña?",
  "md_text": "Una cafetera compacta debería equilibrar la huella y la capacidad.",
  "raw_text": "Una cafetera compacta debería equilibrar la huella y la capacidad.",
  "completed": true,
  "answer_revision": 1,
  "conversation": {
    "id": "illustrative-conversation-id"
  },
  "references": [
    {
      "id": "cite_example",
      "title": "Guía de compra ilustrativa",
      "url": "https://example.com/illustrative-buying-guide"
    }
  ],
  "sources": [
    {
      "text": "Fuente ilustrativa",
      "url": "https://example.com/illustrative-buying-guide",
      "type": "OpenURL",
      "fragment_uri": "illustrative-source-fragment"
    }
  ],
  "suggestions": [
    {
      "text": "Comparar modelos compactos",
      "message": "Comparar cafeteras compactas",
      "type": "TextMessage",
      "fragment_uri": "illustrative-suggestion-fragment"
    }
  ],
  "products": []
}

El array de productos vacío es intencional. La información del producto es condicional, por lo que los parseadores deben aceptar una lista vacía.

Obtén tu clave de API en el plan gratuito: app.scrapeless.com

Integrando el Scraper de Alexa en Python

Un cliente de Python puede enviar la solicitud documentada e imprimir la respuesta del flujo de trabajo de la solicitud. El resultado final del actor de Alexa se entrega a través del flujo de trabajo configurado y debe ser pasado a la función de normalización mostrada después de la solicitud.
Instala la única dependencia de terceros. Este paso de configuración requiere acceso a un índice de paquetes de Python.

python -m pip install requests

Nota: El bloque de solicitud a continuación es un ejemplo protegido por credenciales. Requiere las variables de entorno SCRAPELESS_API_KEY y SCRAPELESS_WEBHOOK_URL.

import os
import requests

API_URL = "https://api.scrapeless.com/api/v2/scraper/request"

api_key = os.environ["SCRAPELESS_API_KEY"]
webhook_url = os.environ["SCRAPELESS_WEBHOOK_URL"]

payload = {
    "actor": "scraper.alexa",
    "input": {
        "prompt": "Atracciones recomendadas en Nueva York",
        "country": "US",
    },
    "webhook": {
        "url": webhook_url,
    },
}

response = requests.post(
    API_URL,
    headers={
        "Content-Type": "application/json",
        "x-api-token": api_key,
    },
    json=payload,
    timeout=60,
)
response.raise_for_status()
print(response.json())

Mantén la clave de API en una variable de entorno. No la coloques en el control de versiones, notebooks, capturas de pantalla o cargas de webhook capturadas.

Normalizando la Salida de Alexa para Almacenamiento

Un registro de Alexa normalizado mantiene la respuesta a nivel de padre y almacena arreglos repetitivos como registros hijo.

Utiliza una tabla de captures padre con:

• ID de captura interno
• Prompt enviado
• País enviado
• user_text, md_text y raw_text
• completed y answer_revision
• Identificadores de conversación y diálogo
• Marca de tiempo de captura generada por tu sistema

Almacena references, sources, suggestions, directives y products en tablas separadas vinculadas al ID de captura. Esto evita duplicar la respuesta completa para cada fuente o producto.

Las relaciones de origen deben seguir siendo explícitas y consultables. El actor ya expone esas relaciones a través de IDs de cita, URLs de fuente y URIs de fragmento. Presérvalas en lugar de aplanarlas en un campo de texto no estructurado.

Para las filas de productos, mantén citation_id incluso cuando sea nulo. Cuando esté presente, puede asociar el producto con una referencia documentada. Cuando esté ausente, el valor nulo registra con precisión que no se devolvió ningún enlace de cita directa en ese campo.

Cómo Evitar Problemas Comunes de Integración

Las integraciones de Alexa Scraper se mantienen predecibles cuando los campos anulables, el alcance del país y la evidencia de respuesta se manejan de manera explícita.

Tratar Arreglos Condicionales como Colecciones Vacías

El arreglo products puede estar vacío cuando la información del producto no se aplica. El mismo patrón defensivo es útil para references, sources, suggestions y directives: leer un arreglo faltante o nulo como una colección vacía en la capa de transformación, mientras se conserva la carga original para auditoría.

Mantener Markdown y Texto Plano

md_text y raw_text soportan diferentes tareas. Markdown es útil para renderizar y preservar estructura visible. El texto plano es más fácil de tokenizar, comparar y buscar. Almacenar ambos previene que un pipeline posterior reconstruya un formato a partir del otro.

Fijar el País en Cada Registro

No confíes en un mercado predeterminado en el almacenamiento posterior. Guarda el país enviado exacto junto al prompt y el resultado. Las comparaciones de mercado fallan cuando las capturas no pueden vincularse al contexto de la solicitud.

Preservar IDs de Cita Antes de Agrupar por Dominio

Los informes a nivel de dominio son útiles, pero deben derivarse de los registros de referencia y fuente originales. Mantén el ID de cita, el título, la URL completa, el tipo de fuente y el URI de fragmento antes de agregar campos de dominio normalizados.

Separar la Salida del Actor de las Puntuaciones Derivadas

El actor devuelve campos de respuesta y contexto. La tasa de mención, la tasa de cita, la diversidad de fuentes, la precisión de reclamos y la aparición de productos son analíticas creadas después de la captura. Almacena las puntuaciones derivadas en una tabla o espacio de nombres separados para que un revisor pueda distinguir la salida de la API de la interpretación del equipo.

Lectura Complementaria para Datos de Motor de Respuestas

Alexa Scraper cubre una superficie de respuesta de LLM. La guía de la API de Google AI Overview Scraper muestra un patrón de actor relacionado para una experiencia de respuesta guiada por búsqueda con su propio modelo de campo.

Utiliza un contrato de almacenamiento compartido entre actores solo para campos que realmente se alineen: prompt enviado, país, texto de respuesta, URL de fuente, ID de captura y hora de captura. Mantén campos específicos de actores en sus propias tablas para que los fragmentos de producto, los mensajes de sugerencia y los identificadores de plataforma no desaparezcan en un esquema de denominador común más bajo.

Conclusión: Preservar la Respuesta y Su Evidencia

La integración de Alexa Scraper tiene una pequeña superficie de solicitud: actor, prompt, país, encabezado de autenticación y flujo de trabajo de webhook. El modelo de respuesta es más amplio porque preserva la respuesta, referencias, fuentes, sugerencias, directivas, contexto de conversación y productos condicionales.
Empiece guardando la carga útil en bruto y una captura de padre normalizada. Agregue tablas secundarias para registros repetidos, conserven los campos de producto que pueden ser nulos y mantengan los análisis derivados separados de la salida del actor. Esa estructura admite futuros casos de uso de marca, GEO, producto y mercado sin reescribir la capa de colección.

¿Listo para construir con Alexa Scraper?

Únase a nuestra comunidad para reclamar un plan gratuito y conectar con desarrolladores que están construyendo tuberías de datos de respuestas LLM: Discord · Telegram.

Regístrese en app.scrapeless.com y pruebe al actor con un aviso, un país admitido y un endpoint de webhook que controle.

Preguntas Frecuentes

P: ¿Qué endpoint utiliza Alexa Scraper?

Alexa Scraper utiliza POST https://api.scrapeless.com/api/v2/scraper/request en la documentación actual del actor. La solicitud utiliza scraper.alexa como valor del actor.

P: ¿Cuáles son los inputs requeridos para Alexa Scraper?

El actor requiere un aviso y un código de país dentro del objeto input. El ejemplo de solicitud documentado también incluye una URL de webhook para el flujo de trabajo de la solicitud.

P: ¿Cuál es la diferencia entre md_text y raw_text?

md_text es la respuesta de Alexa en formato Markdown, mientras que raw_text es la respuesta en texto plano. Almacene ambos cuando el pipeline necesite representación fiel y análisis de texto.

P: ¿Alexa Scraper siempre devuelve citas?

Alexa Scraper expone arreglos references y sources, pero el código de downstream debe permitir que esos arreglos estén vacíos. La presencia de citas depende de la respuesta devuelta.

P: ¿Alexa Scraper siempre devuelve productos?

No. La información del producto es condicional, y el arreglo products puede estar vacío cuando no aplica.

P: ¿Se puede utilizar Alexa Scraper sin Python?

Sí. Cualquier cliente que pueda enviar un JSON POST autenticado y recibir la respuesta del flujo de trabajo de la solicitud puede usar el actor. El ejemplo de cURL es suficiente para una prueba de integración directa.

P: ¿Cómo se deben almacenar las claves de API?

Almacene la clave de API de Scrapeless en una variable de entorno o en un almacén de secretos gestionado. No comprometa la clave en el control de fuente ni la incluya en los registros de webhook.