search_by_keyword
Find places in Korea by entering a keyword, filtering by category, or specifying a location and radius using the Kakao Local API. Results can be paginated for easier navigation.
Instructions
Searches for places related to the keyword
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| category_group_code | No | category used for filtering results (CategoryGroupCode resource) | |
| center_coordinate | No | longitude and latitude of a center | |
| keyword | Yes | keyword used to search for places | |
| page | No | page number of result | |
| radius_from_center | No | search radius from the center in meters |
Implementation Reference
- src/mcp_kakao_local/server.py:65-98 (handler)The MCP tool handler for 'search_by_keyword', registered with @mcp.tool decorator. Defines input parameters with Pydantic Field descriptions (schema), includes validation logic, and delegates execution to the KakaoLocalClient helper.@mcp.tool(description="Searches for places related to the keyword") async def search_by_keyword( keyword: str = Field(description="keyword used to search for places", min_length=1), category_group_code: CategoryGroupCode | None = Field( None, description="category used for filtering results (CategoryGroupCode resource)" ), center_coordinate: Coordinate | None = Field( None, description="longitude and latitude of a center" ), radius_from_center: int | None = Field( None, description="search radius from the center in meters", gt=0 ), page: int = Field(1, description="page number of result", ge=1), ) -> LocationSearchResponse: """ Returns: LocationSearchResponse: An object containing metadata and a list of places. """ if center_coordinate: assert radius_from_center is not None if radius_from_center: assert center_coordinate is not None try: return await kakao_local_client.search_by_keyword( keyword, category_group_code, center_coordinate, radius_from_center, page=page, ) except Exception as ex: return {"success": False, "error": str(ex)}
- Supporting utility method in KakaoLocalClient class that implements the core logic: constructs query parameters and performs asynchronous HTTP GET request to the Kakao Local API search/keyword endpoint, returning parsed LocationSearchResponse.async def search_by_keyword( self, keyword: str, category_group_code: CategoryGroupCode | None, center: Coordinate | None, radius: int | None, page: int = 1, size: int = 10, sort_option: LocationSortOption = LocationSortOption.ACCURACY, ) -> LocationSearchResponse: """https://developers.kakao.com/docs/latest/ko/local/dev-guide#search-by-keyword""" path = f"{self.BASE_URL}/search/keyword" params = { "query": keyword, "category_group_code": category_group_code.name if category_group_code else None, "x": center.longitude if center else None, "y": center.latitude if center else None, "radius": radius if radius else None, "page": page, "size": size, "sort": sort_option.value, } response_json = await self._get(path, {k: v for k, v in params.items() if v is not None}) return LocationSearchResponse(**response_json)
- src/mcp_kakao_local/models.py:87-90 (schema)Pydantic BaseModel defining the structure and validation for the tool's output response, used as return type annotation in both handler and helper.class LocationSearchResponse(BaseModel): meta: Meta = Field(description="Response metadata") documents: list[PlaceDocument] = Field(description="List of places")
- src/mcp_kakao_local/models.py:6-9 (schema)Pydantic model for Coordinate type used in optional center_coordinate input parameter.class Coordinate(BaseModel): longitude: str latitude: str
- src/mcp_kakao_local/models.py:16-35 (schema)Enum defining valid CategoryGroupCode values used in optional category_group_code input parameter.class CategoryGroupCode(Enum): MT1 = "대형마트 (Large Mart, Grocery Store)" CS2 = "편의점 (Convenience Store)" PS3 = "어린이집, 유치원 (Daycare, Kindergarten)" SC4 = "학교 (School)" AC5 = "학원 (Academy/Private Institute)" PK6 = "주차장 (Parking Lot)" OL7 = "주유소, 충전소 (Gas Station, Charging Station)" SW8 = "지하철역 (Subway Station)" BK9 = "은행 (Bank)" CT1 = "문화시설 (Cultural Facility)" AG2 = "중개업소 (Agency, e.g. Real Estate)" PO3 = "공공기관 (Public Institution)" AT4 = "관광명소 (Tourist Attraction)" AD5 = "숙박 (Accommodation)" FD6 = "음식점 (Restaurant)" CE7 = "카페 (Cafe)" HP8 = "병원 (Hospital)" PM9 = "약국 (Pharmacy)"