geocode_location
Convert location names to precise coordinates and geographic details for weather lookups. Use before weather tools to ensure accurate results.
Instructions
Convert location names to coordinates and get detailed geographic information.
Use this tool FIRST before calling weather tools to get accurate coordinates for any location. Searches worldwide database of cities, towns, and places with comprehensive metadata.
Args: name: Location name to search for. Can be: - City name: "London", "Tokyo", "New York" - City with country: "Paris, France", "Portland, Oregon" - Region or landmark: "Cornwall", "Lake Tahoe" - Address or place: "Times Square", "Big Ben" count: Maximum number of results to return (1-100). Default is 10. Use 1 if you're confident about the location (e.g., "London, UK") Use 5-10 for ambiguous names (e.g., "Paris" - could be France, Texas, etc.) language: Language code for result names. Options: "en" (English, default), "de" (German), "fr" (French), "es" (Spanish), "it" (Italian), "pt" (Portuguese), etc. format: Response format. Always use "json" (default).
Returns: GeocodingResponse: A Pydantic model containing: - results: List of matching locations, each with: - name: Location name - latitude, longitude: Coordinates (use these for weather tools!) - country, country_code: Country information - timezone: IANA timezone (e.g., "Europe/London") - elevation: Meters above sea level - population: Population (if available) - admin1, admin2: Administrative divisions (state, county, etc.) - feature_code: Type of place (PPLC=capital, PPL=populated place, etc.)
Tips for LLMs: - ALWAYS geocode location names before requesting weather data - Results are sorted by relevance (population, importance) - First result is usually what users mean for well-known cities - For ambiguous names, check country/admin divisions to pick the right one - Use the exact latitude/longitude from results in weather API calls - Timezone from geocoding can be passed to weather APIs for local time - CRITICAL: If no results found, IMMEDIATELY retry with simpler search terms! The API works best with just city names (e.g., "Portland" not "Portland Harbor" or "Portland, Maine") WORKFLOW: If "City, Region" fails → AUTOMATICALLY try just "City" → filter by admin1/admin2/country DO NOT ask the user - just retry automatically with the simpler name! - If still no results after retry: try even simpler terms or use nearest known location - Common pattern: "Harbor Name" fails → retry just the city name → filter by region/country
Example: # Find London coordinates locations = await geocode_location("London", count=1) london = locations.results[0] # Use coordinates for weather: london.latitude, london.longitude
# Handle ambiguous names
locations = await geocode_location("Paris", count=5)
# results[0] = Paris, France (population 2.1M)
# results[1] = Paris, Texas (population 25K)
# Pick based on context or ask user
# If "City, Region" returns no results, try just "City"
locations = await geocode_location("Portland, Maine", count=5)
if not locations.results:
# Try simpler search
locations = await geocode_location("Portland", count=5)
# Filter by country_code='US' and admin1='Maine' to get the right one
portland = next(r for r in locations.results if r.country_code == 'US' and r.admin1 == 'Maine')
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| count | No | ||
| format | No | json | |
| language | No | en |