You search "dentist" across a whole city through the Places API, export what comes back, and the list is obviously short. The search stopped because it hit a per-query ceiling, not because the dentists ran out. The fix is to ask a smaller question many times, and a quadtree scan does that without spending requests on empty areas.
This walkthrough builds that scan against the official API. It also fixes the weak spots in the sketch from a vendor post (Axio Leads on dev.to), which defines "full" by one page's size and has no real cost control. That post discloses that its author works on a Maps data-extraction product. This article does not endorse the product, and none of the code needs it.
All code below is unexecuted. No run output exists for it. Read it, adapt it, and test it on a tiny area before you trust it.
Step 1: Find your real cap, don't assume 120
The vendor post says tools commonly report "roughly 120" results per search, and adds that the number can vary by place, query, and over time. Treat 120 as unverified.
Before running anything, open the current Google Places documentation for the endpoint you use and write down three things:
- the maximum results per page
- the maximum total across pages for one query
- how the next-page token behaves, including whether it needs a delay before use
Put those values in config constants. The script below uses PAGE_SIZE = 20 and QUERY_CAP = 60 as placeholders. They are not claims about the current API.
Step 2: Define "full" by the whole query, not one page
The vendor sketch compares one page's result count to a page size. That goes wrong when the API returns several pages per query: a cell with a full first page looks full even though you haven't seen the rest, and it splits more than it needs to.
A better rule has two parts. First, fetch pages for the cell until the API stops offering a next-page token or you reach the query cap. Second, call the cell full if you hit the cap. If a cell returns exactly the cap, you can't tell whether it had exactly that many or got cut off, so split it anyway. That costs a few extra requests and avoids silent loss.
The search function is pluggable. It takes a bounding box and a keyword, and returns the places plus a "full" flag. Swap in any capped API that fits that contract.
Step 3: Split safely and stop for sure
Split the box at its midpoints into four quadrants. Child boxes share edges, so a business on a boundary can show up twice. That's fine, because you dedupe by place ID later. Don't match on name or address.
Three things guarantee termination:
- Depth increases on every recursive call and stops at
max_depth. - A minimum cell size stops splitting before cells get absurdly small.
- Cells that stop for either reason while still full go into an
incompletelist and get logged, so you know where coverage may be thin.
A hard request budget protects your bill. When the budget runs out, the script stops and you keep everything collected so far.
Step 4: Estimate cost before spending anything
The worst case is every cell splitting down to max_depth. That's (4^(d+1) - 1) / 3 cells, times the pages needed per cell. With the placeholder values (depth 6, three pages per cell), the ceiling is 5,461 cells and 16,383 requests.
Real scans should land far below that, because quiet areas never split. The ceiling shows you what a runaway looks like. Check current Google Maps Platform pricing for your endpoint and field mask, since price depends on which fields you request. We cover related ground in see also: sharp vs cloudinary vs imgix for fixed avatar sizes.
Step 5: The script (unexecuted)
Dependencies: Python 3.10+ and requests. Pin a version you have tested, for example requests==2.32.3, and verify it installs in your environment. The request and response shapes below follow the Places API (New) Text Search style. Confirm field names and the field mask against the current docs before running.
## UNEXECUTED example. Verify endpoint, field mask, and limits against current docs.
import logging
import math
import os
import sys
import requests
logging.basicConfig(level=logging.INFO, format='%(levelname)s %(message)s')
log = logging.getLogger('quadtree')
PAGE_SIZE = 20 # CHECK docs: results per page
QUERY_CAP = 60 # CHECK docs: max total results for one query
MAX_DEPTH = 6
MIN_CELL_METERS = 250 # do not split a cell below this size
MAX_REQUESTS = 500 # hard budget for one run
class BudgetExceeded(Exception):
pass
class Budget:
def __init__(self, limit):
self.limit, self.used = limit, 0
def spend(self):
if self.used >= self.limit:
raise BudgetExceeded('request budget of %d reached' % self.limit)
self.used += 1
def worst_case_requests(max_depth, query_cap, page_size):
cells = (4 ** (max_depth + 1) - 1) // 3
pages = math.ceil(query_cap / page_size)
return cells * pages
def make_places_search(api_key, budget):
url = 'https://places.googleapis.com/v1/places:searchText'
headers = {
'Content-Type': 'application/json',
'X-Goog-Api-Key': api_key,
'X-Goog-FieldMask': 'places.id,places.displayName,places.location,nextPageToken',
}
def search(bbox, keyword):
south, west, north, east = bbox
body = {
'textQuery': keyword,
'pageSize': PAGE_SIZE,
'locationRestriction': {'rectangle': {
'low': {'latitude': south, 'longitude': west},
'high': {'latitude': north, 'longitude': east},
}},
}
out = []
while True:
budget.spend()
resp = requests.post(url, json=body, headers=headers, timeout=30)
resp.raise_for_status() # add backoff for 429/5xx in real use
data = resp.json()
out.extend(data.get('places', []))
token = data.get('nextPageToken')
if len(out) >= QUERY_CAP:
return out, True # hit the cap: treat as full
if not token:
return out, False # API says nothing more: not full
body['pageToken'] = token We cover related ground in [go deeper on pagespeed insights score changed without site changes?](/pagespeed-insights-score-changed-without-site-changes).
return search
def cell_size_m(bbox):
s, w, n, e = bbox
lat_m = (n - s) * 111_320
lng_m = (e - w) * 111_320 * math.cos(math.radians((n + s) / 2))
return min(lat_m, lng_m)
def scan_cell(bbox, keyword, search_fn, collected, incomplete,
depth=0, max_depth=MAX_DEPTH, min_cell_m=MIN_CELL_METERS):
places, full = search_fn(bbox, keyword)
collected.extend(places) # keep parent results; dedupe handles overlap
if not full:
return
if depth >= max_depth or cell_size_m(bbox) / 2 < min_cell_m:
incomplete.append({'bbox': bbox, 'depth': depth, 'returned': len(places)})
log.warning('cell still full at depth %d, coverage may be incomplete: %s', depth, bbox)
return
south, west, north, east = bbox
mid_lat, mid_lng = (south + north) / 2, (west + east) / 2
for quad in [
(south, west, mid_lat, mid_lng),
(south, mid_lng, mid_lat, east),
(mid_lat, west, north, mid_lng),
(mid_lat, mid_lng, north, east),
]:
scan_cell(quad, keyword, search_fn, collected, incomplete,
depth + 1, max_depth, min_cell_m)
def dedupe_by_place_id(results):
seen = {}
for r in results:
pid = r.get('id')
if pid and pid not in seen:
seen[pid] = r
return list(seen.values())
def main():
bbox = (40.70, -74.05, 40.74, -74.00) # placeholder: replace with your small test area
keyword = 'dentist'
worst = worst_case_requests(MAX_DEPTH, QUERY_CAP, PAGE_SIZE)
print('Worst-case requests at depth %d: %d' % (MAX_DEPTH, worst))
if '--dry-run' in sys.argv:
return
budget = Budget(MAX_REQUESTS)
search = make_places_search(os.environ['GOOGLE_MAPS_API_KEY'], budget)
collected, incomplete = [], []
try:
scan_cell(bbox, keyword, search, collected, incomplete)
except BudgetExceeded as exc:
log.error('stopped early: %s', exc)
unique = dedupe_by_place_id(collected)
print('requests used: %d' % budget.used)
print('raw results: %d, unique place IDs: %d' % (len(collected), len(unique)))
print('cells needing review (full at depth/size limit): %d' % len(incomplete))
if __name__ == '__main__':
main()
Expected output shape (illustrative only, not from a real run; your numbers will differ):
Worst-case requests at depth 6: 16383
WARNING cell still full at depth 6, coverage may be incomplete: (40.7, -74.05, 40.7006, -74.0494)
requests used: 148
raw results: 1312, unique place IDs: 1047
cells needing review (full at depth/size limit): 1
The gap between raw and unique is the overlap you should expect. If the two numbers are equal on a multi-cell scan, check that dedupe is actually running.
Also read: rds inaccessible encryption credentials: kms triage guide
Verify before a full run
- Run
--dry-runand compare the worst-case figure with your budget and pricing. - Pick a small area you know well, such as a few blocks, and run the real scan with a low
MAX_REQUESTS. - Pick 10 to 20 businesses you can name from local knowledge and confirm each one appears among the unique place IDs.
- Add a counter in a test run and confirm that no leaf cell came back full except the ones listed in
incomplete. - Re-run with
MAX_DEPTHone level higher. If the unique count jumps, your earlier depth was truncating coverage.
Failure cases to plan for
| Problem | What you see | Fix |
|---|---|---|
| Exact-cap ambiguity | A cell returns exactly the cap and may have been cut off | Treat count >= cap as full and split; the cost is a few extra requests |
| Boundary duplicates | Raw count exceeds unique count, same business in neighboring cells | Dedupe by place ID only, never by name or address |
| max_depth truncation | Warnings for cells still full at the limit | Review the incomplete list; raise depth or lower minimum cell size for those cells only, and re-check your budget |
| Rate limits or quota overruns | HTTP 429 or quota errors, or a surprise bill | Keep the request budget, add exponential backoff, set quotas in your Google Cloud project |
| Terms of service | Account warnings, blocked keys | Use the official API with your own key, read Google Maps Platform terms for what you may store and for how long, and don't scrape the Maps website |
When this isn't worth it
If you only need the top results for a small town, one search is enough. If your area is evenly dense, a fixed grid is simpler and the quadtree adds little. That's an inference from how the recursion works, not a measured result.
If your problem is category coverage rather than geographic coverage, vary the keywords ("dentist", "dental clinic", "orthodontist") and dedupe the combined output. The vendor post suggests the same thing. Keyword variation goes straight at that problem, where deeper splitting does not.
Even a clean scan is not a census. Listings can be missing, miscategorized, or closed but unmarked, so treat the result as a large sample of what the API shows.
What to expect next
Your first real run may flag a few cells at the depth limit in the densest part of town. Re-scan only those boxes with a tighter cell size and a fresh budget, rather than raising depth everywhere. Check the current docs again every so often, too, since the cap and pagination rules are the one part of this design you don't control.



