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 author information.

Operation Type: Query (Read)

Parameters:

  • business_id string (required): The Google business ID or Place ID to get reviews for
  • limit number (nullable): Maximum number of reviews to return
  • sort string (nullable): Sort order for reviews

Returns:

  • reviews array of objects: Array of reviews
    • review_id string (nullable): Review identifier
    • author_name string (nullable): Reviewer name
    • rating number (nullable): Review rating (1-5)
    • text string (nullable): Review text
    • published_at string (nullable): Publication date
    • response_text string (nullable): Business owner response

Example Usage:

{
  "business_id": "0x89c25a3eab6a3b1f:0x12345",
  "limit": 50
}

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