Skip to main content

geo.geocode Tool

Convert addresses to coordinates and vice versa

Overview​

  • Type: Geocoding & reverse geocoding (Nominatim / OpenStreetMap via geopy)
  • Capabilities: geo.geocode, geo.reverse_geocode
  • Egress: Required (controlled)
  • Speed: Sub-second

The tool has one /invoke entry point that switches on the input: pass address for forward geocoding, or lat + lng for reverse geocoding.

Public Endpoint​

Ready to use — available as a public endpoint:

  • Endpoint: geo-geocode-public
  • Pricing: per-request, billed in USD. See the Tools index or the live catalog (GET /api/builder/v1/actions?visibility=public) for the current price.
  • No setup required — just call the API

Quick Start​

from colabhive import ColabHive

client = ColabHive(
    api_key="your_api_key_here",
    account_id="your_account_id_here",
    base_url="https://api.colabhive.com",
)

# Forward: address → coordinates
result = client.endpoints.infer(
    endpoint_id="geo-geocode-public",
    input_data={"address": "1600 Amphitheatre Parkway, Mountain View, CA"},
)
print(result)

# Reverse: coordinates → address
result = client.endpoints.infer(
    endpoint_id="geo-geocode-public",
    input_data={"lat": 37.4224764, "lng": -122.0842499},
)
print(result)

cURL (Alternative)​

Forward geocoding

curl -X POST "https://api.colabhive.com/api/builder/v1/endpoints/{ENDPOINT_ID}/infer" \
  -H "X-Account-ID: YOUR_ACCOUNT_ID" \
  -H "Content-Type: application/json" \
  -d '{"input": {"address": "1600 Amphitheatre Parkway, Mountain View, CA"}}'

Reverse geocoding

curl -X POST "https://api.colabhive.com/api/builder/v1/endpoints/{ENDPOINT_ID}/infer" \
  -H "X-Account-ID: YOUR_ACCOUNT_ID" \
  -H "Content-Type: application/json" \
  -d '{"input": {"lat": 37.4224764, "lng": -122.0842499}}'

Input Parameters​

Forward geocoding​

ParameterTypeRequiredDescription
addressstring✓Full or partial address to geocode
country_biasstringNoOptional country hint to disambiguate

Reverse geocoding​

ParameterTypeRequiredDescription
latfloat✓Latitude (-90 to 90)
lngfloat✓Longitude (-180 to 180)

Output Format​

Both directions return the same shape:

{
  "lat": 37.4224764,
  "lng": -122.0842499,
  "formatted_address": "Google Building 40, 1600, Amphitheatre Parkway, Mountain View, Santa Clara County, California, 94043, United States",
  "confidence": 1.0,
  "duration_ms": 210
}
  • formatted_address is the resolved address string.
  • If nothing is found the request returns a 404 (address / location not found).

When to Use​

✅ Perfect for:

  • Location-based queries for LLMs and agents
  • Store locators, delivery/logistics, travel planning
  • Standardizing free-text addresses to coordinates

❌ Not ideal for:

  • Bulk-geocoding millions of addresses (use a dedicated service)
  • Real-time routing (use a specialized mapping API)

Use Cases​

LLM location lookup​

# Geocode a place the LLM mentioned
location = client.endpoints.infer(
    endpoint_id="geo-geocode-public",
    input_data={"address": "Eiffel Tower, Paris, France"},
)
print(location)   # {"lat": ..., "lng": ..., "formatted_address": ..., ...}

Reverse geocode a map click​

result = client.endpoints.infer(
    endpoint_id="geo-geocode-public",
    input_data={"lat": 37.7749, "lng": -122.4194},
)
print(result["formatted_address"])

Distance between two places​

from math import radians, sin, cos, sqrt, atan2

a = client.endpoints.infer(endpoint_id="geo-geocode-public",
                           input_data={"address": "San Francisco, CA"})
b = client.endpoints.infer(endpoint_id="geo-geocode-public",
                           input_data={"address": "Los Angeles, CA"})

def haversine(lat1, lon1, lat2, lon2):
    R = 6371  # km
    dlat, dlon = radians(lat2 - lat1), radians(lon2 - lon1)
    h = sin(dlat/2)**2 + cos(radians(lat1))*cos(radians(lat2))*sin(dlon/2)**2
    return R * 2 * atan2(sqrt(h), sqrt(1-h))

# distance = haversine(a["lat"], a["lng"], b["lat"], b["lng"])

Tips​

  1. Be specific: more detailed addresses geocode more reliably.
  2. Handle 404s: ambiguous or unknown addresses return a not-found error — fall back to asking for clarification.
  3. Cache results: avoid re-geocoding the same address.
  4. country_bias: pass it to disambiguate common place names.

Next Steps​