Google Maps Integration

Need to add location intelligence to your agents? Connect Google Maps to your workflows and let agents geocode addresses or search for nearby locations—instantly.

TL;DR

Generate a Google Maps API Key, store it in the Vault, and use Drive components like Geocode Address or Get Nearby Places to power geospatial agents.

List of Google Maps Components

Component	Action	What it Does	Inputs	Key Outputs	Use Case
Geocode Address	Convert	Turns an address into coordinates.	urlEncodedAddress	location, response	Enrich a user form with lat/lng.
Get Nearby Places	Search	Finds POIs within a given radius.	location, radius, keyword	results	Suggest coffee spots or ATMs nearby.

Prerequisites

To use Google Maps with SmythOS, you need:

• A Google Cloud Project
• Enabled APIs: Maps JavaScript API, Places API
• A Maps API Key
• A SmythOS account (sign up) and access to the Vault

API Key Setup

Step 1: Create a Google Cloud Project

Open Google Cloud Console and create or select a project.

Step 2: Enable Required APIs

Navigate to APIs & Services > Library and enable:

• Maps JavaScript API
• Places API

Step 3: Generate an API Key

1. Go to Credentials
2. Click Create Credentials > API Key
3. Restrict the key to specific APIs (recommended)

Secure Your Key

Restrict by IP, referrer, and limit to Maps APIs only. Store securely in the Vault.

Step 4: Store Key in Vault

1. Go to Vault > New Secret in SmythOS
2. Name it something like google_maps_api_key
3. Paste the API Key you copied from Google

Component Reference

Geocode Address

This component converts a human-readable address into GPS coordinates (latitude, longitude).

Inputs

Field	Required	Description
urlEncodedAddress	required	Address string formatted for URL (e.g., 1600+Amphitheatre+Parkway,+Mountain+View,+CA).

Outputs

Field	Description
location	Object with lat and lng.
response	Raw JSON from Google Geocoding API.
headers	HTTP headers from the API call.

Use Case

Convert shipping or address input into coordinates and pass to logistics API or distance calculator.

{ "component": "maps.geocodeAddress", "urlEncodedAddress": "1600+Amphitheatre+Parkway,+Mountain+View,+CA" }

Get Nearby Places

Returns nearby points of interest (POIs) based on location, radius, and keyword.

Inputs

Field	Required	Description
location	required	Lat/lng string (e.g., 37.4220,-122.0841).
radius	required	Search radius in meters.
keyword	required	Place type or keyword (e.g., bookstore, atm).

Outputs

Field	Description
results	Array of places with name, address, and geometry.
response	Full response from the Places API.
headers	Metadata headers returned from the call.

Use Case

Pair this with a user’s geocoded address to find relevant venues nearby: coffee, pharmacies, or retail.

{ "component": "maps.getNearbyPlaces", "location": "37.4220,-122.0841", "radius": 1500, "keyword": "restaurant" }

Best Practices

• 🔐 Always store your API key in the Vault, never in plain text.
• 📍 Chain Geocode Address → Get Nearby Places to power geospatial logic.
• ✅ Validate API results by checking status and ZERO_RESULTS.
• ⚠️ Use clear keyword values to improve relevance (e.g., use "pharmacy", not "meds").

Troubleshooting

Error	Cause	Resolution
REQUEST_DENIED	Invalid or missing key	Check Vault and restrictions.
ZERO_RESULTS	No matches found	Try broader keywords or adjust radius.
OVER_QUERY_LIMIT	Daily quota exceeded	Upgrade your plan or reduce frequency.
INVALID_REQUEST	Missing fields	Check inputs for required values.

INFO

Check response.status and error_message in the output for deeper context.

What’s Next?

Example workflows to try:

• Local Finder Agent: Geocode a form address → Find nearby resources
• Routing Helper: Convert multiple addresses to coordinates → Optimize with Maps Distance Matrix
• Venue Recommender: Detect location from IP → Recommend restaurants or hotels nearby