Google Maps API & Scraper
The Google Maps API returns place, business and review data as clean JSON.
🤖 Using an AI assistant? Copy this link into ChatGPT / Claude / Cursor — it reads every endpoint and parameter instantly and tells you if this API fits your use case.
The primary place/search endpoint returns places with name, rating, review count, category, address, locality and coordinates, and you can pull a place/detail, look up a place by id, find nearby places, geocode an address, and read place/reviews and place/photos. It is the managed alternative to the official Places API and to scraping Maps — for local-data products, lead generation and review monitoring, with no per-request Google billing to manage. One ReefAPI key, one shared credit pool, the standard envelope.
Google Maps place ids: fid, place_id, cid and entity_id
Google hands the same business four different identifiers and they are not interchangeable. This API returns all four on every place, and only some of them can be sent back as a lookup key. Each row was measured on 2026-08-27 against Katz's Delicatessen in Manhattan and cross-checked on four Times Square coffee shops.
| Identifier | Measured value | Can you look a place up with it? |
|---|---|---|
| fid | 0x89c2598f7ff4aa09:0x313547e757cb8cea | Yes. This is the working key for place/by-id, place/reviews and place/photos. |
| place_id | 0x89c2598f7ff4aa09:0x313547e757cb8cea | Yes, because it is the same string as fid. It is not Google's Places API id. |
| a ChIJ... id | ChIJCarr_49ZwokRyozLV-dHNTE | No. Sent as place_id it came back with error code MISSING_PARAM. |
| cid | 3545819340560108778 | No. On its own it returned NOT_FOUND, "no place matched". It is returned, and maps_url is built from it. |
| entity_id | /m/03tx_h | No. A Google Knowledge Graph id, returned for reference only. |
| maps_url | https://www.google.com/maps?cid=3545819340560108778 | The shareable link, always keyed on cid. |
| rating | 4.5 | Out of 5, one decimal, on the place. Individual reviews carry an integer from 1 to 5. |
| review_count | 93499 | An integer on place/detail. It can come back null on place/search, see below. |
| hours_today | ["8 AM-11 PM"], ["Open 24 hours"] | Today only, as an array of strings. A full week of opening hours is not returned. |
| latitude / longitude | 40.722232999999996 / -73.98742899999999 | Floats at full precision. |
| review_id | Ci9DQUlRQUNvZENodHljRjlvT21OUWVETTVUekpoZEdOVU0yRnNiRmR3VG5GR1drRRAB | Base64, from place/reviews. Reviews also carry date (2026-08-19T23:08:23Z) and relative_date ("6 days ago"). |
cid is the decimal form of the hexadecimal half of fid that follows the colon: 0x313547e757cb8cea is 3545819340560108778, and the same conversion held on all four coffee shops checked. entity_id follows Google's own split, where long-established entities get an /m/... Freebase-style id (Katz's is /m/03tx_h) and everything else gets a machine-generated /g/11... id (787 coffee is /g/11y31_2b88). There is no business_status or plus_code field in this response.
Real request and response JSON
Captured from the indexed primary action, place/search, on .
{
"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": 920.5,
"record_count": 10,
"bytes": 123340,
"cache_hit": false,
"completeness_pct": 99,
"query": "specialty coffee Times Square"
},
"data": {
"places": [
{
"fid": "0x89c2585580e483ab:0xe[redacted-phone]b3d7a8",
"place_id": "0x89c2585580e483ab:0xe[redacted-phone]b3d7a8",
"cid": "[redacted-phone]",
"entity_id": "/g/11c1xjnyxs",
"name": "[redacted-name]",
"rating": 4,
"review_count": 555,
"category_primary": "Coffee shop",
"categories": [
"Coffee shop",
"Cafe",
"Coffee store"
],
"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-phone]",
"phone_display": "[redacted-phone]",
"hours_today": [
"8 AM-4 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=[redacted-phone]"
},
{
"fid": "0x89c259b6c59db77d:0x57cf5d10e4d1b9a5",
"place_id": "0x89c259b6c59db77d:0x57cf5d10e4d1b9a5",
"cid": "[redacted-phone]",
"entity_id": "/g/11y31_2b88",
"name": "[redacted-name]",
"rating": 4.9,
"review_count": 3427,
"category_primary": "Coffee shop",
"categories": [
"Coffee shop"
],
"address": "245 W 46th St, New York, NY 10036",
"locality": "New York, NY 10036",
"latitude": 40.759709099999995,
"longitude": -73.9873617,
"website": "https://www.787coffee.com/",
"domain": "787coffee.com",
"phone": "[redacted-phone]",
"phone_display": "[redacted-phone]",
"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=[redacted-phone]"
},
{
"fid": "0x89c25903f53cf951:0xc2c7e3abcb39348f",
"place_id": "0x89c25903f53cf951:0xc2c7e3abcb39348f",
"cid": "[redacted-phone]",
"entity_id": "/g/11m7mgfqyx",
"name": "[redacted-name]",
"rating": 4.5,
"review_count": 314,
"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-phone]",
"phone_display": "[redacted-phone]",
"hours_today": [
"8 AM-4 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=[redacted-phone]"
}
],
"count": 10
}
}What the Google Maps API does
| Action | Description | Concrete use case | Key params |
|---|---|---|---|
| place/search | Search places by text query with optional lat/lng geo-bias. Returns up to 200 places with name, address, rating, categories, phone, website, coordinates, photos. | Support teams call place/search to search places by text query with optional lat/lng geo-bias. | query, lat, lng, altitude, maxResults, ... |
| place/detail | The single richest matching place: name, address, phone, website, rating, total review count, categories, coordinates, opening hours and photos. | Reputation platforms call place/detail to get the single richest matching place. | query, lat, lng, lang, region, ... |
| place/by-id | Fetch a place directly by its Google id — fid (0x…:0x…), place_id or numeric cid — no text query needed. Use the id returned by place/search. | Market researchers call place/by-id to fetch a place directly by its Google id. | fid, place_id, cid, query, lat, ... |
| place/nearby | Find places of a given type near coordinates (e.g. coffee shops, pharmacies, ATMs around a lat/lng). Returns up to 200 nearby places. | B2B review analysts call place/nearby to find places of a given type near coordinates (e.g. | lat, lng, type, radius, maxResults, ... |
| geocode | Turn an address or place name into coordinates: returns latitude, longitude and the formatted address of the best match. | Support teams call geocode to turn an address or place name into coordinates. | address, lang, region |
| place/reviews | Public Google reviews for a place — paginated to ALL reviews. Each review carries author name, rating, text, date, photos and the owner's response. Resolve a place by query, or pass its fid/cid/place_id from place/search. | Reputation platforms call place/reviews to get public Google reviews for a place. | query, fid, cid, place_id, sort, ... |
| place/photos | Public photos for a place — the featured/hero gallery plus user-uploaded photos attached to reviews. Each is a stable image CDN URL (append '=s800' etc. for a sized variant). Resolve by query or pass an id. | Market researchers call place/photos to get public photos for a place. | query, fid, cid, place_id, lat, ... |
| place/freshness | Monitor a place for changes: returns the current place plus a typed diff vs the snapshot you pass from a previous call (rating/review_count/phone/website/address changes). | B2B review analysts call place/freshness to monitor a place for changes. | query, lat, lng, previous, lang, ... |
Call place/search from your stack
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}.Who uses this API and why
- Lead-generation tools call place/search to build lists of businesses by category and location.
- Reputation products use place/reviews to monitor a business's Google ratings and review text.
- Local-data apps use place/detail and geocode to enrich a location with hours, contact and coordinates.
Questions developers ask before integrating
What is the difference between place_id, fid and cid on Google Maps?
fid is Google's feature id, two hexadecimal halves joined by a colon, for example 0x89c2598f7ff4aa09:0x313547e757cb8cea. In this API place_id holds exactly the same string, so it is an alias for fid and not the ChIJ... id from Google's Places API. cid is a single decimal number, 3545819340560108778, and it is what maps.google.com/?cid= links use. All three are returned on every place, but only fid, or place_id carrying the fid, works as a lookup key.
Can I look up a place with just the cid?
No. Measured on 2026-08-27, place/by-id with only cid 3545819340560108778 returned ok:false with error.code NOT_FOUND and the message "no place matched", while the same place resolved in under a second from its fid. Treat cid as an output you store for building share links, and keep the fid alongside it if you plan to refresh the record later.
Does this accept a ChIJ... place_id from the Google Places API?
No. Passing ChIJCarr_49ZwokRyozLV-dHNTE as place_id returned ok:false with error.code MISSING_PARAM, because the parameter is documented as an alias of fid and a ChIJ string is not a fid. If a ChIJ id is all you hold, look the business up again by name and coordinates with place/search or place/detail and store the fid that comes back.
How do I derive cid from fid myself?
Take the part of fid after the colon, drop the 0x, and read it as a hexadecimal integer. 0x313547e757cb8cea becomes 3545819340560108778. That held for all five places checked on 2026-08-27, including 0x57cf5d10e4d1b9a5 giving 6327378328618645925 and 0x2be347662f0035e giving 197653116721562462. The conversion is lossless in that direction, but you cannot recover the first half of the fid from a cid, which is why cid alone is not a lookup key.
Why does review_count sometimes come back null?
place/search is served from more than one Google result surface and only one of them publishes the count. The identical request for "specialty coffee Times Square" was run three times in a row on 2026-08-27: two runs returned review_count null for all four places while rating was populated on every row, and one run returned 3526, 958, 559 and 2835. Until that is evened out, treat a null review_count from place/search as unknown rather than zero, and read counts from place/detail or place/by-id, which returned 93,499 for Katz's on every attempt.
What comes back for a permanently closed business?
There is no business_status field, so closure shows up as absence. Barneys New York on Madison Avenue, closed for years, came back from place/search with name, address and rating 4.2, and with review_count, hours_today, website and phone all null. Times Square Toys R Us returned a name and a partial address and nothing else. If you are monitoring closures, watch for hours_today and phone dropping to null on a record that previously had them.
What opening hours do I get?
Only today's, as hours_today, an array of strings. Measured values are ["8 AM-11 PM"], ["7 AM-7:30 PM"] and ["Open 24 hours"] for round-the-clock pharmacies. The array shape allows split shifts, for example separate lunch and dinner service on one day. A seven-day schedule is not part of this response, so if you need a full week you have to poll once a day and build it up.
How does place/freshness work, and what is snapshot_hash?
It returns the current place block plus a freshness object. On 2026-08-27 that was first_seen true, changed false, snapshot_hash "0e71d7ba7e625683" and an empty changes object. The hash is a 16-character digest of the place record, so you can store it and compare it yourself on the next run to detect a change. Two things measured the same day are worth knowing: passing that hash back in the previous parameter returned ok:false with error.code PARSE_ERROR, so the built-in comparison path is not usable yet, and the place block from freshness came back with review_count null while place/detail reported 93,499 for the same fid.
What is the Google Maps API?
Google Maps API is a ReefAPI endpoint group for places, business details, ratings and reviews. It returns live JSON through POST requests under /google-maps/v1.
Is the Google Maps API free to try?
Yes. ReefAPI starts with 1,000 free credits, no card required. Google Maps calls use the same shared credit balance as every other ReefAPI engine.
Do I need a Google Maps login or account?
No login to Google Maps is needed for the API response. You call ReefAPI with your x-api-key header, and the playground can run live examples before you create a production key.
How fresh is the Google Maps data?
The page example is captured from a live place/search call, and production requests fetch live data through ReefAPI rather than a static sample.
How many credits does the Google Maps API use?
Google Maps actions currently cost 1-3 credits per successful call. Failed or blocked calls are free, and all APIs draw from one credit pool.
Can I call Google Maps from an AI assistant or MCP client?
Yes. Connect ReefAPI once through MCP and your assistant can call google-maps actions with the same key, credit pool and JSON envelope used by normal REST requests.