search_by_category
Find places by category group code within a specific radius. Input center coordinates and radius to retrieve locations such as restaurants, schools, or public institutions using the MCP server for Kakao Local API.
Instructions
Searches for places with matching category group code
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| category_group_code | Yes | category used to search for places (CategoryGroupCode resource) | |
| center_coordinate | Yes | longitude and latitude of a center | |
| page | No | page number of result | |
| radius_from_center | Yes | search radius from the center in meters |
Implementation Reference
- src/mcp_kakao_local/server.py:100-122 (handler)The main handler function for the 'search_by_category' MCP tool, decorated with @mcp.tool for registration and execution. It validates inputs via Pydantic and delegates to the KakaoLocalClient.@mcp.tool(description="Searches for places with matching category group code") async def search_by_category( category_group_code: CategoryGroupCode = Field( description="category used to search for places (CategoryGroupCode resource)" ), center_coordinate: Coordinate = Field(description="longitude and latitude of a center"), radius_from_center: int = Field(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. """ try: return await kakao_local_client.search_by_category( category_group_code, center_coordinate, radius_from_center, page=page, ) except Exception as ex: return {"success": False, "error": str(ex)}
- Helper method in KakaoLocalClient that performs the actual HTTP request to Kakao's search/category endpoint and parses the response into LocationSearchResponse.async def search_by_category( self, category_group_code: CategoryGroupCode, center: Coordinate, radius: int, page: int = 1, size: int = 10, sort_option: LocationSortOption = LocationSortOption.ACCURACY, ) -> LocationSearchResponse: """https://developers.kakao.com/docs/latest/ko/local/dev-guide#search-by-category""" path = f"{self.BASE_URL}/search/category" params = { "category_group_code": category_group_code.name, "x": center.longitude, "y": center.latitude, "radius": radius, "page": page, "size": size, "sort": sort_option.value, } response_json = await self._get(path, params) return LocationSearchResponse(**response_json)
- src/mcp_kakao_local/models.py:87-90 (schema)Pydantic model defining the output schema for search_by_category tool.class LocationSearchResponse(BaseModel): meta: Meta = Field(description="Response metadata") documents: list[PlaceDocument] = Field(description="List of places")
- src/mcp_kakao_local/models.py:16-35 (schema)Enum defining valid category_group_code values used as input schema for the tool.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)"
- src/mcp_kakao_local/models.py:6-9 (schema)Pydantic model for center_coordinate input parameter.class Coordinate(BaseModel): longitude: str latitude: str