If you want a competitor keywords API that a coding agent can call, the useful properties are a clear price per call, a hard cap the agent can set, and output structured enough to sort without scraping. seogeoaeo.ai exposes its Competitor Keywords tool over both REST and MCP with those three things, so an agent in Claude Code, Cursor or Codex can pull a rival's ranking keywords and hand you a shortlist.
What one call returns #
You send a domain, or any URL on it, and an optional market code. The tool looks up the whole domain in Google data for that country and returns up to 100 keywords, ordered by estimated traffic. Each row carries:
- keyword and the ranking URL
- position
- monthly search volume
- difficulty
- search intent
- cost per click
- estimated visits
On top of the rows it adds two derived lists and a page summary: blog topics (informational, difficulty 50 or less, at least 10 searches a month, competitor's own name excluded), keywords worth bidding on (commercial or buying searches with a CPC), and the pages bringing the site the most visits.
Supported markets are us, gb, ca, au, ie, in, sg, nz, za, de, fr, es, it, nl, se, pl, br, mx, jp and ae.
The REST call #
curl -X POST https://seogeoaeo.ai/api/v1/tools/competitor-keywords/runs \
-H "Authorization: Bearer $SEOGEOAEO_API_KEY" \
-H "Content-Type: application/json" \
-d '{"input":{"url":"https://rival.example","market":"gb"},"maxCredits":35}'
maxCredits makes the server refuse the run if the price is above what you set, with a max_credits_exceeded error. Add an idempotencyKey and a retry after a timeout will not charge you twice. The full reference is in llms-full.txt.
The MCP route #
Point your MCP client at https://seogeoaeo.ai/api/mcp with a workspace API key. The tool name is the slug, competitor-keywords, and it accepts the same url, market, maxCredits and idempotencyKey arguments. Agent runs cost the same as runs from the browser.
A prompt that works well:
Run competitor-keywords on rival.example for the US market with maxCredits 35. Drop brand searches. Return keywords where the rival ranks 8 to 20, grouped by ranking URL.
Cost and failure rules #
| Case | Charge |
|---|---|
| Normal run | 35 credits, shown before it starts |
| Site found but no rankings | Charged; the report says nothing was found |
| Provider has no record of the site | Refunded |
| Run ends in a 502 or 503 | Refunded |
Credits come from a monthly plan, starting at $29 for 2,000. Monthly credits reset at renewal; top-ups bought on an active plan never expire. Details on the seogeoaeo.ai plans page.
Limits to code around #
- Whole domain only. A URL is accepted as input, but the lookup is for the domain. Filter by ranking URL yourself if you care about one folder.
- One country per call. Loop over markets if the rival sells in several, and keep the market in your output so numbers from different countries never get mixed.
- Estimates. Volume, difficulty and visits come from a search data provider, not Google. Compare within one result set; do not diff totals against another vendor's API.
- No ad bids. It does not return keywords a competitor bids on in Google Ads. Google does not publish them.
- No history. Each call is a snapshot. It is not a rank tracker; if you need daily positions for your own site over months, a product with rank tracking, such as Semrush Position Tracking, fits that better. You can still store snapshots yourself and diff them month to month.
Chaining it #
Two neighbours make the call more useful in an agent loop. Competitor Finder (38 credits) returns the 30 sites sharing the most Google keywords with a domain, so the agent can pick which rivals to look up instead of guessing. Keyword Metrics (33 credits) takes up to 100 keywords you already have and returns volume, difficulty, CPC and yearly trend, which is handy for re-checking a shortlist built from several competitors.
A full loop for three rivals costs about 38 + 3 × 35 = 143 credits, and with maxCredits on each call the agent cannot overspend.