search_festivals_by_date
Find Korean festivals and cultural events happening within specific dates. Search by date range and filter by region to plan visits to celebrations and cultural activities in South Korea.
Instructions
Find festivals in Korea by date range.
This tool searches for festivals and events occurring within a specified date range. It's useful for finding cultural events, celebrations, and festivals happening during a particular period or ongoing events.
Args: start_date (str): Start date in YYYYMMDD format (e.g., "20250501" for May 1, 2025) end_date (str, optional): End date in YYYYMMDD format (e.g., "20250531" for May 31, 2025) If not provided, searches for events starting from the start_date area_code (str, optional): Area code to filter results. Valid values: - "1" (Seoul) - "2" (Incheon) - "3" (Daejeon) - "4" (Daegu) - "5" (Gwangju) - "6" (Busan) - "7" (Ulsan) - "8" (Sejong) - "31" (Gyeonggi-do) - "32" (Gangwon-do) - "33" (Chungcheongbuk-do) - "34" (Chungcheongnam-do) - "35" (Gyeongsangbuk-do) - "36" (Gyeongsangnam-do) - "37" (Jeonbuk-do) - "38" (Jeollanam-do) - "39" (Jeju-do) language (str, optional): Language for results (default: "en"). Supported: - "en" (English) - "jp" (Japanese) - "zh-cn" (Simplified Chinese) - "zh-tw" (Traditional Chinese) - "de" (German) - "fr" (French) - "es" (Spanish) - "ru" (Russian) page (int, optional): Page number for pagination (default: 1, min: 1) rows (int, optional): Number of items per page (default: 20, max: 100) filter (list[str], optional): List of keys to include in each result item (whitelist). - If filter is None or an empty list ([]), all fields are returned. - If filter contains values, only the specified keys will be included in each item, and all other keys will be removed.
Returns: dict: Festivals within the specified date range with structure: { "total_count": int, # Total number of matching items "num_of_rows": int, # Number of items per page "page_no": int, # Current page number "start_date": str, # Search start date "end_date": str, # Search end date or "ongoing" "items": [ # List of festival items { "title": str, # Name of the festival "addr1": str, # Primary address "addr2": str, # Secondary address "areacode": str, # Area code "contentid": str, # Unique content ID "contenttypeid": str, # Content type ID "createdtime": str, # Creation timestamp "eventstartdate": str, # Festival start date "eventenddate": str, # Festival end date "firstimage": str, # URL of main image "firstimage2": str, # URL of thumbnail image "mapx": str, # Longitude "mapy": str, # Latitude "mlevel": str, # Map level "tel": str, # Phone number "cat1": str, # Category 1 code "cat2": str, # Category 2 code "cat3": str # Category 3 code } # ... more items ] }
Example: search_festivals_by_date("20250501", "20250531", "1", "en", 1, 20)
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| start_date | Yes | ||
| end_date | No | ||
| area_code | No | ||
| language | No | ||
| page | No | ||
| rows | No | ||
| filter | No |
Implementation Reference
- src/mcp_tourism/server.py:537-620 (handler)The function `search_festivals_by_date` is the handler that implements the festival search logic by date range, registered with the @mcp.tool decorator.
async def search_festivals_by_date( start_date: str, end_date: str | None = None, area_code: str | None = None, language: str | None = None, page: int = 1, rows: int = 20, filter: list[str] | None = None, ) -> dict: """ Find festivals in Korea by date range. This tool searches for festivals and events occurring within a specified date range. It's useful for finding cultural events, celebrations, and festivals happening during a particular period or ongoing events. Args: start_date (str): Start date in YYYYMMDD format (e.g., "20250501" for May 1, 2025) end_date (str, optional): End date in YYYYMMDD format (e.g., "20250531" for May 31, 2025) If not provided, searches for events starting from the start_date area_code (str, optional): Area code to filter results. Valid values: - "1" (Seoul) - "2" (Incheon) - "3" (Daejeon) - "4" (Daegu) - "5" (Gwangju) - "6" (Busan) - "7" (Ulsan) - "8" (Sejong) - "31" (Gyeonggi-do) - "32" (Gangwon-do) - "33" (Chungcheongbuk-do) - "34" (Chungcheongnam-do) - "35" (Gyeongsangbuk-do) - "36" (Gyeongsangnam-do) - "37" (Jeonbuk-do) - "38" (Jeollanam-do) - "39" (Jeju-do) language (str, optional): Language for results (default: "en"). Supported: - "en" (English) - "jp" (Japanese) - "zh-cn" (Simplified Chinese) - "zh-tw" (Traditional Chinese) - "de" (German) - "fr" (French) - "es" (Spanish) - "ru" (Russian) page (int, optional): Page number for pagination (default: 1, min: 1) rows (int, optional): Number of items per page (default: 20, max: 100) filter (list[str], optional): List of keys to include in each result item (whitelist). - If filter is None or an empty list ([]), all fields are returned. - If filter contains values, only the specified keys will be included in each item, and all other keys will be removed. Returns: dict: Festivals within the specified date range with structure: { "total_count": int, # Total number of matching items "num_of_rows": int, # Number of items per page "page_no": int, # Current page number "start_date": str, # Search start date "end_date": str, # Search end date or "ongoing" "items": [ # List of festival items { "title": str, # Name of the festival "addr1": str, # Primary address "addr2": str, # Secondary address "areacode": str, # Area code "contentid": str, # Unique content ID "contenttypeid": str, # Content type ID "createdtime": str, # Creation timestamp "eventstartdate": str, # Festival start date "eventenddate": str, # Festival end date "firstimage": str, # URL of main image "firstimage2": str, # URL of thumbnail image "mapx": str, # Longitude "mapy": str, # Latitude "mlevel": str, # Map level "tel": str, # Phone number "cat1": str, # Category 1 code "cat2": str, # Category 2 code "cat3": str # Category 3 code } # ... more items ] - src/mcp_tourism/server.py:536-536 (registration)Tool registration using the @mcp.tool decorator for the `search_festivals_by_date` function.
@mcp.tool