find_coordinates
Convert addresses to geographic coordinates using Kakao Local API for location-based services and mapping in Korea.
Instructions
Find coordinates of a given address
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| address | Yes | address to search for | |
| page | No | page number of result |
Implementation Reference
- src/mcp_kakao_local/server.py:46-62 (handler)MCP tool handler for find_coordinates: validates inputs with Pydantic Fields, calls KakaoLocalClient.find_coordinates, handles empty results and exceptions, returns AddressResponse or error dict.
@mcp.tool(description="Find coordinates of a given address") async def find_coordinates( address: str = Field(description="address to search for", min_length=1), page: int = Field(1, description="page number of result", ge=1), ) -> AddressResponse: """ Returns: AddressResponse: An object containing metadata and a list of addresses """ try: response = await kakao_local_client.find_coordinates(address, page=page) if len(response.documents) == 0: return {"success": False, "error": "No coordinates found. Check if the address is correct."} return response except Exception as ex: return {"success": False, "error": str(ex)} - Core implementation in KakaoLocalClient: constructs API params, makes HTTP GET to Kakao Local API endpoint for address coordinates, parses JSON response into AddressResponse model.
async def find_coordinates(self, address: str, page: int = 1, size: int = 10) -> AddressResponse: """https://developers.kakao.com/docs/latest/ko/local/dev-guide#address-coord""" path = f"{self.BASE_URL}/search/address" params = { "query": address, "page": page, "size": size, } response_json = await self._get(path, params) return AddressResponse(**response_json) - src/mcp_kakao_local/models.py:92-94 (schema)Pydantic BaseModel schema for the tool's output: AddressResponse containing meta (paging info) and list of AddressDocument (each with address_name, type, x/y coordinates, etc.).
class AddressResponse(BaseModel): meta: Meta = Field(description="Response metadata") documents: list[AddressDocument] = Field(description="List of addresses") - src/mcp_kakao_local/server.py:46-46 (registration)Registration of the 'find_coordinates' tool via FastMCP's @mcp.tool decorator with description.
@mcp.tool(description="Find coordinates of a given address") - src/mcp_kakao_local/models.py:76-85 (schema)Pydantic model for individual address document in response: includes address_name, type, longitude (x), latitude (y), and address details.
class AddressDocument(BaseModel): address_name: str = Field(description="street address or land-lot address (지번 주소)") address_type: Literal["REGION", "ROAD", "REGION_ADDR", "ROAD_ADDR"] = Field( description="type of address" ) x: str = Field(description="longitude") y: str = Field(description="latitude") address: dict = Field(description="details of land-lot address (지번 주소)") road_address: dict = Field(description="details of street address")