# Google Maps

> Google Maps Platform services for address validation, geocoding, and location services.

Source: https://cotera.co/docs/reference/tools/individual-tools/google-maps

---

**Authentication Type:** API Key\
**Description:** Google Maps Platform services for address validation, geocoding, and location services.

***

## Authentication

To authenticate, you'll need a Google Maps Platform API key. Create one in the [Google Cloud Console](https://console.cloud.google.com/google/maps-apis/api-list).

**Required APIs:**

* Address Validation API
* Solar API

Make sure both APIs are enabled for your project.

***

## Places

Search for businesses, restaurants, and other places using Google Maps data.

### Search Places

Search for places by query, returning business details including name, address, phone, rating, reviews, and more.

**Operation Type:** Query (Read)

**Parameters:**

* **query** `string` (required): Search query for places (e.g., "restaurants in San Francisco", "dentist near 10001")
* **limit** `number` (nullable): Maximum number of results to return
* **country** `string` (nullable): Country code to restrict results (e.g., "us")
* **lang** `string` (nullable): Language for results (e.g., "en")
* **lat** `number` (nullable): Latitude for location-based search
* **lng** `number` (nullable): Longitude for location-based search
* **offset** `number` (nullable): Pagination offset
* **zoom** `number` (nullable): Zoom level for location precision

**Returns:**

* **status** `string`: Response status
* **data** `array of objects`: Array of places
  * **business\_id** `string` (nullable): Google business ID
  * **name** `string` (nullable): Business name
  * **phone\_number** `string` (nullable): Phone number
  * **full\_address** `string` (nullable): Complete address
  * **latitude** `number` (nullable): Latitude
  * **longitude** `number` (nullable): Longitude
  * **review\_count** `number` (nullable): Total number of reviews
  * **rating** `number` (nullable): Average rating (1-5)
  * **website** `string` (nullable): Business website URL
  * **place\_id** `string` (nullable): Google Place ID
  * **types** `array of strings` (nullable): Place type categories
  * **price\_level** `string` (nullable): Price level indicator
  * **working\_hours** `object` (nullable): Operating hours
  * **city** `string` (nullable): City name
  * **is\_claimed** `boolean` (nullable): Whether the listing is claimed
  * **verified** `boolean` (nullable): Whether the business is verified
  * **description** `string` (nullable): Business description

**Example Usage:**

```json
{
  "query": "coffee shops in downtown Seattle",
  "limit": 20,
  "country": "us"
}
```

***

## Reviews

### Get Place Reviews

Get reviews for a specific place by its business ID or Place ID, including review text, rating, and reviewer information.

**Operation Type:** Query (Read)

**Parameters:**

* **business\_id** `string` (required): Business ID from search results
* **country** `string` (nullable): Country code (e.g., "US", "GB"). Note: currently accepted but ignored — the tool always queries using `country=us`
* **lang** `string` (nullable): Language code for results (e.g., "en", "es")
* **limit** `number` (nullable): Maximum number of reviews to return (capped at 20, the API maximum)
* **cursor** `string` (nullable): Pagination cursor — pass `next_page_token` from a previous response to fetch the next page
* **sort** `string` (nullable): Sort order for reviews (relevance, newest, highest, lowest)
* **place\_id** `string` (nullable): Google Place ID — alternative identifier to `business_id`

**Returns:**

* **status** `string`: Response status
* **data** `array of objects`: Array of review objects
  * **user\_name** `string` (nullable): Reviewer name
  * **user\_avatar** `string` (nullable): Reviewer avatar URL
  * **review\_rate** `number` (nullable): Star rating
  * **review\_text** `string` (nullable): Review text content
  * **review\_time** `string` (nullable): Relative time string (e.g., "2 weeks ago")
  * **review\_id** `string` (nullable): Unique review identifier
  * **business\_response\_text** `string` (nullable): Business owner response text
  * **user\_total\_reviews** `number` (nullable): Total number of reviews by this user
  * **user\_total\_photos** `number` (nullable): Total number of photos by this user
  * **iso\_date** `string` (nullable): ISO 8601 date string
  * **review\_timestamp** `number` (nullable): Raw timestamp of the review
  * **review\_link** `string` (nullable): Link to the review
  * **review\_photos** `array of strings` (nullable): Photo URLs attached to the review
  * **translations** `object` (nullable): Translations of the review
  * **user\_link** `string` (nullable): Link to the reviewer's profile
* **next\_page\_token** `string` (nullable): Pagination cursor — pass as the `cursor` input to fetch the next page; `null` when there are no more pages

**Pagination:**

The response includes a `next_page_token`. Pass it back as the `cursor` input parameter to retrieve the next page of results. When `next_page_token` is `null`, there are no more pages.

**Example Usage:**

```json
{
  "business_id": "0x89c25a3eab6a3b1f:0x12345",
  "limit": 20,
  "sort": "newest"
}
```

To fetch the next page, pass the `next_page_token` from the previous response as `cursor`:

```json
{
  "business_id": "0x89c25a3eab6a3b1f:0x12345",
  "limit": 20,
  "sort": "newest",
  "cursor": "<next_page_token from previous response>"
}
```

***

## Address Validation

Validate, standardize, and geocode addresses using Google Maps Address Validation API.

### Validate Address

Validate an address by checking components, standardizing format, correcting errors, completing missing information, and providing geocoding coordinates. Optionally enable CASS for enhanced US/Puerto Rico address accuracy.

**Operation Type:** Query (Read)

**Parameters:**

