The PlaceGrid API

Google Maps places for any region, with the contacts their own websites publish — as structured data for your code and your AI agents.

Preview. This page describes the API as it is being built. Endpoint names, fields and limits may still change before the first stable version.

PlaceGrid collects the businesses of a category inside a region boundary you choose, tells you how many there are before anything is charged, and returns each place as one structured record. On request it reads each business’s own website for e-mails and social profiles.

---

Concepts

• Region — an area taken from the map’s own boundaries: a country, a region, a city or a district. A scan covers exactly that area and nothing outside it.
• Category — the kind of business, as Google Maps classifies it (dentist, café, hotel …).
• Estimate — a free preview of a scan: roughly how many places, what share of them lists a website or a phone, and the price.
• Scan — the actual collection run for one or more regions and categories.
• Place — one business, identified by its Google Maps place ID. The same place never appears twice in one scan, and a later scan can skip places you already have.
• Enrichment — contact details found on the business’s own website: e-mail addresses and links to its social profiles.

---

Authentication

Create an API key on your account page and send it with every request:

Authorization: Bearer <your API key>

Keys belong to your account. Treat them like passwords; revoke a key on the account page the moment it may have leaked.

---

Endpoints (planned)

Method	Path	What it does
POST	/api/v1/estimates	Estimate a scan for regions and categories — free
POST	/api/v1/scans	Start a scan
GET	/api/v1/scans/{id}	Progress and counters of a scan
GET	/api/v1/scans/{id}/places	The places of a scan, as JSON, CSV or Markdown
POST	/api/v1/enrich	Enrich places you already know by their place IDs

---

Fields of a place

Field	Meaning
placeId	Google Maps place ID — stable across scans
name, category	As the listing shows them
address, lat, lng	Location
phone, website	Contacts from the listing
rating, reviewCount	Current rating and number of reviews
openingHours	Weekly opening hours
emails, socials	Found on the business’s own website (enrichment)
fetchedAt	When the record was collected

---

Present, absent, unknown

Every optional field is in one of three states, and the API says which:

• present — the value was found;
• absent — it was looked for and does not exist (for example, the listing has no website);
• unknown — it was not checked, or checking failed.

“No website” and “not checked” are different answers, and a lead list built on the first is not the same as one built on the second.

---

What is not charged

Failed requests, duplicates, and places outside the region you chose are not charged. An estimate is free.

---

Errors

Every error comes back as JSON with a stable code, a message and, where there is one, a hint on what to do next:

{ "code": "…", "message": "…", "hint": "…" }