# Google Maps API — place search, business details, public reviews, nearby search, geocoding and change monitoring: name, address, phone, website, rating, review count, categories, photos and coordinates from Google Maps (geo-biased, logged-out, no API key or quota)

> 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.
> ReefAPI engine `google-maps` · 8 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/google-maps/v1/<action>` with a JSON body.
- **Auth:** header `x-api-key: <YOUR_REEFAPI_KEY>` — create one free (1,000 credits, no card): https://reefapi.com/signup
- **Response (every call):** `{ ok: boolean, data: ..., meta: { record_count, credits, ... }, error: { code, message } }` — branch on `ok`. Failed or blocked calls are free.
- **One key + one shared credit pool** across every ReefAPI API. Per-call credits are listed on each endpoint below.
- **Use it from an AI agent (MCP):** connect `https://api.reefapi.com/mcp` (remote streamable-http, `Authorization: Bearer <key>`) and your assistant can call these actions directly.

## Endpoints

### POST /google-maps/v1/place/search — 2 credits
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.

**Parameters:**
- `query` (string, required) — What to look for — business name, type or free text, ideally with a place hint ('pizza Brooklyn', 'Katz's Delicatessen Manhattan').
- `lat` (number, optional) — Latitude to bias the search around. Strongly recommended — without it Google assumes the central US.
- `lng` (number, optional) — Longitude to bias the search around (pair with lat).
- `maxResults` (integer, optional, default 20) — How many places to return (1–200). The engine pages Google's 20-per-page results internally — no page/cursor needed.
- `lang` (string, optional, default "en") — Result language (Google hl code: en, de, tr, es…). Affects category names and localized fields.
- `region` (string, optional, default "us") — Region bias (Google gl country code: us, de, tr…).
- `altitude` (integer, optional, default 15000) — Advanced: viewport altitude in meters — smaller = tighter local results, larger = wider area.
- `include_contacts` (boolean, optional, default false) — Enrich each result that has a website with contact details scraped from that site: business email(s), extra phone numbers, and social profile links (LinkedIn, Instagram, Facebook, Twitter/X, YouTube, TikTok). Adds email, emails, contact_phones and socials to each place. Off by default; turning it on fetches every result's website (through the proxy) so the response is slower — best used for lead generation. Sites that fail/block are returned without contacts.

**Returns:** places[]{fid, place_id, cid, entity_id, name, rating, review_count, category_primary, categories, address, locality, latitude, longitude, website, domain, phone, phone_display, hours_today, photos, photo_count, thumbnail, maps_url} (+ email, emails, contact_phones, socials when include_contacts=true)

**Example request body:**
```json
{
  "query": "specialty coffee Times Square",
  "lat": 40.7589,
  "lng": -73.9881,
  "maxResults": 10
}
```

### POST /google-maps/v1/place/detail — 3 credits
The single richest matching place: name, address, phone, website, rating, total review count, categories, coordinates, opening hours and photos.

**Parameters:**
- `query` (string, required) — The business to look up — name plus a location hint gives the best match.
- `lat` (number, optional) — Latitude to bias the search around. Strongly recommended — without it Google assumes the central US.
- `lng` (number, optional) — Longitude to bias the search around (pair with lat).
- `lang` (string, optional, default "en") — Result language (Google hl code: en, de, tr, es…). Affects category names and localized fields.
- `region` (string, optional, default "us") — Region bias (Google gl country code: us, de, tr…).
- `include_contacts` (boolean, optional, default false) — Enrich each result that has a website with contact details scraped from that site: business email(s), extra phone numbers, and social profile links (LinkedIn, Instagram, Facebook, Twitter/X, YouTube, TikTok). Adds email, emails, contact_phones and socials to each place. Off by default; turning it on fetches every result's website (through the proxy) so the response is slower — best used for lead generation. Sites that fail/block are returned without contacts.

**Returns:** place{fid, place_id, cid, entity_id, name, rating, review_count, category_primary, categories, address, locality, latitude, longitude, website, domain, phone, phone_display, hours_today, photos, photo_count, thumbnail, maps_url} (+ email, emails, contact_phones, socials when include_contacts=true)

**Example request body:**
```json
{
  "query": "Katz's Delicatessen Manhattan",
  "lat": 40.7223,
  "lng": -73.9874
}
```

### POST /google-maps/v1/place/by-id — 3 credits
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.

**Parameters:**
- `fid` (string, optional) — Google feature id (ftid '0x…:0x…'). Pass this OR cid OR place_id.
- `place_id` (string, optional) — Alias of fid (same 0x…:0x… value).
- `cid` (string, optional) — Numeric Google customer id (cid). Pass this OR fid.
- `query` (string, optional) — Optional text fallback if no id is supplied.
- `lat` (number, optional) — Latitude to bias the search around. Strongly recommended — without it Google assumes the central US.
- `lng` (number, optional) — Longitude to bias the search around (pair with lat).
- `lang` (string, optional, default "en") — Result language (Google hl code: en, de, tr, es…). Affects category names and localized fields.
- `region` (string, optional, default "us") — Region bias (Google gl country code: us, de, tr…).

**Returns:** place{fid, place_id, cid, entity_id, name, rating, review_count, category_primary, categories, address, locality, latitude, longitude, website, domain, phone, phone_display, hours_today, photos, photo_count, thumbnail, maps_url}

### POST /google-maps/v1/place/nearby — 2 credits
Find places of a given type near coordinates (e.g. coffee shops, pharmacies, ATMs around a lat/lng). Returns up to 200 nearby places.

**Parameters:**
- `type` (string, required) — The kind of place to find nearby — a category or keyword ('coffee shop', 'pharmacy', 'ATM', 'sushi restaurant').
- `lat` (number, required) — Latitude of the center point.
- `lng` (number, required) — Longitude of the center point.
- `radius` (integer, optional, default 2000) — Approximate search radius in meters (wider = more area, less local precision). Default ~2 km.
- `maxResults` (integer, optional, default 20) — How many places to return (1–200).
- `lang` (string, optional, default "en") — Result language (Google hl code: en, de, tr, es…). Affects category names and localized fields.
- `region` (string, optional, default "us") — Region bias (Google gl country code: us, de, tr…).

**Returns:** places[]{fid, place_id, cid, entity_id, name, rating, review_count, category_primary, categories, address, locality, latitude, longitude, website, domain, phone, phone_display, hours_today, photos, photo_count, thumbnail, maps_url}

**Example request body:**
```json
{
  "type": "coffee shop",
  "lat": 40.7589,
  "lng": -73.9851,
  "maxResults": 10
}
```

### POST /google-maps/v1/geocode — 1 credit
Turn an address or place name into coordinates: returns latitude, longitude and the formatted address of the best match.

**Parameters:**
- `address` (string, required) — The address or place name to geocode.
- `lang` (string, optional, default "en") — Result language (Google hl code: en, de, tr, es…). Affects category names and localized fields.
- `region` (string, optional, default "us") — Region bias (Google gl country code: us, de, tr…).

**Returns:** {query, latitude, longitude, formatted_address, locality, name, fid, place_id, maps_url}

**Example request body:**
```json
{
  "address": "350 5th Ave, New York, NY 10118"
}
```

### POST /google-maps/v1/place/reviews — 1 credit
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.

**Parameters:**
- `query` (string, optional) — The business whose reviews you want (name + location). Pass this OR an id (fid/cid/place_id).
- `fid` (string, optional) — Google feature id from place/search — skips re-resolving.
- `cid` (string, optional) — Numeric Google cid (alternative to fid).
- `place_id` (string, optional) — Alias of fid.
- `sort` (enum, optional, default "most_relevant") — Review ordering. 'newest' for the latest reviews, 'highest_rating'/'lowest_rating' to surface best/worst. [one of: most_relevant, newest, highest_rating, lowest_rating]
- `max_reviews` (integer, optional, default 20) — How many reviews to return. The engine paginates Google's 20-per-page reviews automatically up to this many.
- `cursor` (string, optional) — Continue from a previous response's pagination.cursor to fetch the next batch (omit for the first page).
- `lat` (number, optional) — Latitude to bias the search around. Strongly recommended — without it Google assumes the central US.
- `lng` (number, optional) — Longitude to bias the search around (pair with lat).
- `lang` (string, optional, default "en") — Result language (Google hl code: en, de, tr, es…). Affects category names and localized fields.
- `region` (string, optional, default "us") — Region bias (Google gl country code: us, de, tr…).

**Returns:** {place{fid,place_id,cid,name,rating,review_count,address,maps_url}, reviews[]{review_id, author_name, author_photo, author_profile_url, rating, text, language, relative_date, date, photos, photo_count, owner_response{text,relative_date}}, count, pagination{cursor, has_more}, aggregate{rating, total}}

**Example request body:**
```json
{
  "query": "Katz's Delicatessen Manhattan",
  "lat": 40.7223,
  "lng": -73.9874,
  "max_reviews": 20
}
```

### POST /google-maps/v1/place/photos — 2 credits
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.

**Parameters:**
- `query` (string, optional) — The business whose photos you want (or pass an id).
- `fid` (string, optional) — Google feature id from place/search.
- `cid` (string, optional) — Numeric Google cid (alternative to fid).
- `place_id` (string, optional) — Alias of fid.
- `lat` (number, optional) — Latitude to bias the search around. Strongly recommended — without it Google assumes the central US.
- `lng` (number, optional) — Longitude to bias the search around (pair with lat).
- `lang` (string, optional, default "en") — Result language (Google hl code: en, de, tr, es…). Affects category names and localized fields.
- `region` (string, optional, default "us") — Region bias (Google gl country code: us, de, tr…).

**Returns:** {place{fid,place_id,cid,name,maps_url}, photos[] (image CDN URLs), count}

### POST /google-maps/v1/place/freshness — 2 credits
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).

**Parameters:**
- `query` (string, required) — The business to monitor (same query each run).
- `lat` (number, optional) — Latitude to bias the search around. Strongly recommended — without it Google assumes the central US.
- `lng` (number, optional) — Longitude to bias the search around (pair with lat).
- `previous` (object, optional) — The `place` object from your previous freshness call. Omit on the first run (returns first_seen: true); pass it on later runs to get the change diff.
- `lang` (string, optional, default "en") — Result language (Google hl code: en, de, tr, es…). Affects category names and localized fields.
- `region` (string, optional, default "us") — Region bias (Google gl country code: us, de, tr…).

**Returns:** place{...} + freshness{first_seen, changed, snapshot_hash, prev_snapshot_hash, changes{field: {old, new}}}

**Example request body:**
```json
{
  "query": "Katz's Delicatessen Manhattan",
  "lat": 40.7223,
  "lng": -73.9874
}
```

## More
- Try it live, no code: https://reefapi.com/playground?engine=google-maps
- Human docs page: https://reefapi.com/docs/google-maps
- Every ReefAPI API in one file (for your AI): https://reefapi.com/llms-full.txt