Keyword Analysis API

API de análise de palavras-chave voltada para agentes, para pesquisa de SERP ao vivo, scraping de páginas e síntese de palavras-chave de SEO.

Ver em wordflowsai.com

Documentação

keyword-analysis-api

API de análise de palavras-chave priorizando agentes, para pesquisa de SERP ao vivo, raspagem de páginas e síntese de palavras-chave.

Resumo

Este serviço foi projetado para LLMs e agentes no estilo MCP que precisam de:

  • criar uma conta sem um fluxo tradicional de site
  • verificar a propriedade de um e-mail com um código de uso único
  • executar análise de palavras-chave ao vivo nos resultados do Google
  • receber saída estruturada voltada para SEO, focada em contagem de palavras e densidade de palavras-chave
  • adiar a configuração de cobrança até que o uso gratuito seja esgotado

O produto é majoritariamente headless. A interação humana só é necessária para:

  • ler o código de verificação de e-mail
  • concluir a configuração de cobrança hospedada no Stripe quando o uso gratuito for esgotado

Fluxo de Autenticação

  1. POST /auth/create-account Crie ou retome uma conta pendente para um endereço de e-mail.

  2. POST /auth/verify-account Envie o código de uso único enviado por e-mail. Em caso de sucesso, isso retorna um token de API.

  3. Use o token de API como:

    • Authorization: Bearer <token>
    • X-API-Key: <token>

Conector MCP

  • Endpoint MCP: GET/POST /mcp
  • Metadados OAuth: GET /.well-known/oauth-authorization-server
  • Autorização OAuth: GET /oauth/authorize
  • Troca de token OAuth: POST /oauth/token
  • Registro dinâmico de cliente: POST /oauth/register

O servidor MCP expõe wrappers de ferramentas para:

  • status da conta
  • resumo de uso
  • análise de palavras-chave na fila
  • consulta e listagem de trabalhos
  • configuração de cobrança

Endpoint Principal

POST /keyword-analysis/analyze

Coloque na fila um trabalho de análise de palavras-chave que irá:

  • buscar resultados de SERP ao vivo do Bright Data
  • raspar os principais resultados com o Jina Reader
  • calcular a contagem de palavras-alvo sugerida
  • pontuar candidatos a palavras-chave primárias e de suporte a partir do corpus das páginas ranqueadas
  • recomendar a palavra-chave primária mais forte com base no ranking para a consulta original do usuário
  • usar uma passagem de limpeza com LLM restrito para escolher as palavras-chave de suporte mais fortes entre os candidatos
  • calcular metas de densidade de palavras-chave primárias e secundárias a partir do corpus das páginas ranqueadas

Entrada

{
  "keyword": "ai teaching assistant",
  "top_n_results": 5,
  "include_page_content": false
}

Saída

Retorna:

  • keyword
  • suggested_word_count
  • total_results_analyzed
  • results
  • analysis.primary_keyword
  • analysis.primary_keyword_density
  • analysis.secondary_keywords

Observações:

  • keyword é a consulta original do usuário
  • analysis.primary_keyword é a palavra-chave primária recomendada com base no ranking
  • results contém apenas as páginas realmente usadas na análise, e cada item inclui analysis_rank

Resumo do OpenAPI

Autenticação

  • POST /auth/create-account
  • POST /auth/verify-account
  • GET /auth/account-status
  • GET /auth/usage-summary

Cobrança

  • POST /billing/start-billing-setup
  • POST /billing/stripe/webhooks
  • GET /billing/setup/success
  • GET /billing/setup/cancel

Análise de Palavras-chave

  • POST /keyword-analysis/analyze

Descoberta

  • GET /
  • GET /mcp
  • GET /.well-known/oauth-authorization-server
  • GET /llms.txt
  • GET /.well-known/llms.txt
  • GET /openapi.json

Endpoints de Conta e Cobrança

GET /auth/account-status

Obtenha o status verificado, o status de cobrança e a disponibilidade de busca gratuita.

GET /auth/usage-summary

Obtenha o uso gratuito, o uso pago, as buscas bem-sucedidas e as buscas com falha.

POST /billing/start-billing-setup

Retorne uma URL hospedada do Stripe para configuração do método de pagamento ou gerenciamento de cobrança.

POST /billing/stripe/webhooks

Endpoint de webhook do Stripe para atualizações de estado de cobrança.

Fluxos de Exemplo

1. Criar Conta

Solicitação:

{
  "email": "user@example.com"
}

Resposta:

{
  "pending_user_id": "pending_abcd1234",
  "verification_required": true,
  "expires_in_seconds": 600,
  "delivery_method": "smtp"
}

