Convert a location string (city, address, or landmark) to latitude/longitude coordinates for use with location-based queries.
Quick Example
{
"location": "San Francisco, CA"
}Input Parameters
| Parameter | Type | Required | Default | Constraints | Description |
|---|---|---|---|---|---|
| location | string | Yes | - | Min 1 character | Location string to geocode |
| provider | string | No | "google" | "google" | Geocoding provider |
| workflow_id | string | No | - | Valid UUID | Workflow session identifier |
Request Schema:
interface GeocodeLocationParams {
location: string;
provider?: "google";
workflow_id?: string;
}Output Format
{
latitude: number,
longitude: number,
formatted_address: string,
confidence: "high" | "medium" | "low",
provider: string,
tool_trace_id: string,
workflow_id: string
}Response Fields:
| Field | Type | Description |
|---|---|---|
| latitude | number | Latitude coordinate |
| longitude | number | Longitude coordinate |
| formatted_address | string | Normalized address from geocoding service |
| confidence | string | Confidence level: "high", "medium", or "low" |
| provider | string | Geocoding provider used |
| tool_trace_id | string | OpenTelemetry trace ID |
| workflow_id | string | Workflow session identifier |
Example Response:
{
"latitude": 37.7749,
"longitude": -122.4194,
"formatted_address": "San Francisco, CA, USA",
"confidence": "high",
"provider": "google",
"tool_trace_id": "a1b2c3d4e5f6",
"workflow_id": "550e8400-e29b-41d4-a716-446655440000"
}Error Handling
Common Errors:
- Unresolvable location: "Could not geocode location. Please provide a more specific location."
- Empty location string: "Location string cannot be empty"
Usage Examples
Example 1: City name
{
"location": "San Francisco, CA"
}Example 2: Full address
{
"location": "1600 Amphitheatre Parkway, Mountain View, CA"
}Example 3: Landmark
{
"location": "Times Square, New York"
}Example 4: Use with entity_find
First geocode the location:
{
"location": "Chicago, IL"
}Then use the coordinates in entity_find:
{
"entity_type": "person",
"expression": "1000000001 AND 1000000002",
"location": {
"latitude": 41.8781,
"longitude": -87.6298,
"radius": 25,
"unit": "miles"
}
}