Keyword Analysis API

Agent-first Keyword-Analyse-API für Live-SERP-Recherche, Seiten-Scraping und SEO-Keyword-Synthese.

Auf wordflowsai.com ansehenDieses MCP ausprobierenGesponsert

Dokumentation

keyword-analysis-api

Agent-first keyword analysis API for live SERP research, page scraping, and keyword synthesis.

Summary

This service is designed for LLMs and MCP-style agents that need to:

  • create an account without a traditional website flow
  • verify ownership of an email with a one-time code
  • run live keyword analysis against Google results
  • receive structured SEO-oriented output focused on word count and keyword density
  • defer billing setup until after free usage is exhausted

The product is mostly headless. Human interaction is only required for:

  • reading the email verification code
  • completing hosted Stripe billing setup when free usage is exhausted

Authentication Flow

  1. POST /auth/create-account Create or resume a pending account for an email address.

  2. POST /auth/verify-account Submit the one-time code sent by email. On success this returns an API token.

  3. Use the API token as either:

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

MCP Connector

  • MCP endpoint: GET/POST /mcp
  • OAuth metadata: GET /.well-known/oauth-authorization-server
  • OAuth authorize: GET /oauth/authorize
  • OAuth token exchange: POST /oauth/token
  • Dynamic client registration: POST /oauth/register

The MCP server exposes tool wrappers for:

  • account status
  • usage summary
  • queued keyword analysis
  • job lookup and listing
  • billing setup

Primary Endpoint

POST /keyword-analysis/analyze

Queue a keyword analysis job that will:

  • fetch live SERP results from Bright Data
  • scrape the top results with Jina Reader
  • calculate suggested target word count
  • score primary and supporting keyword candidates from the ranking-page corpus
  • recommend the closest ranking-backed primary keyword for the user's original query
  • use a constrained LLM cleanup pass to choose the strongest supporting keywords from those candidates
  • calculate primary and secondary keyword density targets from the ranking-page corpus

Input

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

Output

Returns:

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

Notes:

  • keyword is the user's original query
  • analysis.primary_keyword is the recommended ranking-backed primary keyword target
  • results contains only the pages actually used in the analysis and each item includes analysis_rank

OpenAPI Summary

Auth

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

Billing

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

Keyword Analysis

  • POST /keyword-analysis/analyze

Discovery

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

Account and Billing Endpoints

GET /auth/account-status

Get verified status, billing status, and free-search availability.

GET /auth/usage-summary

Get free usage, paid usage, successful searches, and failed searches.

POST /billing/start-billing-setup

Return a hosted Stripe URL for payment-method setup or billing management.

POST /billing/stripe/webhooks

Stripe webhook endpoint for billing state updates.

Example Flows

1. Create Account

Request:

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

Response:

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

In development, delivery_method may be console and verification_code may be included directly.

2. Verify Account

Request:

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

Response:

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

3. Check Account Status

Response:

{
  "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. Run Keyword Analysis

Request:

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

Response shape:

{
  "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. Start Billing Setup

Response:

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

Billing-Required Response Pattern

When free usage is exhausted and billing is not configured, the API may return HTTP 402 with a detail object like:

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

Billing Model

  • First 25 successful searches are free
  • Billing is only required after free usage is exhausted
  • Failed searches should not be billed
  • Successful searches are metered per completed keyword-analysis request

Agent Guidance

  • If account creation returns a verification code in development, use it directly
  • In production, ask the human to check email for the code
  • If analysis returns a billing-required response, show the hosted billing URL to the user
  • Prefer top_n_results=5 unless a larger competitive sample is necessary
  • Use include_page_content=false by default to minimize payload size

Best Practices For Agents

  • Treat create-account and verify-account as a two-step handshake
  • Do not retry verification blindly after a wrong code; ask the user to re-check email
  • Store the returned API token securely for future calls
  • On HTTP 402, pause analysis flow and present the hosted billing URL to the human
  • Retry transient upstream failures conservatively; avoid repeated search bursts
  • Do not assume every SERP request will return the same ranking set across time and geography
  • Treat analysis.primary_keyword as the recommended target and keyword as the user's original query
  • Use account-status before prompting the user for billing if you are unsure whether free usage remains
  • Consider usage-summary the source of truth for agent-side quota messaging
  • Default to 5 results for speed and cost unless the user explicitly asks for deeper analysis
  • If partial scraping occurs but a valid analysis returns, treat the request as successful unless the API says otherwise

Discovery Endpoints

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

Notes

  • This service is optimized for fast, structured keyword analysis rather than broad SEO suite workflows
  • It is intended to be easier and cheaper to use than a full SEO platform when the only need is quick live keyword research