get_sido_list
Retrieve a list of South Korean metropolitan administrative divisions (sido) to enable regional filtering for youth activity searches through the Ministry of Gender Equality and Family's public data API.
Instructions
청소년 활동 정보 시도(광역자치단체) 목록을 조회합니다
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| pageNo | No | 페이지 번호 (기본값: 1) | |
| numOfRows | No | 한 페이지 결과 수 (기본값: 100) |
Implementation Reference
- src/index.ts:199-233 (handler)Handler for the 'get_sido_list' tool execution. Parses input arguments, calls the youthApiClient.getSidoList helper, formats the response into a readable text list of provinces (sido) with codes, and returns it as tool content.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:61-73 (schema)Input schema definition for the 'get_sido_list' tool, specifying optional pageNo and numOfRows parameters.inputSchema: { type: "object", properties: { pageNo: { type: "number", description: "페이지 번호 (기본값: 1)", }, numOfRows: { type: "number", description: "한 페이지 결과 수 (기본값: 100)", }, }, },
- src/index.ts:58-74 (registration)Tool registration in the ListTools handler, defining name, description, and input schema for 'get_sido_list'.{ name: "get_sido_list", description: "청소년 활동 정보 시도(광역자치단체) 목록을 조회합니다", inputSchema: { type: "object", properties: { pageNo: { type: "number", description: "페이지 번호 (기본값: 1)", }, numOfRows: { type: "number", description: "한 페이지 결과 수 (기본값: 100)", }, }, }, },
- src/youthApiClient.ts:69-116 (helper)Supporting helper method in YouthApiClient class that makes the HTTP GET request to the public API endpoint '/getSidoList', parses the XML response, handles errors, and returns structured data with totalCount and items array.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; } }