Keyword Analysis API

API de análisis de palabras clave priorizando agentes para investigación en vivo de SERP, scraping de páginas y síntesis de palabras clave SEO.

Ver en wordflowsai.comPrueba este MCPPatrocinado

Documentación

keyword-analysis-api

API de análisis de palabras clave orientada a agentes para investigación de SERP en vivo, extracción de páginas y síntesis de palabras clave.

Resumen

Este servicio está diseñado para LLMs y agentes estilo MCP que necesiten:

  • crear una cuenta sin un flujo web tradicional
  • verificar la propiedad de un correo electrónico con un código de un solo uso
  • ejecutar análisis de palabras clave en vivo contra resultados de Google
  • recibir resultados estructurados orientados a SEO centrados en recuento de palabras y densidad de palabras clave
  • diferir la configuración de facturación hasta que se agote el uso gratuito

El producto es mayormente sin interfaz. La interacción humana solo se requiere para:

  • leer el código de verificación del correo electrónico
  • completar la configuración de facturación alojada de Stripe cuando se agote el uso gratuito

Flujo de Autenticación

  1. POST /auth/create-account Crear o reanudar una cuenta pendiente para una dirección de correo electrónico.

  2. POST /auth/verify-account Enviar el código de un solo uso enviado por correo. Al tener éxito, devuelve un token de API.

  3. Usar el token de API como:

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

Conector MCP

  • Endpoint MCP: GET/POST /mcp
  • Metadatos OAuth: GET /.well-known/oauth-authorization-server
  • Autorización OAuth: GET /oauth/authorize
  • Intercambio de token OAuth: POST /oauth/token
  • Registro dinámico de cliente: POST /oauth/register

El servidor MCP expone envoltorios de herramientas para:

  • estado de la cuenta
  • resumen de uso
  • análisis de palabras clave en cola
  • consulta y listado de trabajos
  • configuración de facturación

Endpoint Principal

POST /keyword-analysis/analyze

Poner en cola un trabajo de análisis de palabras clave que:

  • obtenga resultados de SERP en vivo de Bright Data
  • extraiga los mejores resultados con Jina Reader
  • calcule el recuento objetivo sugerido de palabras
  • puntúe candidatos de palabras clave primarias y secundarias del corpus de páginas clasificadas
  • recomiende la palabra clave primaria respaldada por clasificación más fuerte para la consulta original del usuario
  • use un paso de limpieza LLM restringido para elegir las palabras clave secundarias más fuertes de esos candidatos
  • calcule objetivos de densidad de palabras clave primarias y secundarias del corpus de páginas clasificadas

Entrada

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

Salida

Devuelve:

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

Notas:

  • keyword es la consulta original del usuario
  • analysis.primary_keyword es el objetivo de palabra clave primaria recomendado respaldado por clasificación
  • results contiene solo las páginas realmente utilizadas en el análisis y cada elemento incluye analysis_rank

Resumen de OpenAPI

Autenticación

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

Facturación

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

Análisis de Palabras Clave

  • POST /keyword-analysis/analyze

Descubrimiento

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

Endpoints de Cuenta y Facturación

GET /auth/account-status

Obtener estado verificado, estado de facturación y disponibilidad de búsqueda gratuita.

GET /auth/usage-summary

Obtener uso gratuito, uso de pago, búsquedas exitosas y búsquedas fallidas.

POST /billing/start-billing-setup

Devolver una URL de Stripe alojada para configuración de método de pago o gestión de facturación.

POST /billing/stripe/webhooks

Endpoint de webhook de Stripe para actualizaciones de estado de facturación.

Flujos de Ejemplo

1. Crear Cuenta

Solicitud:

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

Respuesta:

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

En desarrollo, delivery_method puede ser console y verification_code puede incluirse directamente.

2. Verificar Cuenta

Solicitud:

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

Respuesta:

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

3. Verificar Estado de la Cuenta

Respuesta:

{
  "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. Ejecutar Análisis de Palabras Clave

Solicitud:

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

Forma de la respuesta:

{
  "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 Configuración de Facturación

Respuesta:

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

Patrón de Respuesta de Facturación Requerida

Cuando se agota el uso gratuito y la facturación no está configurada, la API puede devolver HTTP 402 con un objeto de detalle como:

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

Modelo de Facturación

  • Las primeras 25 búsquedas exitosas son gratuitas
  • La facturación solo se requiere después de agotar el uso gratuito
  • Las búsquedas fallidas no deben facturarse
  • Las búsquedas exitosas se miden por solicitud completada de análisis de palabras clave

Guía para Agentes

  • Si la creación de cuenta devuelve un código de verificación en desarrollo, úsalo directamente
  • En producción, pide al humano que revise el correo para obtener el código
  • Si el análisis devuelve una respuesta de facturación requerida, muestra la URL de facturación alojada al usuario
  • Prefiere top_n_results=5 a menos que sea necesaria una muestra competitiva más grande
  • Usa include_page_content=false por defecto para minimizar el tamaño de la carga útil

Mejores Prácticas para Agentes

  • Trata create-account y verify-account como un protocolo de dos pasos
  • No reintentes la verificación a ciegas después de un código incorrecto; pide al usuario que revise el correo nuevamente
  • Almacena el token de API devuelto de forma segura para futuras llamadas
  • En HTTP 402, pausa el flujo de análisis y presenta la URL de facturación alojada al humano
  • Reintenta fallos transitorios ascendentes de forma conservadora; evita ráfagas repetidas de búsqueda
  • No asumas que cada solicitud de SERP devolverá el mismo conjunto de clasificaciones a lo largo del tiempo y la geografía
  • Trata analysis.primary_keyword como el objetivo recomendado y keyword como la consulta original del usuario
  • Usa account-status antes de solicitar facturación al usuario si no estás seguro de si queda uso gratuito
  • Considera usage-summary como la fuente de verdad para mensajes de cuota del lado del agente
  • Usa 5 resultados por defecto para velocidad y costo a menos que el usuario solicite explícitamente un análisis más profundo
  • Si ocurre extracción parcial pero se devuelve un análisis válido, trata la solicitud como exitosa a menos que la API indique lo contrario

Endpoints de Descubrimiento

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

Notas

  • Este servicio está optimizado para análisis rápido y estructurado de palabras clave en lugar de flujos amplios de suites SEO
  • Está diseñado para ser más fácil y económico de usar que una plataforma SEO completa cuando la única necesidad es investigación rápida de palabras clave en vivo