get_sido_list
Retrieve a list of South Korean metropolitan and provincial administrative divisions (sido) to enable regional filtering for youth activity searches through the Ministry of Gender Equality and Family's public data.
Instructions
청소년 활동 정보 시도(광역자치단체) 목록을 조회합니다
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| pageNo | No | 페이지 번호 (기본값: 1) | |
| numOfRows | No | 한 페이지 결과 수 (기본값: 100) |
Implementation Reference
- src/index.ts:199-233 (handler)Main tool handler for 'get_sido_list': extracts pagination parameters, calls youthApiClient.getSidoList(), formats results into a user-friendly text list with province names and codes.
case "get_sido_list": { const pageNo = (args?.pageNo as number) || 1; const numOfRows = (args?.numOfRows as number) || 100; const result = await youthApiClient.getSidoList(pageNo, numOfRows); // 결과 포맷팅 let resultText = `📍 시도 목록 (전체 ${result.totalCount}개)\n\n`; if (Array.isArray(result.items)) { result.items.forEach((item: any, index: number) => { resultText += `${index + 1}. ${item.ctpvNm || "N/A"} (코드: ${ item.ctpvCode || "N/A" })\n`; }); } else if (result.items) { // 단일 항목인 경우 resultText += `1. ${result.items.ctpvNm || "N/A"} (코드: ${ result.items.ctpvCode || "N/A" })\n`; } else { resultText += "조회된 항목이 없습니다.\n"; } resultText += `\n페이지: ${pageNo}/${Math.ceil( result.totalCount / numOfRows )}`; return { content: [ { type: "text", text: resultText, }, ], }; } - src/index.ts:59-74 (schema)Input schema definition for the 'get_sido_list' tool, specifying optional pagination parameters pageNo and numOfRows.
name: "get_sido_list", description: "청소년 활동 정보 시도(광역자치단체) 목록을 조회합니다", inputSchema: { type: "object", properties: { pageNo: { type: "number", description: "페이지 번호 (기본값: 1)", }, numOfRows: { type: "number", description: "한 페이지 결과 수 (기본값: 100)", }, }, }, }, - src/index.ts:56-187 (registration)Registration of 'get_sido_list' tool in the list of available tools returned by ListToolsRequestSchema handler.
tools: [ // 청소년 활동 API 관련 도구 { name: "get_sido_list", description: "청소년 활동 정보 시도(광역자치단체) 목록을 조회합니다", inputSchema: { type: "object", properties: { pageNo: { type: "number", description: "페이지 번호 (기본값: 1)", }, numOfRows: { type: "number", description: "한 페이지 결과 수 (기본값: 100)", }, }, }, }, { name: "get_sigungu_list", description: "특정 시도의 시군구(기초자치단체) 목록을 조회합니다", inputSchema: { type: "object", properties: { sido: { type: "string", description: "시도명 (예: 서울, 부산광역시, 경기도)", }, pageNo: { type: "number", description: "페이지 번호 (기본값: 1)", }, numOfRows: { type: "number", description: "한 페이지 결과 수 (기본값: 100)", }, }, required: ["sido"], }, }, { name: "search_youth_activities", description: "청소년 활동 프로그램을 검색합니다. 프로그램명, 기관명, 지역, 기간 등으로 필터링 가능합니다", inputSchema: { type: "object", properties: { pageNo: { type: "number", description: "페이지 번호 (기본값: 1)", }, numOfRows: { type: "number", description: "한 페이지 결과 수 (기본값: 10)", }, atName: { type: "string", description: "프로그램명 (선택사항)", }, orgName: { type: "string", description: "주최자(기관명) (선택사항)", }, sido: { type: "string", description: "시도명 (선택사항, 예: 서울, 부산광역시)", }, startDate: { type: "string", description: "일활동기간시작일 (선택사항, YYYYMMDD 형식)", }, endDate: { type: "string", description: "일활동기간종료일 (선택사항, YYYYMMDD 형식)", }, }, }, }, { name: "get_facility_group_list", description: "청소년 시설 그룹 목록을 조회합니다. 시도, 기관명, 기관유형으로 필터링 가능합니다", inputSchema: { type: "object", properties: { pageNo: { type: "number", description: "페이지 번호 (기본값: 1)", }, numOfRows: { type: "number", description: "한 페이지 결과 수 (기본값: 10)", }, sido: { type: "string", description: "시도명 (선택사항)", }, stName: { type: "string", description: "기관명 (선택사항)", }, gName: { type: "string", description: "기관유형명 (선택사항)", }, }, }, }, // 기본 유틸리티 도구 { name: "echo", description: "입력받은 메시지를 그대로 반환합니다", inputSchema: { type: "object", properties: { message: { type: "string", description: "반환할 메시지", }, }, required: ["message"], }, }, { name: "get_time", description: "현재 시간을 반환합니다", inputSchema: { type: "object", properties: {}, }, }, ], }; - src/youthApiClient.ts:69-116 (helper)Helper function in YouthApiClient that performs the actual API call to retrieve sido list, parses XML response from public data portal, validates, and structures the data.
async getSidoList( pageNo: number = 1, numOfRows: number = 100 ): Promise<any> { try { const response = await this.client.get("/getSidoList", { params: { serviceKey: this.serviceKey, pageNo, numOfRows, }, }); // XML 응답 파싱 const parsedData = await this.parseXmlResponse(response.data); // 응답 구조 확인 if (parsedData.response) { const header = parsedData.response.header; const body = parsedData.response.body; // 에러 체크 if (header?.resultCode !== "00") { throw new Error( `API 오류: ${header?.resultMsg || "알 수 없는 오류"}` ); } return { totalCount: parseInt(body?.totalCount || "0"), items: body?.items?.item || [], pageNo, numOfRows, }; } throw new Error("예상치 못한 응답 형식"); } catch (error) { if (axios.isAxiosError(error)) { throw new Error( `API 호출 실패: ${error.message}${ error.response?.data ? ` - ${error.response.data}` : "" }` ); } throw error; } }