# Google Maps API for agents

> API for Agents · https://apiforagents.dev/platforms/google_maps · HTML twin: https://apiforagents.dev/platforms/google_maps

Places, search and reviews from Google Maps.

Endpoint: `POST https://apiforagents.dev/v1/google_maps`. One op per call. Quote first with `"estimateOnly": true`.

## Prices (USD per record, pay as you go)

| Record | Per record |
|---|---|
| reviews | $0.000225 |
| places | $0.0036 |

## Operations

### places

Full cards for up to ten places by Maps URL (place id or cid). Rating and breakdown, review keywords, contact, address, hours, popular times, attributes, socials, owner posts.

| Field | Required | Type | Meaning |
|---|---|---|---|
| subjects | yes | list of string (1-10 items) | Maps URLs carrying a place id or cid, or bare ChIJ… place ids. |

Response fields (each row of data; every field present, null when the source had nothing):

| Field | Type |
|---|---|
| placeId | string |
| placeUrl | string |
| businessName | string |
| category | string |
| allCategories | list of string |
| categoryId | string |
| placeTags | list of string |
| rating | number |
| reviews | integer |
| reviewBreakdown | any |
| reviewKeywords | any |
| reviewsUrl | string |
| priceRange | string |
| phone | string |
| formattedPhone | string |
| website | string |
| emails | list of string |
| additionalPhones | list of string |
| socials | any |
| directoryProfiles | any |
| address | string |
| neighborhood | string |
| city | string |
| state | string |
| postalCode | string |
| country | string |
| street | string |
| latitude | number |
| longitude | number |
| plusCode | string |
| locatedIn | string |
| floor | string |
| permanentlyClosed | boolean |
| temporarilyClosed | boolean |
| unclaimed | boolean |
| owner | any |
| description | string |
| attributes | any |
| openingHours | any |
| specialHours | any |
| popularTimes | any |
| liveOccupancyPercent | integer |
| liveStatus | string |
| coverPhoto | string |
| photos | any |
| photoCount | integer |
| relatedPlaces | any |
| ownerPosts | any |
| menuUrl | string |
| reserveTableUrl | string |
| reservationLinks | any |
| entranceLocation | any |
| hotelAds | any |
| similarHotels | any |
| hotelType | string |
| hotelDescription | string |
| subTitle | string |
| cid | string |
| fid | string |
| kgmid | string |
| isAdvertisement | boolean |
| language | string |
| details | object |

`details` is always the last field: everything else the source sent for that row, under our own field names. Its keys depend on the source that answered, so read them defensively; it is `{}` when there is nothing more.

Example request:

```bash
curl -X POST https://apiforagents.dev/v1/google_maps \
  -H "Authorization: Bearer $AFA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"op":"places","subjects":["ChIJN1t_tDeuEmsRUsoyG83frY4"]}'
```

Example response rows (made-up names, real field names; a live row carries every field above):

```json
[
  {
    "businessName": "Brewlab Coffee",
    "category": "Coffee shop",
    "address": "210 Congress Ave, Austin, TX 78701",
    "city": "Austin",
    "country": "US",
    "rating": 4.7,
    "reviews": 1284,
    "priceRange": "$$",
    "phone": "+1 512-555-0142",
    "website": "https://brewlab.example",
    "permanentlyClosed": false,
    "placeId": "2910649290",
    "placeUrl": "https://www.google.com/maps/brewlab-coffee-1000",
    "categoryId": "3644697838",
    "reviewsUrl": "https://www.google.com/maps/brewlab-coffee-1000",
    "menuUrl": "https://www.google.com/maps/brewlab-coffee-1000",
    "reserveTableUrl": "https://www.google.com/maps/brewlab-coffee-1000",
    "cid": "777429974",
    "fid": "615548140",
    "kgmid": "751321537",
    "isAdvertisement": false,
    "details": {}
  },
  {
    "businessName": "Casa Lumen Tacos",
    "category": "Mexican restaurant",
    "address": "88 Harbor Dr, San Diego, CA 92101",
    "city": "San Diego",
    "country": "US",
    "rating": 4.5,
    "reviews": 2310,
    "priceRange": "$",
    "phone": "+1 619-555-0190",
    "website": "https://casalumen.example",
    "permanentlyClosed": false,
    "placeId": "2171364855",
    "placeUrl": "https://www.google.com/maps/casa-lumen-tacos-1001",
    "categoryId": "1221544499",
    "reviewsUrl": "https://www.google.com/maps/casa-lumen-tacos-1001",
    "menuUrl": "https://www.google.com/maps/casa-lumen-tacos-1001",
    "reserveTableUrl": "https://www.google.com/maps/casa-lumen-tacos-1001",
    "cid": "2979685572",
    "fid": "67051873",
    "kgmid": "3876769627",
    "isAdvertisement": false,
    "details": {}
  }
]
```

