Track Google keyword rankings by country
Get Google results for any query as JSON with position, title, URL, snippet, date and related searches, to track your rank and competitors by country.
You want to know where your page ranks for the keywords that matter, in the country that matters, and who is above you. Checking by hand gives you a result shaped by your own location and history. Lovely Router runs the search for you. Send a keyword and a country, get one JSON object per results page, pay per page from a prepaid balance. Call it from a script, a daily job or an AI agent with one API key.
Hand it to your AI agent
Copy this prompt into Claude Code, Cursor, Codex or any coding agent. It tells the agent where the docs are and how to use your API key.
Track Google keyword rankings by country. Use the Lovely Router data tools: each returns JSON and is billed per result.
- Docs (read first): https://lovelyrouter.com/docs/tools/find.md and https://lovelyrouter.com/docs/tools/run.md
- Plan first: POST https://lovelyrouter.com/v1/tools/suggest with `{"task": "<my task in plain words>"}` (free). It returns the tools to run in order, each with an example `input`, the `input_required` fields, an estimated cost and a ready-made `run` request. Replace the example values with my task's; if a field is unclear, read the tool with GET https://lovelyrouter.com/v1/tools/<id>. To browse instead, POST https://lovelyrouter.com/v1/tools/discover searches the catalog.
- Show me the plan and its estimated cost (`total_est_cost_usd`) before running anything large.
- Run: POST https://lovelyrouter.com/v1/tools/<id>/run with `{"input": {...}, "max_results": N}`. A 200 has the finished run with `items`; a 202 means it is still running, so poll the `poll` path until `status` is `succeeded`, `failed`, `timed_out` or `stopped`.
- Only delivered results are billed. Keep max_results small on the first run, check the output, then scale up.
- If you support MCP, connect https://lovelyrouter.com/mcp instead (Streamable HTTP, same key; https://lovelyrouter.com/docs/tools/mcp.md) and use suggest_tools, get_tool and run_tool.
- Auth: read my API key from the LOVELY_API_KEY environment variable and send it as `Authorization: Bearer $LOVELY_API_KEY`. Never print or commit the key. If it is not set, ask me to create one at https://lovelyrouter.com/app/keys.
- Billing is prepaid: every call is charged to my balance, so test with a small request before running anything large.
- Every docs page is plain Markdown; the full index is https://lovelyrouter.com/llms.txt.
My task: <the inputs (links, keywords or accounts) and how many results you need>How it works
List keywords and countries
One keyword per run line, with the ISO country code you care about.
hlsets the language.Run the tool with a cap
Send them with
limitandmax_results. Each results page holds about 10 links and is one billed result.Store positions
Save the position of your URL and each competitor's per keyword and per day, and chart the changes.
Get Google results with one request
Search Google takes a keyword, a country and limit, the number of results per search (10, 20, up to all):
curl https://lovelyrouter.com/v1/tools/google-search/run \
-H "Authorization: Bearer $LOVELY_API_KEY" \
-H "content-type: application/json" \
-d '{
"input": {
"keyword": "best espresso grinder",
"limit": "10",
"country": "US"
},
"max_results": 1
}'tbs adds a time filter, for example the past day or week, and hl sets the Google interface language. A run still going after 60 seconds returns 202; Run a tool shows how to poll.
What each results page holds
| Field group | What you get |
|---|---|
| Organic results | Position, title, URL, snippet and date |
| Extras | Sitelinks |
| Related | Related searches |
One result is one results page of about 10 links, so reading the top 50 is 5 results. Cap a run with max_results, which can be at most 10.
Recipes
Run your 30 keywords each morning with limit at 10 and store the position of your domain.
Run the same keyword with US, GB and DE and see where your page ranks.
Collect the top 20 for your target keywords and count which domains appear most.
Use the related searches of a seed keyword as the next batch of keywords to track.
Use the tbs filter for the past week to see what has been published recently on a topic.
Prefer plain words? Connect the MCP server and tell Claude Code or Cursor: "Search Google in the US for each keyword in keywords.txt, find where example.com ranks, and list the top three competing domains per keyword. Set max_results to 10."
Pair it with other search sources
Organic rankings are one view. Add:
Google results pages for a query: organic results (position, title, URL, snippet, date, sitelinks) and related searches. One result = one results page (~10 links).
News articles from Google News for a search (operators work: "exact phrase", OR, -word, site:, intitle:), optionally within a time window: title, source, date and the article's link on the publisher's site.
Google Trends interest over time and by region for a keyword.
google-newsshows news results for the same topic.google-trendsshows how interest in a keyword changes over time.
For the wider job, see web data extraction and research agents.
What you pay
You pay per page: starting a run holds its maximum cost, the per-call fee plus the per-page fee times max_results, and the run settles to what it returned. The rest of the hold goes back to your balance. A run that fails or times out pays only for the pages it delivered, and a run refused at the start costs nothing.
Tracking 30 keywords at 10 results each is billed as 30 pages a day. There is no subscription and no monthly minimum: top up from $5, and one balance pays for tools and models. The card above shows today's price; pricing lists every tool.
Frequently asked questions
How many results per keyword can I get?+
limit can be 10, 20, 30, 40, 50, 100 or all. Every 10 results are one page and one billed result, and max_results caps a run at 10 pages.
Can I check rankings in other countries?+
Yes. Set country to an ISO 3166 A-2 code such as US, GB or DE. hl sets the interface language.
+
Yes. Organic results include sitelinks, and the page includes related searches.
Can I limit to recent pages?+
Yes, with tbs, for example past day or week, or a custom date range.
Do I need a subscription?+
No. You add credit to a prepaid balance and each run draws it down. Nothing renews automatically.
More on the same theme: web data extraction, research agents and the tool catalog.