Em desenvolvimento, delivery_method pode ser console e verification_code pode ser incluído diretamente.

2. Verificar Conta

Solicitação:

{
  "pending_user_id": "pending_abcd1234",
  "code": "123456"
}

Resposta:

{
  "account_id": 1,
  "email": "user@example.com",
  "api_token": "kaa_xxxxx",
  "billing_status": "unconfigured",
  "free_searches_remaining": 25
}

3. Verificar Status da Conta

Resposta:

{
  "account_id": 1,
  "email": "user@example.com",
  "email_verified": true,
  "billing_configured": false,
  "billing_status": "unconfigured",
  "free_searches_remaining": 25,
  "paid_usage_enabled": false,
  "usage_this_month": 0
}

4. Executar Análise de Palavras-chave

Solicitação:

{
  "keyword": "ai teaching assistant",
  "top_n_results": 5,
  "include_page_content": false
}

Formato da resposta:

{
  "keyword": "auto body repair pearland tx",
  "suggested_word_count": 550,
  "total_results_analyzed": 4,
  "results": [
    {
      "analysis_rank": 1,
      "title": "Collision Repair in Pearland",
      "url": "https://example.com/pearland-collision-repair",
      "rank": 1,
      "word_count": 612,
      "scrape_error": null
    }
  ],
  "analysis": {
    "primary_keyword": "collision repair pearland",
    "primary_keyword_density": {
      "keyword": "collision repair pearland",
      "occurrence_count": 4,
      "occurrences_per_result": 1.0,
      "total_word_count": 2287,
      "density_percentage": 0.17
    },
    "secondary_keywords": [
      {
        "keyword": "collision repair",
        "occurrence_count": 13,
        "occurrences_per_result": 3.25,
        "total_word_count": 2287,
        "density_percentage": 0.57
      }
    ]
  }
}

5. Iniciar Configuração de Cobrança

Resposta:

{
  "billing_status": "unconfigured",
  "url": "https://checkout.stripe.com/...",
  "mode": "checkout_setup",
  "stripe_customer_id": "cus_123"
}

Padrão de Resposta de Cobrança Necessária

Quando o uso gratuito é esgotado e a cobrança não está configurada, a API pode retornar HTTP 402 com um objeto de detalhe como:

{
  "message": "Billing setup required",
  "billing_url": "https://checkout.stripe.com/..."
}

Modelo de Cobrança

  • As primeiras 25 buscas bem-sucedidas são gratuitas
  • A cobrança só é necessária após o uso gratuito ser esgotado
  • Buscas com falha não devem ser cobradas
  • Buscas bem-sucedidas são medidas por solicitação concluída de análise de palavras-chave

Orientação para Agentes

  • Se a criação de conta retornar um código de verificação em desenvolvimento, use-o diretamente
  • Em produção, peça ao humano para verificar o e-mail em busca do código
  • Se a análise retornar uma resposta de cobrança necessária, mostre a URL de cobrança hospedada ao usuário
  • Prefira top_n_results=5 a menos que uma amostra competitiva maior seja necessária
  • Use include_page_content=false por padrão para minimizar o tamanho do payload

Melhores Práticas para Agentes

  • Trate create-account e verify-account como um handshake de duas etapas
  • Não repita a verificação às cegas após um código errado; peça ao usuário para verificar o e-mail novamente
  • Armazene o token de API retornado com segurança para chamadas futuras
  • Em HTTP 402, pause o fluxo de análise e apresente a URL de cobrança hospedada ao humano
  • Repita falhas transitórias de upstream com moderação; evite rajadas repetidas de busca
  • Não presuma que toda solicitação de SERP retornará o mesmo conjunto de rankings ao longo do tempo e da geografia
  • Trate analysis.primary_keyword como a meta recomendada e keyword como a consulta original do usuário
  • Use account-status antes de solicitar cobrança ao usuário se você não tiver certeza se o uso gratuito ainda resta
  • Considere usage-summary a fonte de verdade para mensagens de cota do lado do agente
  • Use 5 resultados por padrão para velocidade e custo, a menos que o usuário peça explicitamente uma análise mais profunda
  • Se ocorrer raspagem parcial, mas uma análise válida for retornada, trate a solicitação como bem-sucedida, a menos que a API diga o contrário

Endpoints de Descoberta

  • GET /
  • GET /llms.txt
  • GET /.well-known/llms.txt
  • GET /openapi.json

Observações

  • Este serviço é otimizado para análise de palavras-chave rápida e estruturada, em vez de fluxos amplos de suíte de SEO
  • Ele é pensado para ser mais fácil e barato de usar do que uma plataforma completa de SEO quando a única necessidade é pesquisa rápida de palavras-chave ao vivo