Guia da API Alexa Scraper: Extraia Respostas, Citações e Produtos

TL;DR:

• Alexa Scraper transforma um prompt em dados de resposta estruturados. O ator scraper.alexa retorna respostas em Markdown e texto simples, juntamente com referências, fontes, sugestões e registros de produtos condicionais.
• A solicitação possui duas entradas obrigatórias do ator. Envie um prompt em linguagem natural e um código de país para o ator Alexa.
• O endpoint documentado atual é /api/v2/scraper/request. Autentique-se com o cabeçalho x-api-token e envie JSON via HTTP POST.
• Os campos de produto são nulos por design. O array products pode estar vazio quando uma resposta da Alexa não tiver contexto de produto.
• Referências e fontes devem permanecer anexadas à resposta. Manter esses registros filhas com a captura preserva as evidências por trás da análise de marca, GEO e produto a jusante.
• Gratuito para começar. Novas contas Scrapeless incluem acesso a um plano gratuito em app.scrapeless.com.

Introdução: Respostas da Alexa Precisam de uma Interface de Dados Estável

Uma resposta da Alexa contém mais do que uma frase. Ela pode incluir Markdown, texto simples, referências, links de fonte, perguntas sugeridas, identificadores de conversa, diretrizes de processamento e registros de produtos. Copiar a resposta visível perde grande parte dessa estrutura.

O Scrapeless Alexa Scraper expõe a resposta através do ator scraper.alexa. Um cliente envia um prompt e país, e o ator retorna campos que podem ser armazenados sem a necessidade de interpretar uma interface de assistente de voz. Isso torna a mesma forma de solicitação útil para monitoramento GEO, revisão de qualidade de resposta, análise de fontes e trabalho de visibilidade de produtos.

Este guia utiliza a atual documentação do Alexa Scraper. Ele abrange o endpoint, autenticação, parâmetros de solicitação, campos de resposta, uma solicitação cURL, um cliente Python e um padrão de armazenamento para saída estruturada.

O Que Você Pode Fazer Com o Alexa Scraper

O Alexa Scraper suporta fluxos de trabalho que precisam da resposta e suas evidências circundantes em um único registro.

• Capturar texto da resposta. Armazenar md_text para conteúdo renderizado e raw_text para processamento em texto simples.
• Inspecionar citações. Ler IDs de referência, títulos e URLs de references.
• Mapear links de fonte. Armazenar texto de exibição da fonte, URL, tipo e URI de fragmento de sources.
• Descobrir prompts de acompanhamento. Coletar os valores de texto e mensagem que a Alexa apresenta em suggestions.
• Rastrear contexto de resposta. Preservar estado de conclusão, revisão de resposta, ID de solicitação de diálogo, ID do endpoint, contagem de fragmentos e ID da conversa.
• Analisar a exposição de produtos. Ler identificadores de produtos, links de citação, títulos, imagens, URLs, preços, texto de entrega, detalhes e finalidade quando os dados do produto se aplicam.

O ator retorna dados de captura. Métricas como taxa de menção, concentração de fontes, consistência de resposta e taxa de aparição de produtos são cálculos a jusante definidos pela equipe que usa os dados.

Por Que o Scrapeless Alexa Scraper

O Scrapeless Alexa Scraper oferece uma interface de ator documentada para capturar respostas da Alexa em diferentes mercados.

O valor da implementação vem da forma da resposta:

• O texto da resposta chega em formatos Markdown e texto simples.
• Citações e links de fonte são arrays separados, em vez de links incorporados apenas em prosa.
• Prompts sugeridos são retornados como registros estruturados.
• Informações sobre produtos estão disponíveis como um array condicional.
• O país é uma entrada de solicitação explícita para captura específica do mercado.
• Identificadores de conversa e resposta podem ser mantidos para rastreabilidade.

O Scrapeless LLM Chat Scraper é parte da linha Universal Scraping API. A página do produto Universal Scraping API é a página inicial do produto, e os detalhes do plano atual estão listados na página de preços da Scrapeless.

Pré-requisitos

Você precisa de:

• Uma conta Scrapeless e uma chave API de app.scrapeless.com
• cURL para o exemplo de shell
• Python e o pacote requests para o exemplo em Python
• Um código de país suportado para o mercado que você deseja capturar

A entrada country utiliza um código de país curto. O padrão de código de país ISO 3166 explica o formato alfa-2 comum; utilize a lista de países suportada pelo Scrapeless para confirmar a disponibilidade do produto para um código específico.

Nota: As solicitações autenticadas abaixo requerem uma chave de API Scrapeless real e um webhook acessível. Sem essas credenciais, os blocos podem ser verificados quanto à sintaxe, mas não podem produzir um resultado ao vivo da Alexa.

Como a API Scraper da Alexa Funciona

A solicitação do Scraper da Alexa é um POST HTTP que nomeia o ator, fornece o prompt e o país, e fornece um destino de webhook.

