How do you get Google Maps places data via API?
Call ReefAPI's google-maps place/search action with a query and read business records - names, ratings, categories, addresses, coordinates, websites and phone numbers - back as JSON. The thing worth learning before you build on it is place identity: the response carries three different ids, and only one of them is derivable from another.
This guide demonstrates the real Google Maps API engine with a captured response from . The example is only published because the engine passed the SEO snapshot gate.
Local lead generation, store discovery, review monitoring and location intelligence.
Call the live endpoint
- 1
Search with category plus location in one string
query 'specialty coffee Times Square' works; adding lat and lng biases the result set toward that point rather than filtering to it. maxResults caps the list.
- 2
Keep fid as the primary key
cid is derivable from it (the decimal of the second hex half) and place_id currently mirrors it. entity_id is a Knowledge Graph mid and only exists for notable places.
- 3
Call place/detail when you need review_count
Search returns rating without review_count on every row we measured. Detail returns both, plus the full category list and the maps_url.
- 4
Turn on include_contacts and log the hit rate
meta.contacts_enriched against meta.contacts_attempted tells you how many businesses actually published an email. Ours was 2 of 5, which is normal, not broken.
- 5
Pull reviews by id, not by query
Once you have fid or cid, place/reviews accepts it directly. Sort by newest, dedupe on review_id, and use the ISO date rather than the relative one for storage.
Copy the request
These snippets use the captured request params for google-maps/v1/place/search.
curl -X POST https://api.reefapi.com/google-maps/v1/place/search \
-H "x-api-key: $REEF_KEY" \
-H "content-type: application/json" \
-d '{"query":"specialty coffee Times Square","lat":40.7589,"lng":-73.9881,"maxResults":10}'import requests
r = requests.post(
"https://api.reefapi.com/google-maps/v1/place/search",
headers={"x-api-key": REEF_KEY},
json={
"query": "specialty coffee Times Square",
"lat": 40.7589,
"lng": -73.9881,
"maxResults": 10
},
)
print(r.json()["data"])const res = await fetch("https://api.reefapi.com/google-maps/v1/place/search", {
method: "POST",
headers: {
"x-api-key": process.env.REEF_KEY,
"content-type": "application/json",
},
body: JSON.stringify({
"query": "specialty coffee Times Square",
"lat": 40.7589,
"lng": -73.9881,
"maxResults": 10
}),
});
const { ok, data, meta, error } = await res.json();Ask your MCP-connected assistant: call reefapi.google-maps.place/search with {"query":"specialty coffee Times Square","lat":40.7589,"lng":-73.9881,"maxResults":10}.Captured output from ReefAPI
Captured on UTC. The response below is the committed snapshot, including the API envelope and metadata.
{
"method": "POST",
"url": "https://api.reefapi.com/google-maps/v1/place/search",
"headers": {
"x-api-key": "$REEF_KEY",
"content-type": "application/json"
},
"body": {
"query": "specialty coffee Times Square",
"lat": 40.7589,
"lng": -73.9881,
"maxResults": 10
}
}{
"ok": true,
"meta": {
"api": "google-maps",
"endpoint": "place/search",
"mode": "live",
"latency_ms": 1058.8,
"record_count": 10,
"bytes": 108773,
"cache_hit": false,
"completeness_pct": 99,
"query": "specialty coffee Times Square",
"charged_credits": 2,
"version": "1.2.0"
},
"data": {
"places": [
{
"fid": "0x89c259b6c59db77d:0x57cf5d10e4d1b9a5",
"place_id": "0x89c259b6c59db77d:0x57cf5d10e4d1b9a5",
"cid": "6327378328618645925",
"entity_id": "/g/11y31_2b88",
"name": "787 coffee",
"rating": 4.9,
"review_count": null,
"category_primary": "Coffee shop",
"categories": [
"Coffee shop"
],
"address": "245 W 46th St, New York, NY 10036",
"locality": "New York, NY 10036",
"latitude": 40.7597441,
"longitude": -73.9875048,
"website": "https://www.787coffee.com/",
"domain": "787coffee.com",
"phone": "[redacted-contact]",
"phone_display": "[redacted-contact]",
"hours_today": [
"7 AM-9 PM"
],
"photos": [
"https://lh6.googleusercontent.com/-TZOLVWqy2ks/AAAAAAAAAAI/AAAAAAAAAAA/3qu4C5Si7yU/s44-p-k-no-ns-nd/photo.jpg"
],
"photo_count": 1,
"thumbnail": "https://lh6.googleusercontent.com/-TZOLVWqy2ks/AAAAAAAAAAI/AAAAAAAAAAA/3qu4C5Si7yU/s44-p-k-no-ns-nd/photo.jpg",
"maps_url": "https://www.google.com/maps?cid=6327378328618645925"
},
{
"fid": "0x89c2585580e483ab:0xe470684141b3d7a8",
"place_id": "0x89c2585580e483ab:0xe470684141b3d7a8",
"cid": "16460771267523631016",
"entity_id": "/g/11c1xjnyxs",
"name": "For Five Coffee Times Square",
"rating": 4,
"review_count": null,
"category_primary": "Coffee shop",
"categories": [
"Coffee shop",
"Cafe",
"Coffee store",
"Cookie shop",
"Dessert shop",
"Espresso bar",
"Event venue",
"Internet cafe",
"Juice shop",
"Pastry shop"
],
"address": "117 W 46th St, New York, NY 10036",
"locality": "New York, NY 10036",
"latitude": 40.7579144,
"longitude": -73.9831988,
"website": "http://forfivecoffee.com/",
"domain": "forfivecoffee.com",
"phone": "[redacted-contact]",
"phone_display": "[redacted-contact]",
"hours_today": [
"7 AM-7 PM"
],
"photos": [
"https://lh4.googleusercontent.com/-tbMGIa_Z3BI/AAAAAAAAAAI/AAAAAAAAAAA/w5zuKoQaC78/s44-p-k-no-ns-nd/photo.jpg"
],
"photo_count": 1,
"thumbnail": "https://lh4.googleusercontent.com/-tbMGIa_Z3BI/AAAAAAAAAAI/AAAAAAAAAAA/w5zuKoQaC78/s44-p-k-no-ns-nd/photo.jpg",
"maps_url": "https://www.google.com/maps?cid=16460771267523631016"
},
{
"fid": "0x89c25853c46c584d:0x2be347662f0035e",
"place_id": "0x89c25853c46c584d:0x2be347662f0035e",
"cid": "197653116721562462",
"entity_id": "/g/11hbtg2w_k",
"name": "Bird & Branch Coffee Roasters",
"rating": 4.6,
"review_count": null,
"category_primary": "Coffee shop",
"categories": [
"Coffee shop",
"Cafe",
"Corporate gift supplier",
"Dessert shop"
],
"address": "359 W 45th St, New York, NY 10036",
"locality": "New York, NY 10036",
"latitude": 40.7602998,
"longitude": -73.9907758,
"website": "http://www.birdandbranch.com/",
"domain": "birdandbranch.com",
"phone": "[redacted-contact]",
"phone_display": "[redacted-contact]",
"hours_today": [
"7 AM-7:30 PM"
],
"photos": [
"https://lh6.googleusercontent.com/-xsr96q4nW-Q/AAAAAAAAAAI/AAAAAAAAAAA/x1Ek3Z8uPro/s44-p-k-no-ns-nd/photo.jpg"
],
"photo_count": 1,
"thumbnail": "https://lh6.googleusercontent.com/-xsr96q4nW-Q/AAAAAAAAAAI/AAAAAAAAAAA/x1Ek3Z8uPro/s44-p-k-no-ns-nd/photo.jpg",
"maps_url": "https://www.google.com/maps?cid=197653116721562462"
},
{
"fid": "0x89c2590039a5dcd5:0x6e8511816d160c47",
"place_id": "0x89c2590039a5dcd5:0x6e8511816d160c47",
"cid": "7963790763653205063",
"entity_id": "/g/11ynxxy0yk",
"name": "Central Perk Coffee Company",
"rating": 4.1,
"review_count": null,
"category_primary": "Coffee shop",
"categories": [
"Coffee shop"
],
"address": "20 Times Square, New York, NY 10036",
"locality": "New York, NY 10036",
"latitude": 40.759254999999996,
"longitude": -73.984134,
"website": "https://centralperk.com/",
"domain": "centralperk.com",
"phone": "[redacted-contact]",
"phone_display": "[redacted-contact]",
"hours_today": [
"8 AM-11 PM"
],
"photos": [
"https://lh5.googleusercontent.com/-vERexRm-X24/AAAAAAAAAAI/AAAAAAAAAAA/yITiYt4Rqn0/s44-p-k-no-ns-nd/photo.jpg"
],
"photo_count": 1,
"thumbnail": "https://lh5.googleusercontent.com/-vERexRm-X24/AAAAAAAAAAI/AAAAAAAAAAA/yITiYt4Rqn0/s44-p-k-no-ns-nd/photo.jpg",
"maps_url": "https://www.google.com/maps?cid=7963790763653205063"
},
{
"fid": "0x89c25903f53cf951:0xc2c7e3abcb39348f",
"place_id": "0x89c25903f53cf951:0xc2c7e3abcb39348f",
"cid": "14035437090711876751",
"entity_id": "/g/11m7mgfqyx",
"name": "Gumption Coffee",
"rating": 4.5,
"review_count": null,
"category_primary": "Coffee shop",
"categories": [
"Coffee shop"
],
"address": "106 W 45th St, New York, NY 10036",
"locality": "New York, NY 10036",
"latitude": 40.7569259,
"longitude": -73.983446,
"website": "http://www.gumptioncoffee.com/",
"domain": "gumptioncoffee.com",
"phone": "[redacted-contact]",
"phone_display": "[redacted-contact]",
"hours_today": [
"7 AM-6 PM"
],
"photos": [
"https://lh5.googleusercontent.com/-q79K_96SXK0/AAAAAAAAAAI/AAAAAAAAAAA/xI0Mft89yzY/s44-p-k-no-ns-nd/photo.jpg"
],
"photo_count": 1,
"thumbnail": "https://lh5.googleusercontent.com/-q79K_96SXK0/AAAAAAAAAAI/AAAAAAAAAAA/xI0Mft89yzY/s44-p-k-no-ns-nd/photo.jpg",
"maps_url": "https://www.google.com/maps?cid=14035437090711876751"
},
{
"fid": "0x89c258534ee007d3:0xe0bd7e6a43f66106",
"place_id": "0x89c258534ee007d3:0xe0bd7e6a43f66106",
"cid": "16194238829966024966",
"entity_id": "/g/11gcm0vmlz",
"name": "Bluestone Lane Times Square Coffee Shop",
"rating": 4.1,
"review_count": null,
"category_primary": "Coffee shop",
"categories": [
"Coffee shop",
"Bar",
"Cafe"
],
"address": "11 Times Sq, New York, NY 10036",
"locality": "New York, NY 10036",
"latitude": 40.7564652,
"longitude": -73.98978579999999,
"website": "https://bluestonelane.com/coffee-shops/11-times-square-new-york/?y_source=1_ODc5MjkwMS03MTUtbG9jYXRpb24ud2Vic2l0ZQ%3D%3D",
"domain": "bluestonelane.com",
"phone": "[redacted-contact]",
"phone_display": "[redacted-contact]",
"hours_today": [
"6:30 AM-6 PM"
],
"photos": [
"https://lh4.googleusercontent.com/-DsGwvv6gSi8/AAAAAAAAAAI/AAAAAAAAAAA/OjQ3CXxtlXw/s44-p-k-no-ns-nd/photo.jpg"
],
"photo_count": 1,
"thumbnail": "https://lh4.googleusercontent.com/-DsGwvv6gSi8/AAAAAAAAAAI/AAAAAAAAAAA/OjQ3CXxtlXw/s44-p-k-no-ns-nd/photo.jpg",
"maps_url": "https://www.google.com/maps?cid=16194238829966024966"
},
{
"fid": "0x89c259125a931087:0x3d471d4575240620",
"place_id": "0x89c259125a931087:0x3d471d4575240620",
"cid": "4415530143815304736",
"entity_id": "/g/11kgnrjx7t",
"name": "GRIND THE NYC COFFEE SHOP & BAGEL HOUSE",
"rating": 4.8,
"review_count": null,
"category_primary": "Coffee shop",
"categories": [
"Coffee shop",
"Bagel shop"
],
"address": "602 9th Ave, New York, NY 10036",
"locality": "New York, NY 10036",
"latitude": 40.7590839,
"longitude": -73.9918101,
"website": "http://grindnyc.com/",
"domain": "grindnyc.com",
"phone": "[redacted-contact]",
"phone_display": "[redacted-contact]",
"hours_today": [
"7 AM-7 PM"
],
"photos": [
"https://lh4.googleusercontent.com/-K49zThvFiYI/AAAAAAAAAAI/AAAAAAAAAAA/naAGSBohkNA/s44-p-k-no-ns-nd/photo.jpg"
],
"photo_count": 1,
"thumbnail": "https://lh4.googleusercontent.com/-K49zThvFiYI/AAAAAAAAAAI/AAAAAAAAAAA/naAGSBohkNA/s44-p-k-no-ns-nd/photo.jpg",
"maps_url": "https://www.google.com/maps?cid=4415530143815304736"
},
{
"fid": "0x89c25973ef719d33:0xc82344355d573f5d",
"place_id": "0x89c25973ef719d33:0xc82344355d573f5d",
"cid": "14421445427760414557",
"entity_id": "/g/11ksnxczx9",
"name": "Tiny Dancer Coffee",
"rating": 4.9,
"review_count": null,
"category_primary": "Coffee shop",
"categories": [
"Coffee shop",
"Cafe",
"Caterer",
"Espresso bar",
"Event venue",
"Patisserie"
],
"address": "IN THE SUBWAY AT, 210 W 50th St Concourse Store #2, New York, NY 10019",
"locality": "210 W 50th St Concourse Store #2",
"latitude": 40.7614519,
"longitude": -73.98452309999999,
"website": "https://tinydancercoffee.com/",
"domain": "tinydancercoffee.com",
"phone": null,
"phone_display": null,
"hours_today": [
"7 AM-6 PM"
],
"photos": [
"https://lh3.googleusercontent.com/--jgPqC_GscM/AAAAAAAAAAI/AAAAAAAAAAA/S0hpnOtkPoc/s44-p-k-no-ns-nd/photo.jpg"
],
"photo_count": 1,
"thumbnail": "https://lh3.googleusercontent.com/--jgPqC_GscM/AAAAAAAAAAI/AAAAAAAAAAA/S0hpnOtkPoc/s44-p-k-no-ns-nd/photo.jpg",
"maps_url": "https://www.google.com/maps?cid=14421445427760414557"
},
{
"fid": "0x89c2585398cb1ecd:0x1c444f8aa8477495",
"place_id": "0x89c2585398cb1ecd:0x1c444f8aa8477495",
"cid": "2036840388425643157",
"entity_id": "/g/11c2091lqr",
"name": "St Kilda Coffee",
"rating": 4.6,
"review_count": null,
"category_primary": "Coffee shop",
"categories": [
"Coffee shop"
],
"address": "328 W 44th St, New York, NY 10036",
"locality": "New York, NY 10036",
"latitude": 40.7590143,
"longitude": -73.9902129,
"website": "http://stkildacoffee.com/",
"domain": "stkildacoffee.com",
"phone": "[redacted-contact]",
"phone_display": "[redacted-contact]",
"hours_today": [
"7 AM-8 PM"
],
"photos": [
"https://lh6.googleusercontent.com/-VJsvomc8IVs/AAAAAAAAAAI/AAAAAAAAAAA/60NRw6saX6E/s44-p-k-no-ns-nd/photo.jpg"
],
"photo_count": 1,
"thumbnail": "https://lh6.googleusercontent.com/-VJsvomc8IVs/AAAAAAAAAAI/AAAAAAAAAAA/60NRw6saX6E/s44-p-k-no-ns-nd/photo.jpg",
"maps_url": "https://www.google.com/maps?cid=2036840388425643157"
},
{
"fid": "0x89c2597044654781:0x222250f7055f8b6c",
"place_id": "0x89c2597044654781:0x222250f7055f8b6c",
"cid": "2459617368375004012",
"entity_id": "/g/11tc0xxt_2",
"name": "Frisson Espresso 44",
"rating": 4.8,
"review_count": null,
"category_primary": "Coffee shop",
"categories": [
"Coffee shop"
],
"address": "405 W 44th St, New York, NY 10036",
"locality": "New York, NY 10036",
"latitude": 40.7599559,
"longitude": -73.9917816,
"website": "http://frissonespresso.co/",
"domain": "frissonespresso.co",
"phone": "[redacted-contact]",
"phone_display": "[redacted-contact]",
"hours_today": [
"7 AM-6 PM"
],
"photos": [
"https://lh6.googleusercontent.com/-QsBr-gH7B8I/AAAAAAAAAAI/AAAAAAAAAAA/Rhijx5_5lr0/s44-p-k-no-ns-nd/photo.jpg"
],
"photo_count": 1,
"thumbnail": "https://lh6.googleusercontent.com/-QsBr-gH7B8I/AAAAAAAAAAI/AAAAAAAAAAA/Rhijx5_5lr0/s44-p-k-no-ns-nd/photo.jpg",
"maps_url": "https://www.google.com/maps?cid=2459617368375004012"
}
],
"count": 10
}
}Why this is hard manually
Local data has no natural primary key. The same restaurant appears with a different name spelling in your CRM, a different address format in your billing system and a different phone format everywhere else. So the first thing any serious local pipeline needs is a stable id, and Google exposes several that look interchangeable and are not.
The second thing that catches people is that a place record is not one record. Google's search surface and Google's business panel carry different field sets, and a field being absent in one does not mean the business lacks it. Build a dedupe key from search-only fields and you will merge two different coffee shops or split one into two.
The third is enrichment cost. Email addresses and social profiles are not on Google at all - they live on the business's own website, which means somebody has to go and read it. That step succeeds or fails per business, and a pipeline that does not track which is which will report a false negative as a fact.
Why ReefAPI solves it
Every place comes back with fid, place_id, cid and entity_id, and the relationship between them is worth knowing. fid is a pair of hex values ('0x89c2598f7ff4aa09:0x313547e757cb8cea'), place_id is currently the same string, and cid is the decimal form of the second half of fid - we checked the arithmetic: 0x313547e757cb8cea equals 3545819340560108778, which is exactly the cid returned for Katz's Delicatessen. entity_id is different in kind: it is a Knowledge Graph mid ('/m/03tx_h' for Katz's, '/g/11hbtg2w_k' for a small coffee roaster), and only well-known entities get an /m/ one. Store fid as your key, keep cid because it is what builds a maps.google.com/?cid= URL, and treat entity_id as a bonus.
review_count is null in place/search and populated in place/detail. This is not intermittent - it was null on all five results of our coffee search while every one of them returned a rating (4.6, 4.0, 4.9, 4.5, 4.9), and place/detail on Katz's returned rating 4.5 with review_count 93,499. A rating with no review count is a rating you cannot weight, so if review volume matters to your scoring, budget a detail call per place rather than assuming search will carry it.
include_contacts is a real enrichment pass and it reports its own hit rate. On our five-result search it set contacts_enriched 2 against contacts_attempted 5. The two that resolved returned an email plus three social profiles each (facebook, instagram, twitter, as network/url pairs); the other three returned nothing at all. That is not a failure - most small businesses do not publish an address on their site - but meta.contacts_enriched is the number to log, because it is the difference between 'this business has no email' and 'we did not find one'.
place/reviews returns both date forms so you never have to parse a label: relative_date '6 days ago' alongside date '2026-08-19T23:08:23Z'. Each review carries review_id, author_name, author_photo, author_profile_url, rating, text, language and an array of full-resolution photo URLs, and meta.has_more tells you whether a cursor will get you more. Reviews can be requested by query, fid, cid or place_id, so once you have resolved a place you never have to search for it again.
The category fields are two, not one: category_primary is the single label Google shows ('Deli'), categories is the full list ('Deli', 'American restaurant', 'Jewish restaurant', 'Restaurant', 'Sandwich shop'). Filtering on category_primary alone will miss businesses that Google files under a different head category than you expect.
Nine actions share the engine: place/search, place/detail, place/by-id, place/nearby, place/reviews, place/photos, place/freshness and geocode. place/nearby takes lat, lng, type and radius rather than a text query, and place/freshness diffs a place against a previous snapshot you pass in, which is the cheap way to watch for a closure or a phone-number change. Search answered in about 5.1 seconds with contact enrichment on, detail in 4.2, reviews in 2.8.
Questions developers ask
Is place_id the same as Google's official Places API place ID?
No. Google's Places API issues ChIJ-prefixed ids. What this engine returns is the maps feature id (fid), a hex pair, with place_id currently mirroring it. If you need to join against Google Places API data, match on coordinates and name instead.
How are fid and cid related?
cid is the decimal value of the second hex component of fid. We verified it: 0x313547e757cb8cea equals 3545819340560108778, the cid returned for Katz's Delicatessen. cid is the one that builds a google.com/maps?cid= link.
Why is review_count null in my search results?
Because Google's search surface does not carry it. It was null on all five of our results while every row had a rating. Call place/detail on the fid to get review_count - Katz's returned 93,499 there.
Does include_contacts find an email for every business?
No. It resolved 2 of 5 in our test. Emails and social profiles come from the business's own website, so a business with no contact page returns nothing. Read meta.contacts_enriched and meta.contacts_attempted before concluding a business has no email.
Can I get reviews without searching first?
Yes. place/reviews accepts fid, cid or place_id directly, which is faster and removes the risk that the search resolves to a different branch than the one you meant.
What is entity_id for?
It is a Google Knowledge Graph mid. Famous places get an /m/ id ('/m/03tx_h'), newer or smaller ones get a /g/ id, and it is the identifier that joins Maps data to other Google surfaces. It is not a substitute for fid as a key.
How do I watch a business for changes?
place/freshness takes a query plus a previous snapshot and returns what moved. It is cheaper than re-pulling and diffing full detail records, and it is the right endpoint for closure and phone-change monitoring.