keyword_ideas

POST https://geondex.com/api/v1/keyword-ideas

• Cost: 7 credits
• MCP tool: keyword_ideas
• Auth: Authorization: Bearer gx_… (see Authentication)
• Try it: Open keyword_ideas in the playground

Keyword ideas around a seed phrase with measured Google search volume, CPC, difficulty (0-100) and search intent — an agent can brainstorm phrases but cannot measure them. mode: suggestions = phrases containing the seed, related = what Google shows as related searches, ideas = same-topic phrases that may not contain the seed. Default United States, English; set location and language to change that. 7 credits per call, up to 100 ideas. Feed the best ones to ai_keyword_volume and check_visibility.

Not available on every deployment: returns 404 not_found when this server is not configured for it. GET /me lists what is configured.

RequestCopy Anchor Link

Request body (JSON)Copy Anchor Link

• keyword · string · required — The seed phrase, e.g. table tennis blade. 1–200 characters
• mode · "suggestions" | "related" | "ideas" · optional — suggestions: longer phrases that contain the seed. related: what Google shows as related searches for the seed. ideas: phrases on the same topic, even without the seed's words. Default "suggestions"
• location · string · optional — Country or city by name, e.g. United States, Germany, or London,England,United Kingdom. 2–100 characters. Default "United States"
• language · string · optional — Language by name, e.g. English, German. 2–50 characters. Default "English"
• limit · integer · optional — How many ideas to return, 1-100. Same price for any limit. 1–100. Default 20

Example requestCopy Anchor Link

curl -s https://geondex.com/api/v1/keyword-ideas -H "Authorization: Bearer gx_YOUR_KEY" -H "content-type: application/json" -d '{"keyword":"table tennis blade","limit":3}'

ResponseCopy Anchor Link

200 with the envelope every tool returns: a one-line summary, the full data, and credits: { charged, remaining }. On a free call charged is 0 and remaining is null.

Fields of dataCopy Anchor Link

• seed · string
• mode · "suggestions" | "related" | "ideas"
• total · number — How many ideas exist for this seed; ideas holds the first limit
• ideas · object[]
• ideas[].keyword · string
• ideas[].volume · number | null — Average monthly Google searches; null when unknown
• ideas[].cpc · number | null — Average cost per ad click, USD
• ideas[].competition · string | null — Google Ads competition: LOW, MEDIUM or HIGH
• ideas[].difficulty · number | null — How hard it is to reach Google's top 10, 0-100
• ideas[].intent · string | null — Main search intent: informational, navigational, commercial or transactional

Example responseCopy Anchor Link

Real-shaped, checked against the output schema by a test. Long lists are shortened.

{
  "summary": "3 of 412 ideas for \"table tennis blade\"; highest volume \"best table tennis blade\" at 1900/mo.",
  "data": {
    "seed": "table tennis blade",
    "mode": "suggestions",
    "total": 412,
    "ideas": [
      {
        "keyword": "best table tennis blade",
        "volume": 1900,
        "cpc": 0.71,
        "competition": "HIGH",
        "difficulty": 21,
        "intent": "commercial"
      },
      {
        "keyword": "table tennis blade for beginners",
        "volume": 480,
        "cpc": 0.62,
        "competition": "HIGH",
        "difficulty": 14,
        "intent": "commercial"
      },
      {
        "keyword": "how to choose a table tennis blade",
        "volume": 170,
        "cpc": null,
        "competition": null,
        "difficulty": null,
        "intent": "informational"
      }
    ]
  },
  "credits": {
    "charged": 7,
    "remaining": 158
  }
}

ErrorsCopy Anchor Link

Every error has the body {"error":{"code":"…","message":"…"}} and is not charged.

Every error.code and what to do about it: Errors & rate limits.