geocode_address
Convert addresses or place names to geographic coordinates with location details for mapping, navigation, and geospatial analysis.
Instructions
Convert an address or place name to geographic coordinates with detailed location information.
This tool takes a text description of a location (such as an address, landmark name, or place of interest) and returns its precise geographic coordinates along with rich metadata. The results can be used for mapping, navigation, location-based analysis, and as input to other geospatial tools.
Args: address: The address, place name, landmark, or description to geocode (e.g., "Empire State Building", "123 Main St, Springfield", "Golden Gate Park, San Francisco")
Returns: List of matching locations with: - Geographic coordinates (latitude/longitude) - Formatted address - Administrative boundaries (city, state, country) - OSM type and ID - Bounding box (if applicable) - Importance ranking
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| address | Yes |
Implementation Reference
- src/osm_mcp_server/server.py:202-237 (handler)The primary handler function for the 'geocode_address' tool. It is registered via the @mcp.tool() decorator and implements the core logic by calling the OSMClient.geocode method, enhancing results with coordinates, and returning the geocoded locations.
@mcp.tool() async def geocode_address(address: str, ctx: Context) -> List[Dict]: """ Convert an address or place name to geographic coordinates with detailed location information. This tool takes a text description of a location (such as an address, landmark name, or place of interest) and returns its precise geographic coordinates along with rich metadata. The results can be used for mapping, navigation, location-based analysis, and as input to other geospatial tools. Args: address: The address, place name, landmark, or description to geocode (e.g., "Empire State Building", "123 Main St, Springfield", "Golden Gate Park, San Francisco") Returns: List of matching locations with: - Geographic coordinates (latitude/longitude) - Formatted address - Administrative boundaries (city, state, country) - OSM type and ID - Bounding box (if applicable) - Importance ranking """ osm_client = ctx.request_context.lifespan_context.osm_client results = await osm_client.geocode(address) # Enhance results with additional context for result in results: if "lat" in result and "lon" in result: result["coordinates"] = { "latitude": float(result["lat"]), "longitude": float(result["lon"]) } return results - src/osm_mcp_server/server.py:25-44 (helper)The supporting 'geocode' method in the OSMClient class that performs the actual HTTP request to Nominatim API for geocoding the address.
async def geocode(self, query: str) -> List[Dict]: """Geocode an address or place name""" if not self.session: raise RuntimeError("OSM client not connected") nominatim_url = "https://nominatim.openstreetmap.org/search" async with self.session.get( nominatim_url, params={ "q": query, "format": "json", "limit": 5 }, headers={"User-Agent": "OSM-MCP-Server/1.0"} ) as response: if response.status == 200: return await response.json() else: raise Exception(f"Failed to geocode '{query}': {response.status}") - src/osm_mcp_server/server.py:12-24 (helper)The OSMClient class that manages the HTTP session and provides the geocoding functionality used by the tool handler.
class OSMClient: def __init__(self, base_url="https://api.openstreetmap.org/api/0.6"): self.base_url = base_url self.session = None self.cache = {} # Simple in-memory cache async def connect(self): self.session = aiohttp.ClientSession() async def disconnect(self): if self.session: await self.session.close() - src/osm_mcp_server/server.py:202-202 (registration)The @mcp.tool() decorator registers the geocode_address function as an MCP tool.
@mcp.tool()