Try it in the playground: https://apiforagents.dev/dashboard/run?platform=google_maps&op=places (sign in first).

### search

Places for a keyword in a location. Every hit a full card.

| Field | Required | Type | Meaning |
|---|---|---|---|
| query | yes | string (≤300 chars) |  |
| location | yes | string (≤120 chars) |  |
| minRating | no | enum | Google's star scale, in halves. Values: 2, 2.5, 3, 3.5, 4, 4.5. |
| website | no | enum | Keep only places that list a website ("with"), only those that do not ("without". A common lead filter), or both. Values: any, with, without. |
| limit | no | integer (1-100) |  |

Response fields (each row of data; every field present, null when the source had nothing):

| Field | Type |
|---|---|
| placeId | string |
| placeUrl | string |
| businessName | string |
| category | string |
| allCategories | list of string |
| categoryId | string |
| placeTags | list of string |
| rating | number |
| reviews | integer |
| reviewBreakdown | any |
| reviewKeywords | any |
| reviewsUrl | string |
| priceRange | string |
| phone | string |
| formattedPhone | string |
| website | string |
| emails | list of string |
| additionalPhones | list of string |
| socials | any |
| directoryProfiles | any |
| address | string |
| neighborhood | string |
| city | string |
| state | string |
| postalCode | string |
| country | string |
| street | string |
| latitude | number |
| longitude | number |
| plusCode | string |
| locatedIn | string |
| floor | string |
| permanentlyClosed | boolean |
| temporarilyClosed | boolean |
| unclaimed | boolean |
| owner | any |
| description | string |
| attributes | any |
| openingHours | any |
| specialHours | any |
| popularTimes | any |
| liveOccupancyPercent | integer |
| liveStatus | string |
| coverPhoto | string |
| photos | any |
| photoCount | integer |
| relatedPlaces | any |
| ownerPosts | any |
| menuUrl | string |
| reserveTableUrl | string |
| reservationLinks | any |
| entranceLocation | any |
| hotelAds | any |
| similarHotels | any |
| hotelType | string |
| hotelDescription | string |
| subTitle | string |
| cid | string |
| fid | string |
| kgmid | string |
| isAdvertisement | boolean |
| language | string |
| details | object |

`details` is always the last field: everything else the source sent for that row, under our own field names. Its keys depend on the source that answered, so read them defensively; it is `{}` when there is nothing more.

Example request:

```bash
curl -X POST https://apiforagents.dev/v1/google_maps \
  -H "Authorization: Bearer $AFA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"op":"search","query":"coffee shop","location":"Seattle, WA","minRating":"4.5","limit":20}'
```

Example response rows (made-up names, real field names; a live row carries every field above):

```json
[
  {
    "businessName": "Third Wave Roasters",
    "category": "Coffee shop",
    "address": "5 Church St, Bengaluru 560001",
    "city": "Bengaluru",
    "country": "IN",
    "rating": 4.6,
    "reviews": 3120,
    "priceRange": "$$",
    "phone": "+91 80 5555 0188",
    "placeId": "1005667376",
    "placeUrl": "https://www.google.com/maps/third-wave-roasters-1000",
    "categoryId": "1413598742",
    "reviewsUrl": "https://www.google.com/maps/third-wave-roasters-1000",
    "menuUrl": "https://www.google.com/maps/third-wave-roasters-1000",
    "reserveTableUrl": "https://www.google.com/maps/third-wave-roasters-1000",
    "cid": "4033895133",
    "fid": "737493188",
    "kgmid": "3492469626",
    "isAdvertisement": false,
    "details": {}
  },
  {
    "businessName": "Brew & Bloom",
    "category": "Cafe",
    "address": "44 Koramangala 5th Block, Bengaluru 560095",
    "city": "Bengaluru",
    "country": "IN",
    "rating": 4.4,
    "reviews": 1860,
    "priceRange": "$$",
    "phone": "+91 80 5555 0141",
    "placeId": "197953318",
    "placeUrl": "https://www.google.com/maps/brew-bloom-1001",
    "categoryId": "3505513993",
    "reviewsUrl": "https://www.google.com/maps/brew-bloom-1001",
    "menuUrl": "https://www.google.com/maps/brew-bloom-1001",
    "reserveTableUrl": "https://www.google.com/maps/brew-bloom-1001",
    "cid": "156300737",
    "fid": "1569078011",
    "kgmid": "3066591407",
    "isAdvertisement": false,
    "details": {}
  }
]
```

