Serper.live now runs live Google searches in 114 countries. At the end of October it was six. That's enough to answer a question that used to take a pile of proxies and a spreadsheet: where does my site rank for this keyword, everywhere at once?
This post builds that check with the Python standard library. One public call for the list of markets, one live search per market, a CSV out. A sweep of the top 10 in all 114 markets costs $0.57.
Disclosure: we build Serper.live, the API used here.
The plan
-
GET /v1/countriesreturns every open market with its default Google interface language. It's public, so no token is needed. -
POST /v1/searchruns once per market, eight at a time. - The script looks for your domain in
organic[]and stores the position, the URL that ranks and the domain at #1. - It sums
priceandfreePagesfrom the responses, so it reports what the sweep actually cost.
The bill, before you run it
At limit 10, each market is one page, and a page costs $0.005 in every market. 114 × $0.005 = $0.57 for a desktop sweep, $1.14 if you run mobile as well. A new account comes with 100 free searches, which are used before the balance. Only pages that received results are charged, and a search that finds nothing costs nothing.
The script
Save it as serp_world.py. It needs Python 3.10 or newer and nothing else.
"""Run one live Google search in every Serper.live market and report where a domain ranks. Usage: SERPER_LIVE_TOKEN=... python3 serp_world.py "running shoes" example.com [desktop|mobile] [DE,FR,...] > world.csv """ import csv import json import os import sys import time import urllib.error import urllib.request import uuid from concurrent.futures import ThreadPoolExecutor API = os.environ.get("SERPER_LIVE_API", "https://api.serper.live") RETRYABLE = {408, 424, 503} BACKOFF = (5, 15, 45) WORKERS = 8 def call(path, body=None, headers=None): request = urllib.request.Request( API + path, data=None if body is None else json.dumps(body).encode(), headers={"Content-Type": "application/json", **(headers or {})}, method="GET" if body is None else "POST", ) with urllib.request.urlopen(request, timeout=100) as response: return json.load(response) def search(query, country, device): key = str(uuid.uuid4()) for pause in (*BACKOFF, None): try: return call( "/v1/search", {"query": query, "country": country, "device": device, "limit": 10}, {"Authorization": f"Bearer {os.environ['SERPER_LIVE_TOKEN']}", "Idempotency-Key": key}, ) except urllib.error.HTTPError as error: if error.code not in RETRYABLE or pause is None: raise key = str(uuid.uuid4()) except (urllib.error.URLError, TimeoutError): if pause is None: raise time.sleep(pause) def host(value): value = value.lower() return value[4:] if value.startswith("www.") else value def check(query, domain, device, market): row = {"country": market["code"], "language": market["defaultLanguage"], "position": "", "url": "", "leader": "", "price": 0, "free_pages": 0, "error": ""} try: data = search(query, market["code"], device) except urllib.error.HTTPError as error: row["error"] = f"{error.code} {json.loads(error.read() or b'{}').get('error', '')}".strip() return row except (urllib.error.URLError, TimeoutError) as error: row["error"] = f"network: {error}" return row organic = data["organic"] hit = next((r for r in organic if host(r["domain"]) == domain or host(r["domain"]).endswith("." + domain)), None) row.update( language=data["language"], position=hit["position"] if hit else "", url=hit["url"] if hit else "", leader=organic[0]["domain"] if organic else "", price=data["price"], free_pages=data["freePages"], ) return row def main(): query, domain = sys.argv[1], host(sys.argv[2]) device = sys.argv[3] if len(sys.argv) > 3 else "desktop" only = set(sys.argv[4].upper().split(",")) if len(sys.argv) > 4 else None markets = [m for m in call("/v1/countries")["countries"] if only is None or m["code"] in only] if not markets: sys.exit("No open market matches the requested codes.") with ThreadPoolExecutor(max_workers=WORKERS) as pool: rows = list(pool.map(lambda m: check(query, domain, device, m), markets)) writer = csv.DictWriter(sys.stdout, fieldnames=rows[0].keys()) writer.writeheader() writer.writerows(sorted(rows, key=lambda r: (r["position"] == "", r["position"] or 0, r["country"]))) found = [r for r in rows if r["position"] != ""] failed = [r for r in rows if r["error"]] print( f"{domain} is in the top 10 in {len(found)} of {len(rows)} markets; " f"cost ${sum(r['price'] for r in rows):.3f}, free pages used {sum(r['free_pages'] for r in rows)}, " f"failed {len(failed)}", file=sys.stderr, ) if __name__ == "__main__": main() Run it with your token:
export SERPER_LIVE_TOKEN=your-token python3 serp_world.py "running shoes" example.com mobile > world.csv The fourth argument narrows the sweep to a list of codes, which is handy for a first run or a regional report:
python3 serp_world.py "running shoes" example.com desktop KE,NG,GH,ZA,EG The parts worth explaining
Concurrency. Searches run concurrently up to the service capacity, and beyond it the API answers 503 busy. Eight workers keep a full sweep short without leaning on that limit, and the retry absorbs an occasional busy answer.
Timeouts. A live search usually takes 2–3 seconds for a page of 10 results. The first request to a market after a pause takes longer, because a fresh Google session opens in that country, and a first sweep touches 114 markets. A search still running after 90 seconds ends with 408 search_timeout, so the client timeout is 100 seconds.
Retries without double billing. 408, 424 and 503 are never charged. The script retries them after 5, 15 and 45 seconds with a new Idempotency-Key, because the same key would replay the same error. A dropped connection is the opposite case: you don't know whether the search finished, so the retry keeps the key. If the first search did finish, the API replays its response instead of charging again.
Matching. Domains are compared as hosts: lower-case, without a leading www.. Subdomains count as your site here, so shop.example.com matches example.com. For a strict tracker, compare exact hosts instead. No match means "not in the top 10 for this check", not an error.
Errors stay in the report. A 402 insufficient_balance doesn't abort the sweep. It lands in the error column for that market, and the summary counts it.
What comes out
Rows are sorted by position, then the markets where the domain isn't in the top 10. This sample is from a local mock of the API with example.* domains, so the numbers mean nothing beyond the format:
country,language,position,url,leader,price,free_pages,error DE,de,1,https://www.example.com/de/,www.example.com,0,1, KE,en,3,https://shop.example.com/ke,site1.example,0,1, US,en,7,https://example.com/,site1.example,0.005,0, AE,ar,,,site1.example,0,1, MT,en,,,,0,0,402 insufficient_balance The summary goes to stderr: in how many markets the domain made the top 10, the cost of the sweep and how many free pages it used.
Where to take it next
- Run both devices. Two sweeps, then join on
country: the same market on desktop and mobile often disagrees. - Set the language. Each market uses its default
hl, such asswin Tanzania orkmin Cambodia. For a market that searches in two languages, add"language": "fr"to the body (French-speaking Canada, for example) and treat it as a separate keyword. - Keep history. Store each sweep with the
fetchedAtof every response and compare week over week. - Go deeper. Raise
limitto 30 or 100 to see positions beyond the top 10. Each started block of 10 is one page.
The API docs cover every field and error. The market list lives at api.serper.live/v1/countries, and the playground runs three live searches a day without an account if you want to look at a market before you script it.
