cotera
Logo

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.

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:

{
  "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:

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

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

{
  "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:

{
  "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:

{
  "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