O ponto de extremidade documentado atual é:

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

O HTTP define métodos de solicitação e campos de cabeçalho através do padrão de semântica HTTP. Nesta solicitação, Content-Type: application/json descreve o formato do corpo e x-api-token transporta a chave de API Scrapeless.

Mantenha essa chave de API em um armazenamento de segredos ou variável de ambiente protegida, em vez de no código-fonte. A orientação de gerenciamento de segredos da OWASP descreve controles práticos para armazenamento, rotação e acesso.

Parâmetros da Solicitação

Mantenha o prompt e o país no mesmo registro do banco de dados que a resposta retornada. Essas duas entradas definem a observação e tornam as comparações posteriores reproduzíveis.

Captura Rápida com cURL

Defina SCRAPELESS_API_KEY e SCRAPELESS_WEBHOOK_URL no shell antes de executar a solicitação.

Nota: Este bloco é uma solicitação com autenticação de credenciais. Precisa de uma chave de API Scrapeless real e de uma 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": "Atrações recomendadas em Nova York",
    "country": "US"
  },
  "webhook": {
    "url": "${SCRAPELESS_WEBHOOK_URL}"
  }
}
JSON

A carga útil é JSON, cuja gramática interoperável é definida por RFC 8259. Mantenha os valores de string entre aspas e evite comentários dentro do corpo enviado.

Campos da Resposta

O resultado do ator agrupa campos em conteúdo da resposta, identificadores, diretivas, referências, fontes, sugestões e produtos.

O seguinte JSON é uma estrutura ilustrativa construída a partir da lista de campos documentados. Os valores são exemplos, não uma execução capturada do ator.

{
  "user_text": "Qual cafeteira se adapta a uma cozinha pequena?",
  "md_text": "Uma cafeteira compacta deve equilibrar espaço e capacidade.",
  "raw_text": "Uma cafeteira compacta deve equilibrar espaço e capacidade.",
  "completed": true,
  "answer_revision": 1,
  "conversation": {
    "id": "id-da-conversacao-ilustrativa"
  },
  "references": [
    {
      "id": "cite_example",
      "title": "Guia de compra ilustrativo",
      "url": "https://example.com/guia-de-compra-ilustrativa"
    }
  ],
  "sources": [
    {
      "text": "Fonte ilustrativa",
      "url": "https://example.com/guia-de-compra-ilustrativa",
      "type": "OpenURL",
      "fragment_uri": "fragmento-da-fonte-ilustrativa"
    }
  ],
  "suggestions": [
    {
      "text": "Compare modelos compactos",
      "message": "Compare cafeteiras compactas",
      "type": "TextMessage",
      "fragment_uri": "fragmento-da-sugestao-ilustrativa"
    }
  ],
  "products": []
}

O array de produtos vazio é intencional. As informações do produto são condicionais, então os analisadores devem aceitar uma lista vazia.

Obtenha sua chave de API no plano gratuito: app.scrapeless.com

Integrando o Scraper da Alexa em Python

Um cliente Python pode enviar a solicitação documentada e imprimir a resposta do fluxo de trabalho da solicitação. O resultado final do ator Alexa é entregue através do fluxo de trabalho configurado e deve ser passado para a função de normalização mostrada após a solicitação.
Instale a única dependência de terceiros. Esta etapa de configuração requer acesso a um índice de pacotes Python.

python -m pip install requests

Nota: O bloco de solicitação abaixo é um exemplo protegido por credenciais. Ele requer as variáveis de ambiente SCRAPELESS_API_KEY e 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": "Atrações recomendadas em Nova 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())

Mantenha a chave da API em uma variável de ambiente. Não a coloque no controle de versão, notebooks, capturas de tela ou cargas úteis de webhook capturadas.

Normalizando a Saída do Alexa para Armazenamento

Um registro normalizado do Alexa mantém a resposta no nível pai e armazena arrays repetitivos como registros filhos.

Use uma tabela pai captures com:

• ID de captura interno
• Prompt enviado
• País submetido
• user_text, md_text e raw_text
• completed e answer_revision
• Identificadores de conversa e diálogo
• Timestamp da captura gerado pelo seu sistema

Armazene references, sources, suggestions, directives e products em tabelas separadas vinculadas ao ID de captura. Isso evita duplicar a resposta completa para cada fonte ou produto.

As relações de origem devem permanecer explícitas e consultáveis. O ator já expõe essas relações por meio de IDs de citação, URLs de origem e URIs de fragmento. Preserve-as em vez de achatá-las em um campo de texto não estruturado.

Para as linhas de produtos, mantenha citation_id, mesmo quando for nulo. Quando presente, pode associar o produto a uma referência documentada. Quando ausente, o valor nulo registra com precisão que nenhum link de citação direta foi retornado naquele campo.

Como Evitar Problemas Comuns de Integração