Try it in the playground: https://apiforagents.dev/dashboard/run?platform=google_maps&op=search (sign in first).

### reviews

Reviews for up to ten places. Text, stars, date, reviewer, owner response; sorted newest, most relevant, highest or lowest.

| Field | Required | Type | Meaning |
|---|---|---|---|
| subjects | yes | list of string (1-10 items) | Maps URLs carrying a place id or cid, or bare ChIJ… place ids. |
| sort | no | enum |  Values: newest, relevance, rating_high, rating_low. |
| limit | no | integer (1-100) |  |

Response fields (each row of data; every field present, null when the source had nothing):

| Field | Type |
|---|---|
| reviewId | string |
| reviewUrl | string |
| reviewText | string |
| stars | number |
| postedAt | string |
| reviewer | string |
| reviewerId | string |
| reviewerUrl | string |
| reviewerPhoto | string |
| reviewerTotalReviews | integer |
| localGuide | boolean |
| reviewLikes | integer |
| originalLanguage | string |
| translatedLanguage | string |
| translatedText | string |
| ownerResponse | string |
| ownerResponseDate | string |
| reviewContext | any |
| reviewImageUrls | string |
| details | object |

`details` is always the last field: everything else the source sent for that row, under our own field names. Its keys depend on the source that answered, so read them defensively; it is `{}` when there is nothing more.

Example request:

```bash
curl -X POST https://apiforagents.dev/v1/google_maps \
  -H "Authorization: Bearer $AFA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"op":"reviews","subjects":["ChIJN1t_tDeuEmsRUsoyG83frY4"],"sort":"newest","limit":25}'
```

Example response rows (made-up names, real field names; a live row carries every field above):

```json
[
  {
    "reviewer": "Ravi K.",
    "stars": 5,
    "reviewText": "Great espresso and fast service.",
    "localGuide": true,
    "reviewerTotalReviews": 214,
    "reviewLikes": 12,
    "postedAt": "2026-10-12",
    "ownerResponse": null,
    "reviewId": "3650111347",
    "reviewUrl": "https://www.google.com/maps/ravi-k-1000",
    "reviewerId": "2639496725",
    "reviewerUrl": "https://www.google.com/maps/ravi-k-1000",
    "ownerResponseDate": "2026-10-03",
    "details": {}
  },
  {
    "reviewer": "Lena M.",
    "stars": 4,
    "reviewText": "Good coffee, few seats.",
    "localGuide": false,
    "reviewerTotalReviews": 9,
    "reviewLikes": 3,
    "postedAt": "2026-10-08",
    "ownerResponse": "Thanks Lena, more seats are on the way!",
    "reviewId": "2122062301",
    "reviewUrl": "https://www.google.com/maps/lena-m-1001",
    "reviewerId": "431987686",
    "reviewerUrl": "https://www.google.com/maps/lena-m-1001",
    "ownerResponseDate": "2026-10-08",
    "details": {}
  }
]
```

Try it in the playground: https://apiforagents.dev/dashboard/run?platform=google_maps&op=reviews (sign in first).

### history (free)

Stored rating/review-count series of places already held. Free.

| Field | Required | Type | Meaning |
|---|---|---|---|
| subjects | yes | list of string (1-10 items) |  |
| metric | no | enum |  Values: rating, reviews, live_occupancy_percent. |
| days | no | integer (1-730) |  |

Request shape:

```json
{
  "op": "history",
  "subjects": [
    "example"
  ]
}
```

Try it in the playground: https://apiforagents.dev/dashboard/run?platform=google_maps&op=history (sign in first).

## Notes for the agent

Measured Google Maps data, one operation per call. Places are named by a Google Maps URL carrying a place id or cid, or by a bare ChIJ… place id. Every fetch adds rating, review count and live occupancy to the place's history. ops: places (full cards for up to ten places. Rating and star breakdown, review keywords, price range, phone, website, emails and socials, full address and coordinates, opening and special hours, popular times, attributes, owner posts, menu and reservation links, closed/unclaimed flags), search (a query in a location with minRating and website filters; every hit a full card), reviews (reviews for up to ten places. Text, stars, date, reviewer with local-guide flag, owner response; four sort orders), history (stored rating and review-count series for places already held, free). Ops are independent. Issue several as PARALLEL tool calls. Fresh fetches are charged per record; your own answer is free while fresh.