* **address** `object` (required): The address to be validated
  * **revision** `number` (nullable): Revision number of the address format
  * **regionCode** `string` (required): CLDR region code of the country/region of the address (e.g., "US", "GB")
  * **languageCode** `string` (nullable): BCP-47 language code for the address language
  * **postalCode** `string` (nullable): Postal code of the address
  * **sortingCode** `string` (nullable): Additional sorting code
  * **administrativeArea** `string` (nullable): Highest administrative subdivision (state, province, etc.)
  * **locality** `string` (nullable): Generally refers to the city/town
  * **sublocality** `string` (nullable): Sublocality of the address
  * **addressLines** `array of strings` (required): Array of address lines representing the address, excluding recipient and country
  * **recipients** `array of strings` (nullable): Name(s) of the recipient(s)
  * **organization** `string` (nullable): Organization name
* **enableUspsCass** `boolean` (nullable): Enables USPS CASS compatible mode for US and Puerto Rico addresses. Improves accuracy but has additional requirements
* **sessionToken** `string` (nullable): Session token for autocomplete sessions to avoid extra billing

**Returns:**

* **result** `object`: Validation result
  * **verdict** `object` (nullable): Validation verdict
    * **inputGranularity** `string` (nullable): Input granularity level. Options: "SUB\_PREMISE", "PREMISE", "PREMISE\_PROXIMITY", "BLOCK", "ROUTE", "OTHER"
    * **validationGranularity** `string` (nullable): Validation granularity level
    * **geocodeGranularity** `string` (nullable): Geocode granularity level
    * **addressComplete** `boolean` (nullable): Whether the address is complete
    * **hasUnconfirmedComponents** `boolean` (nullable): Whether address has unconfirmed components
    * **hasInferredComponents** `boolean` (nullable): Whether address has inferred components
    * **hasReplacedComponents** `boolean` (nullable): Whether address has replaced components
  * **address** `object` (nullable): Validated address
    * **formattedAddress** `string`: Formatted address string
    * **postalAddress** `object`: Postal address components
    * **addressComponents** `array of objects`: Address component details
    * **missingComponentTypes** `array of strings` (nullable): Missing component types
    * **unconfirmedComponentTypes** `array of strings` (nullable): Unconfirmed component types
    * **unresolvedTokens** `array of strings` (nullable): Unresolved address tokens
  * **geocode** `object` (nullable): Geocoding information
    * **location** `object`: Location coordinates
      * **latitude** `number`: Latitude coordinate
      * **longitude** `number`: Longitude coordinate
    * **plusCode** `object` (nullable): Plus Code information
      * **globalCode** `string`: Global Plus Code
      * **compoundCode** `string` (nullable): Compound Plus Code
    * **bounds** `object` (nullable): Location bounds
      * **low** `object`: Lower bound coordinates
      * **high** `object`: Upper bound coordinates
    * **featureSizeMeters** `number` (nullable): Feature size in meters
    * **placeId** `string` (nullable): Google Places place ID
    * **placeTypes** `array of strings` (nullable): Place types
  * **metadata** `object` (nullable): Address metadata
    * **business** `boolean` (nullable): Whether address is a business
    * **poBox** `boolean` (nullable): Whether address is a PO Box
    * **residential** `boolean` (nullable): Whether address is residential
  * **uspsData** `object` (nullable): USPS-specific data (when CASS is enabled)
    * **standardizedAddress** `object` (nullable): USPS standardized address
    * **deliveryPointCode** `string` (nullable): Delivery point code
    * **deliveryPointCheckDigit** `string` (nullable): Delivery point check digit
    * **dpvConfirmation** `string` (nullable): DPV confirmation
    * **dpvFootnote** `string` (nullable): DPV footnote
    * **cmra** `string` (nullable): CMRA indicator
    * **vacant** `string` (nullable): Vacant indicator
    * **pob** `string` (nullable): PO Box indicator
* **responseId** `string` (nullable): Response identifier

**Example Usage:**

```json
{
  "address": {
    "revision": null,
    "regionCode": "US",
    "languageCode": "en",
    "postalCode": "10001",
    "sortingCode": null,
    "administrativeArea": "NY",
    "locality": "New York",
    "sublocality": "Manhattan",
    "addressLines": ["123 Main Street", "Suite 456"],
    "recipients": ["John Smith"],
    "organization": "Acme Corporation"
  },
  "enableUspsCass": true,
  "sessionToken": null
}
```

***

## Solar Analysis

Analyze solar potential for buildings using Google Maps Solar API.

### Get Roof Solar Area

Get solar roof area and sunshine statistics for a building at the specified coordinates. Returns area measurements and sunshine quantiles for solar potential analysis.

**Operation Type:** Query (Read)

**Parameters:**

* **lat** `number` (required): Latitude coordinate
* **lng** `number` (required): Longitude coordinate

**Returns:**

* **areaMeters2** `number` (nullable): Total roof area in square meters
* **sunshineQuantiles** `array of numbers` (nullable): Array of sunshine quantile values
* **groundAreaMeters2** `number` (nullable): Ground area covered by roof in square meters

**Example Usage:**

```json
{
  "lat": 40.7128,
  "lng": -74.006
}
```

***

## Common Use Cases

**Address Verification and Standardization:**

* Validate customer addresses during checkout and registration processes
* Standardize address formats for consistent database storage and mailing
* Geocode addresses to obtain precise coordinates for mapping and delivery routing

**Real Estate and Property Analysis:**

* Analyze solar potential for properties using roof area and sunshine data
* Validate property addresses for real estate listings and transactions
* Assess building locations for renewable energy installations and planning

**Logistics and Delivery:**

* Validate delivery addresses to reduce failed deliveries and returned packages
* Geocode addresses for route optimization and GPS navigation systems
* Verify business addresses for accurate location-based services and directories

**Data Quality and Compliance:**

* Clean and standardize address data for CRM and marketing databases
* Enable USPS CASS validation for mail automation and postal discounts
* Ensure address completeness and accuracy for regulatory compliance and reporting