As integrações do Alexa Scraper permanecem previsíveis quando campos nulos, escopo do país e evidências de resposta são tratados explicitamente.

Trate Arrays Condicionais como Coleções Vazias

O array products pode estar vazio quando as informações do produto não se aplicam. O mesmo padrão defensivo é útil para references, sources, suggestions e directives: leia um array ausente ou nulo como uma coleção vazia na camada de transformação, enquanto retém a carga útil original para auditoria.

Mantenha Markdown e Texto Simples

md_text e raw_text suportam trabalhos diferentes. O Markdown é útil para renderização e preservação da estrutura visível. O texto simples é mais fácil de tokenizar, comparar e pesquisar. Armazenar ambos evita que um pipeline posterior reconstrua um formato a partir do outro.

Fixe o País em Cada Registro

Não confie em um mercado padrão no armazenamento subsequente. Salve o país exato submetido ao lado do prompt e do resultado. Comparações de mercado falham quando as capturas não podem ser vinculadas ao contexto da solicitação.

Preserve IDs de Citação Antes de Agrupar por Domínio

Relatórios em nível de domínio são úteis, mas devem ser derivados dos registros de referência e fonte originais. Mantenha o ID de citação, título, URL completa, tipo de fonte e URI de fragmento antes de adicionar campos de domínio normalizados.

Separe a Saída do Ator dos Pontos Derivados

O ator retorna campos de resposta e contexto. Taxa de menção, taxa de citação, diversidade de fontes, precisão da reivindicação e aparência do produto são análises criadas após a captura. Armazene os pontos derivados em uma tabela ou namespace separado para que um revisor possa distinguir a saída da API da interpretação da equipe.

Leitura Complementar para Dados do Answer-Engine

O Alexa Scraper cobre uma superfície de resposta do LLM. O guia da API do Google AI Overview Scraper mostra um padrão de ator relacionado para uma experiência de resposta liderada pela pesquisa com seu próprio modelo de campo.

Use um contrato de armazenamento compartilhado entre os atores apenas para campos que realmente se alinham: prompt submetido, país, texto da resposta, URL da fonte, ID de captura e hora da captura. Mantenha campos específicos do ator em suas próprias tabelas para que fragmentos de produtos, mensagens de sugestão e identificadores de plataforma não desapareçam em um esquema de menor denominação comum.

Conclusão: Preserve a Resposta e Suas Evidências

A integração do Alexa Scraper tem uma pequena superfície de solicitação: ator, prompt, país, cabeçalho de autenticação e fluxo de trabalho de webhook. O modelo de resposta é mais amplo porque preserva a resposta, referências, fontes, sugestões, diretivas, contexto da conversa e produtos condicionais.
Comece armazenando a carga útil bruta e uma captura pai normalizada. Adicione tabelas de crianças para registros repetidos, mantenha campos de produto anuláveis e mantenha análises derivadas separadas da saída do ator. Essa estrutura suporta casos de uso futuros de marca, GEO, produto e mercado sem reescrever a camada de coleta.

Pronto para Construir com o Alexa Scraper?

Junte-se à nossa comunidade para reivindicar um plano gratuito e se conectar com desenvolvedores construindo pipelines de dados de resposta LLM: Discord · Telegram.

Inscreva-se em app.scrapeless.com e teste o ator com um prompt, um país suportado e um endpoint de webhook que você controla.

FAQ

Q: Qual endpoint o Alexa Scraper usa?

O Alexa Scraper usa POST https://api.scrapeless.com/api/v2/scraper/request na documentação atual do ator. A solicitação usa scraper.alexa como o valor do ator.

Q: Quais entradas do Alexa Scraper são necessárias?

O ator requer um prompt e um código de país dentro do objeto input. O exemplo de solicitação documentada também inclui uma URL de webhook para o fluxo de trabalho da solicitação.

Q: Qual é a diferença entre md_text e raw_text?

md_text é a resposta do Alexa formatada em Markdown, enquanto raw_text é a resposta em texto simples. Armazene ambos quando o pipeline precisar de renderização fiel e análise de texto.

Q: O Alexa Scraper sempre retorna citações?

O Alexa Scraper expõe arrays de references e sources, mas o código a montante deve permitir que esses arrays estejam vazios. A presença de citações depende da resposta retornada.

Q: O Alexa Scraper sempre retorna produtos?

Não. As informações do produto são condicionais, e o array products pode estar vazio quando não se aplica.

Q: O Alexa Scraper pode ser usado sem Python?

Sim. Qualquer cliente que puder enviar um POST JSON autenticado e receber a resposta do fluxo de trabalho da solicitação pode usar o ator. O exemplo cURL é suficiente para um teste de integração direto.

Q: Como as chaves da API devem ser armazenadas?

Armazene a chave da API Scrapeless em uma variável de ambiente ou em um armazenamento de segredos gerenciado. Não comprometa a chave no controle de versão ou inclua-a nos logs do webhook.