Google Maps Platform Connector Guide

The Google Maps Platform connector helps you enrich workflows with geocoding, reverse geocoding, route planning, distance analysis, and Places lookup. It is a practical option when your automation needs location-aware decisions, such as matching service regions, calculating delivery ETAs, or validating customer addresses.

Configure your connector

Set api_key to a Google Maps Platform key that has the APIs you need enabled, such as Geocoding API, Directions API, Distance Matrix API, and Places API. If your organization applies key restrictions, confirm that the execution environment is allowed and that billing is active in the linked Google Cloud project.

Use timeout_seconds to control request duration for larger route or matrix responses. A longer timeout can improve reliability for multi-origin distance calculations while avoiding premature workflow failures.

Operations at a glance

• geocode: Address to coordinates and normalized address components
• reverse_geocode: Coordinates to addresses
• directions: Route plans between origin and destination
• distance_matrix: Travel time and distance for origin-destination sets
• places_search: Text-based place discovery
• places_details: Structured details for a selected place
• test: API key and connectivity validation

Run address lookup with geocode

Use geocode when you need to convert a formatted address into normalized location data and coordinates. This is typically the first step before routing or place relevance logic.

const baseUrl = "https://api.example.com/api/v1";
const tenantId = "<TENANT_ID>";
const apiKey = "<API_KEY>";

async function geocodeAddress(integrationId: string) {
  const response = await fetch(`${baseUrl}/integrations/${encodeURIComponent(integrationId)}/execute`, {
    method: "POST",
    headers: {
      "X-API-Key": apiKey,
      "X-Tenant-ID": tenantId,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      operation: "geocode",
      address: "1600 Amphitheatre Parkway, Mountain View, CA",
      language: "en",
      region: "us"
    }),
  });
  if (!response.ok) throw new Error(`Request failed: ${response.status}`);
  return response.json();
}

curl -X POST "https://api.example.com/api/v1/integrations/<ENTITY_ID>/execute" \
  -H "X-API-Key: <API_KEY>" \
  -H "X-Tenant-ID: <TENANT_ID>" \
  -H "Content-Type: application/json" \
  -d '{
    "operation": "geocode",
    "address": "1600 Amphitheatre Parkway, Mountain View, CA",
    "language": "en",
    "region": "us"
  }'

{
  "success": true,
  "data": {
    "success": true,
    "message": "Geocoding completed successfully",
    "status": "OK",
    "result_count": 1,
    "results": [
      {
        "formatted_address": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
        "geometry": {
          "location": {
            "lat": 37.422,
            "lng": -122.084
          }
        }
      }
    ]
  }
}

Run coordinate lookup with reverse_geocode

Use reverse_geocode to resolve lat/lng (or latitude/longitude) into human-readable addresses.

curl -X POST "https://api.example.com/api/v1/integrations/<ENTITY_ID>/execute" \
  -H "X-API-Key: <API_KEY>" \
  -H "X-Tenant-ID: <TENANT_ID>" \
  -H "Content-Type: application/json" \
  -d '{
    "operation": "reverse_geocode",
    "lat": 37.422,
    "lng": -122.084,
    "language": "en"
  }'

Calculate travel with directions

Use directions to generate route options between an origin and destination. This operation is useful for transportation planning, dispatch prioritization, and user-facing ETA estimates.

const baseUrl = "https://api.example.com/api/v1";
const tenantId = "<TENANT_ID>";
const apiKey = "<API_KEY>";

async function getDirections(integrationId: string) {
  const response = await fetch(`${baseUrl}/integrations/${encodeURIComponent(integrationId)}/execute`, {
    method: "POST",
    headers: {
      "X-API-Key": apiKey,
      "X-Tenant-ID": tenantId,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      operation: "directions",
      origin: "Oslo, Norway",
      destination: "Bergen, Norway",
      mode: "driving",
      alternatives: true
    }),
  });
  if (!response.ok) throw new Error(`Request failed: ${response.status}`);
  return response.json();
}

curl -X POST "https://api.example.com/api/v1/integrations/<ENTITY_ID>/execute" \
  -H "X-API-Key: <API_KEY>" \
  -H "X-Tenant-ID: <TENANT_ID>" \
  -H "Content-Type: application/json" \
  -d '{
    "operation": "directions",
    "origin": "Oslo, Norway",
    "destination": "Bergen, Norway",
    "mode": "driving",
    "alternatives": true
  }'

{
  "success": true,
  "data": {
    "success": true,
    "message": "Directions retrieved successfully",
    "status": "OK",
    "route_count": 1,
    "routes": [
      {
        "summary": "E16",
        "legs": [
          {
            "distance": { "text": "463 km", "value": 463000 },
            "duration": { "text": "6 hours 52 mins", "value": 24720 }
          }
        ]
      }
    ]
  }
}

Compare origin and destination sets with distance_matrix

Use distance_matrix when you need many travel estimates in one request. origins and destinations can be arrays or pipe-delimited strings.

curl -X POST "https://api.example.com/api/v1/integrations/<ENTITY_ID>/execute" \
  -H "X-API-Key: <API_KEY>" \
  -H "X-Tenant-ID: <TENANT_ID>" \
  -H "Content-Type: application/json" \
  -d '{
    "operation": "distance_matrix",
    "origins": ["Oslo, Norway", "Drammen, Norway"],
    "destinations": ["Bergen, Norway", "Stavanger, Norway"],
    "mode": "driving",
    "units": "metric"
  }'

Find places with places_search

Use places_search to return nearby places for a query, then call places_details to enrich a selected result with structured place metadata. Chaining these operations works well when your workflow needs candidate selection followed by detail retrieval.

curl -X POST "https://api.example.com/api/v1/integrations/<ENTITY_ID>/execute" \
  -H "X-API-Key: <API_KEY>" \
  -H "X-Tenant-ID: <TENANT_ID>" \
  -H "Content-Type: application/json" \
  -d '{
    "operation": "places_search",
    "query": "coffee near Oslo Central Station",
    "radius": 1500
  }'

Fetch a selected result with places_details

Use places_details with place_id from places_search to retrieve richer metadata such as name, geometry, opening hours, and rating fields.

curl -X POST "https://api.example.com/api/v1/integrations/<ENTITY_ID>/execute" \
  -H "X-API-Key: <API_KEY>" \
  -H "X-Tenant-ID: <TENANT_ID>" \
  -H "Content-Type: application/json" \
  -d '{
    "operation": "places_details",
    "place_id": "ChIJN1t_tDeuEmsRUsoyG83frY4",
    "fields": ["name", "formatted_address", "geometry", "rating"]
  }'

Validate connector setup with test

Use test to confirm key configuration and endpoint reachability. The connector runs a geocode request against a fixed Google HQ address and returns details.test_status.

curl -X POST "https://api.example.com/api/v1/integrations/<ENTITY_ID>/execute" \
  -H "X-API-Key: <API_KEY>" \
  -H "X-Tenant-ID: <TENANT_ID>" \
  -H "Content-Type: application/json" \
  -d '{"operation":"test"}'

Troubleshooting and best practices

A 403 or REQUEST_DENIED response usually means the API key restrictions, enabled APIs, or billing configuration need attention. A ZERO_RESULTS response is a valid outcome, so treat it as an empty dataset rather than a failure.

For quota-related failures, use caching for repeated queries and monitor usage in Google Cloud before raising limits. This helps keep cost and latency stable while maintaining predictable workflow behavior.