---
title: "SEO keyword research from a seed keyword or topic. Uses Google Suggest (public, keyless) to discover related queries at"
method: POST
path: "/api/v1/call/seo_keyword_research"
tags: ["expertise"]
---

# SEO keyword research from a seed keyword or topic. Uses Google Suggest (public, keyless) to discover related queries at

`POST /api/v1/call/seo_keyword_research`

## Request

- Base URL: `https://mcp.gapup.io`
- URL: `https://mcp.gapup.io/api/v1/call/seo_keyword_research`
- Auth: HTTP bearer

SEO keyword research from a seed keyword or topic. Uses Google Suggest (public, keyless) to discover related queries at 2 expansion levels, then clusters them by intent: informational / commercial / transactional / navigational — via heuristic pattern matching. Search volume is bucketed (very_high / high / medium / low / very_low) and clearly labelled as ESTIMATED — no fabricated precise numbers. Returns all keywords, intent clusters, quality scores (0-100), and top 10 opportunities. Supports country (gl) and language (hl) targeting. 100% keyless. Cache TTL 6h. ICP: SEO managers, content strategists, SaaS founders, agency teams.

## Request body

- object
  - `seed_keyword` string, required: The seed keyword or topic to research (e.g. 'invoice software', 'project management tool')
  - `country` string: ISO 3166-1 alpha-2 country code for Google Suggest (e.g. 'US', 'FR', 'DE'). Defaults to 'US'.
  - `language` string: BCP-47 language code for suggestions (e.g. 'en', 'fr', 'de', 'es'). Defaults to 'en'.
  - `async` boolean: If true, returns a job_id immediately (<200ms) instead of waiting for the result. Poll the result with job_result(job_id). Use for slow tools to avoid client timeouts.

## Response `200`

Tool result

- object
  - `tool` string
  - `result` object
    - `seed_keyword` string, required
    - `country` string, required
    - `language` string, required
    - `total_keywords` number, required
    - `clusters` object[], required
      - `intent` 'informational' | 'commercial' | 'transactional' | 'navigational'
      - `keywords` unknown[]
        - unknown
      - `count` number
    - `all_keywords` unknown[], required
      - unknown
    - `top_opportunities` unknown[], required
      - unknown
    - `warnings` string[], required
    - `quality_score` number, required
    - `status` 'partial' | 'final' | 'failed', required
  - `request_id` string
  - `source` 'rest-api'
  - `ms` number

## Other responses

- `400`: Invalid arguments
- `401`: Unauthorized
- `402`: Payment Required — pay via x402 (USDC on Base) then retry with X-Payment header
- `404`: Tool not found
- `429`: Rate limited
- `500`: Internal error

---

[API](https://skmtc.dev/gapup/apis/gapup-mcp-rest-api.md) · [All operations](https://skmtc.dev/gapup/apis/gapup-mcp-rest-api/llms.txt) · [OpenAPI document](https://skmtc.dev/gapup/apis/gapup-mcp-rest-api/revisions/afb9da3b98f4?raw)