A Google query is only part of a search request. Someone researching London and someone researching Singapore may need different results for the same words. This guide shows how to request a country, interface language and city, then collect a small number of result pages without counting duplicate URLs twice.
You will build a Python 3 script that saves both the results and the search settings returned by the API. If you are making your first request, start with Google search results to CSV.
What gl, hl and location control
glis the two-letter country code, such asgb,usorsg.hlselects the Google interface language, such asenorde. It is not a guarantee that every returned page is written in that language.locationrequests a search location. Use a clear city name, such asLondon, England, United Kingdom, when local context matters.
Use these parameters together when you want an explicit search configuration. A location is a request to the search source, not a guarantee of identical results to a particular person’s browser. Search type, query, timing and available data can affect the response. Inspect results[0].searchParameters instead of assuming the service applied every value unchanged.
Prepare your API key and request budget
Create an API key and make sure the account has available Credits. Store the key in your environment, not in source control or browser JavaScript. The code uses only Python’s standard library.
export FLASHDATA_API_KEY='your-api-key'
export SEARCH_QUERY='coworking spaces'
export SEARCH_COUNTRY='gb'
export SEARCH_LANGUAGE='en'
export SEARCH_LOCATION='London, England, United Kingdom'
export SEARCH_MAX_PAGES='3'
num requests 1–100 results and page accepts 1–100. Returned counts can be smaller than the requested count. Each page is a separate billable request. This example requests up to three pages, stops on an empty page, and does not automatically retry failed submissions.
Collect localized results and preserve their context
Save this as localized-search.py. It records the requested page alongside each result, keeps the original position if one is returned, and removes only exact duplicate URLs. It deliberately does not calculate a global ranking from (page - 1) × num: the returned count can vary.
import json
import os
from pathlib import Path
from urllib.error import HTTPError
from urllib.request import Request, urlopen
key = os.environ["FLASHDATA_API_KEY"]
max_pages = int(os.getenv("SEARCH_MAX_PAGES", "3"))
if not 1 <= max_pages <= 100:
raise ValueError("SEARCH_MAX_PAGES must be between 1 and 100")
query = os.getenv("SEARCH_QUERY", "coworking spaces")
settings = {
"gl": os.getenv("SEARCH_COUNTRY", "gb"),
"hl": os.getenv("SEARCH_LANGUAGE", "en"),
"location": os.getenv("SEARCH_LOCATION", "London, England, United Kingdom"),
"num": 10,
}
rows, pages, seen = [], [], set()
for page in range(1, max_pages + 1):
payload = {"source": "google_search", "query": query,
"params": {**settings, "page": page}}
request = Request(
"https://data.flashdata.dev/v1/queries/realtime",
data=json.dumps(payload).encode(), method="POST",
headers={"Content-Type": "application/json", "X-API-Key": key},
)
try:
with urlopen(request, timeout=60) as response:
body = json.load(response)
except HTTPError as error:
raise RuntimeError(f"Search failed: HTTP {error.code}. Check the request and account before resubmitting.") from error
if body.get("error") or body.get("status") != "done":
raise RuntimeError("Search did not complete. Check Request History before resubmitting.")
if not isinstance(body.get("results"), list) or not body["results"]:
raise RuntimeError("Expected a search result object")
result = body["results"][0]
organic = result.get("organic", [])
pages.append({"requestedPage": page, "requestedParams": payload["params"],
"reportedParams": result.get("searchParameters"),
"returnedCount": len(organic), "usage": body.get("usage")})
for item in organic:
link = item.get("link")
if link and link not in seen:
seen.add(link)
rows.append({"requestedPage": page, **item})
if not organic:
break
Path("localized-results.json").write_text(
json.dumps({"query": query, "pages": pages, "organic": rows}, indent=2),
encoding="utf-8",
)
print(f"Saved {len(rows)} unique URLs from {len(pages)} pages")
python3 localized-search.py
Read the output before comparing markets
The JSON file contains a pages entry for each completed request and an organic array of unique links. Keep requestedParams and reportedParams with your data. An absent field should remain absent or null; do not manufacture a country or location value for a response that did not report one.
To compare two markets, keep the query and requested page budget consistent and change the country, language and location deliberately. Record collection time in your application if you need historical comparisons. Different result sets are observations from those requests, not proof of a permanent rank change.
Why might a page contain fewer results?
Search results can include rich features as well as organic links, and the source may return fewer organic items than requested. Count the returned array. An empty organic page is a reasonable stopping condition for this small script; it does not establish that Google has no other relevant pages.
For 401/403 errors, check the API key and permissions. For credit or rate-limit errors, resolve the account or request-rate issue first. A network timeout does not prove that a paid request was never executed; inspect Request History before submitting it again.
Continue with the Google Search API parameter reference, async and batch guide, or Google Search product overview.