{"id":21662493,"url":"https://github.com/leegeunhyeok/school-kr","last_synced_at":"2025-04-11T23:43:30.072Z","repository":{"id":42222775,"uuid":"130546966","full_name":"leegeunhyeok/school-kr","owner":"leegeunhyeok","description":"🍚🍴 전국 교육청 급식, 학사일정 파싱 라이브러리","archived":false,"fork":false,"pushed_at":"2023-01-07T04:29:49.000Z","size":1622,"stargazers_count":46,"open_issues_count":12,"forks_count":10,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-03-25T19:40:44.524Z","etag":null,"topics":["javascript","node-module","nodejs","school","school-kr"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/school-kr","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/leegeunhyeok.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-04-22T07:58:40.000Z","updated_at":"2025-02-01T09:10:42.000Z","dependencies_parsed_at":"2023-02-06T11:40:11.655Z","dependency_job_id":null,"html_url":"https://github.com/leegeunhyeok/school-kr","commit_stats":null,"previous_names":["leegeunhyeok/node-school-kr"],"tags_count":16,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leegeunhyeok%2Fschool-kr","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leegeunhyeok%2Fschool-kr/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leegeunhyeok%2Fschool-kr/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leegeunhyeok%2Fschool-kr/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/leegeunhyeok","download_url":"https://codeload.github.com/leegeunhyeok/school-kr/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248497903,"owners_count":21113982,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["javascript","node-module","nodejs","school","school-kr"],"created_at":"2024-11-25T10:16:27.986Z","updated_at":"2025-04-11T23:43:30.047Z","avatar_url":"https://github.com/leegeunhyeok.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# school-kr\n\n\u003e 전국 초, 등, 고등학교 및 병설유치원 급식, 학사일정 파싱 라이브러리\n\n[![npm version](https://img.shields.io/npm/v/school-kr.svg)](https://www.npmjs.com/package/school-kr)\n[![downloads](https://img.shields.io/npm/dt/school-kr.svg)](https://www.npmjs.com/package/school-kr)\n[![license](https://img.shields.io/npm/l/school-kr.svg)](https://www.npmjs.com/package/school-kr)\n[![circleci](https://circleci.com/gh/leegeunhyeok/school-kr.svg?style=shield)](https://circleci.com/gh/leegeunhyeok/school-kr)\n\n본 라이브러리는 `Node.js` 환경에서 사용할 수 있는 Promise 기반의 `급식 API` + `학사일정 API` 통합 라이브러리 입니다.\n\n전국 교육청 학생 서비스 페이지(stu.xxx.go.kr)를 파싱하여 이번 달 **학사일정**과 **급식 정보**를 JSON 데이터로 제공합니다.\n\n`3.0.0` 버전부터 파싱 방식이 아닌 API 호출을 통해 데이터를 수집하여 제공합니다.\n\n- `시간표 정보`도 필요하신가요? 그렇다면 [comcigan-parser](https://github.com/leegeunhyeok/comcigan-parser) 라이브러리도 함께 확인해보세요!\n\n## 설치하기\n\n[NPM](https://www.npmjs.com/package/school-kr) 저장소를 통해 다운로드 받을 수 있으며 별다른 작업 없이 바로 사용 가능합니다.\n\n```bash\nnpm i school-kr\n```\n\n## 테스트\n\n아래 명령어를 입력하여 미리 작성된 예제 코드를 실행해볼 수 있습니다.  \n`sample/sample.js` 코드가 실행되며, 학교는 `광명경영회계고등학교` 기준으로 실행됩니다.\n\n```bash\nnpm test\n```\n\n`v2` 버전과 `v3` 버전의 성능 비교\n\n\u003cimg width=\"200\" src=\"./test/test_v2.png\"\u003e\n\n---\n\n\u003cimg width=\"200\" src=\"./test/test_v3.png\"\u003e\n\n\u003e v3는 v2 대비 약 25%의 성능이 향상됨 (네트워크 상태에 따라 일부 변동될 수 있음)\n\n테스트 코드는 `test/test_v2.js`, `test/test_v3.js` 참고\n\n## 개발 문서\n\n### School\n\n모듈을 불러오면 School 클래스의 인스턴스를 생성할 수 있습니다.\n\n```javascript\nconst School = require('school-kr');\nnew School();\n```\n\n---\n\n### School.Type\n\n[학교 종류](#학교-종류) 참조\n\n---\n\n### School.Region\n\n[교육청 관할 지역](#교육청-관할-지역) 참조\n\n---\n\n### (Method) School.search\n\n지정한 지역의 학교를 검색하여 정보를 반환합니다.\n\n| Parameter |  Type  | Required |\n| :-------- | :----: | :------: |\n| region    | Symbol |    O     |\n| name      | string |    O     |\n\nReturn type: `Promise\u003cArray\u003cany\u003e\u003e`, [참고](#검색-데이터-형식)\n\n```javascript\nconst school = new School();\nschool.search(region, name);\n```\n\n예제는 [학교 검색](#학교-검색) 참조\n\n---\n\n### (Method) School.init\n\n인스턴스 정보를 지정한 학교로 초기화 합니다.\n\n| Parameter  |  Type  | Required |\n| :--------- | :----: | :------: |\n| type       | Symbol |    O     |\n| region     | Symbol |    O     |\n| schoolCode | string |    O     |\n\nReturn type: `void`\n\n```javascript\nconst school = new School();\nschool.init(type, region, schoolCode);\n```\n\n예제는 [인스턴스 초기화](#인스턴스-초기화) 참조\n\n---\n\n### (Method) School.getMeal\n\n이번 달 또는 지정한 년도/월의 급식 데이터를 반환합니다  \n년도 또는 월을 지정하지 않을 경우 **현재 시점의 날짜** 기준의 데이터를 반환합니다.\n\n| Parameter |  Type  | Required |\n| :-------- | :----: | :------: |\n| year      |  any   |    X     |\n| month     | number |    X     |\n\nReturn type: `Promise\u003cany\u003e`, [참고](#급식-데이터-형식)\n\n```javascript\nschool.getMeal(year, month);\n```\n\n예제는 [급식 및 학사일정 조회](#급식-및-학사일정-조회) 참조\n\n---\n\n### (Method) School.getCalendar\n\n이번 달 또는 지정한 년도/월의 학사일정 데이터를 반환합니다  \n년도 또는 월을 지정하지 않을 경우 **현재 시점의 날짜** 기준의 데이터를 반환합니다.\n\n| Parameter |  Type  | Required |\n| :-------- | :----: | :------: |\n| year      |  any   |    X     |\n| month     | number |    X     |\n\nReturn type: `Promise\u003cany\u003e`, [참고](#학사일정-데이터-형식)\n\n```javascript\nschool.getCalendar(year, month);\n```\n\n예제는 [급식 및 학사일정 조회](#급식-및-학사일정-조회) 참조\n\n---\n\n## 사용 방법\n\n### School 인스턴스 생성\n\n`school-kr` 모듈을 불러온 후 인스턴스를 생성합니다.  \n생성 후 반드시 `init()`를 호출하여 데이터를 조회할 학교로 초기화합니다.\n\n- init() 호출 없이 데이터를 불러올 경우 Error가 Throw 됩니다.\n\n```javascript\nconst School = require('school-kr')\nconst school = new School()\n\n/*\n* @param type: 학교 유형(초, 중, 고, 병설유치원)\n* @param region: 교육청 관할 지역\n* @param schoolCode: 학교 고유 코드\n*/\nschool.init(/* Type */, /* Region */, /* SchoolCode */)\n```\n\n#### 학교 종류\n\n학교 종류는 `School.Type` 에서 선택할 수 있습니다.\n\n```javascript\nconst School = require('school-kr');\n\n/* 4 */\nconsole.log(School.Type.HIGH);\n```\n\n|    유형    | Key            | Value |\n| :--------: | :------------- | :---: |\n| 병설유치원 | `KINDERGARTEN` |   1   |\n|  초등학교  | `ELEMENTARY`   |   2   |\n|   중학교   | `MIDDLE`       |   3   |\n|  고등학교  | `HIGH`         |   4   |\n\n#### 교육청 관할 지역\n\n지역은 생성한 `School.Region` 에서 선택할 수 있습니다.\n\n```javascript\nconst School = require('school-kr');\n\n/* stu.sen.go.kr */\nconsole.log(School.Region.SEOUL);\n```\n\n| 지역 | Key         | Value         |\n| :--: | :---------- | :------------ |\n| 서울 | `SEOUL`     | stu.sen.go.kr |\n| 인천 | `INCHEON`   | stu.ice.go.kr |\n| 부산 | `BUSAN`     | stu.pen.go.kr |\n| 광주 | `GWANGJU`   | stu.gen.go.kr |\n| 대전 | `DAEJEON`   | stu.dge.go.kr |\n| 대구 | `DEAGU`     | stu.dge.go.kr |\n| 세종 | `SEJONG`    | stu.sje.go.kr |\n| 울산 | `ULSAN`     | stu.use.go.kr |\n| 경기 | `GYEONGGI`  | stu.goe.go.kr |\n| 강원 | `KANGWON`   | stu.kwe.go.kr |\n| 충북 | `CHUNGBUK`  | stu.cbe.go.kr |\n| 충남 | `CHUNGNAM`  | stu.cne.go.kr |\n| 경북 | `GYEONGBUK` | stu.gbe.go.kr |\n| 경남 | `GYEONGNAM` | stu.gne.go.kr |\n| 전북 | `JEONBUK`   | stu.jbe.go.kr |\n| 전남 | `JEONNAM`   | stu.jne.go.kr |\n| 제주 | `JEJU`      | stu.jje.go.kr |\n\n## 학교 코드\n\n`School.search()`를 통해 학교 코드를 검색할 수 있습니다.  \n자세한 사용법은 [학교 검색](#학교-검색) 참조\n\n## 사용 예시\n\n※ 아래 예제는 경기도의 `광명경영회계고등학교`를 기준으로 진행됩니다.\n\n### 학교 검색\n\n```javascript\nconst School = require('school-kr');\nconst school = new School();\n\nschool.search(School.Region.GYEONGGI, '광명경영회계고');\n```\n\n### 인스턴스 초기화\n\n```javascript\nconst School = require('school-kr');\nconst school = new School();\n\nschool.init(School.Type.HIGH, School.Region.GYEONGGI, 'J100000488');\n```\n\n### 급식 및 학사일정 조회\n\n#### 사용 예시\n\n```javascript\nconst School = require('school-kr');\nconst school = new School();\n\nconst example = async function () {\n  // 학교 검색 및 첫 번째 결과의 학교 코드로 초기화\n  const result = await school.search(School.Region.GYEONGGI, '광명경영회계고');\n  school.init(School.Type.HIGH, School.Region.GYEONGGI, result[0].schoolCode);\n\n  const meal = await school.getMeal();\n  const calendar = await school.getCalendar();\n\n  // 오늘 날짜\n  console.log(`${meal.month}월 ${meal.day}일`);\n\n  // 오늘 급식 정보\n  console.log(meal.today);\n\n  // 이번 달 급식 정보\n  console.log(meal);\n\n  // 이번 달 학사일정\n  console.log(calendar);\n\n  // 년도와 달을 지정하여 해당 날짜의 데이터를 조회할 수 있습니다.\n  const mealCustom = await school.getMeal(2018, 9);\n  const calendarCustom = await school.getCalendar(2017, 4);\n\n  console.log(mealCustom);\n  console.log(calendarCustom);\n\n  // 년도값 대신 옵션 객체를 전달하여 데이터 수집 가능\n  // year: 년도 (기본값: 현재 시점의 년도)\n  // month: 달 (기본값: 현재 시점의 달)\n  // default: 급식이 없는 경우 기본값 (기본값: '')\n  const optionMeal = await school.getMeal({\n    year: 2018,\n    month: 9,\n    default: '급식이 없습니다',\n  });\n\n  // 년도값 대신 옵션 객체를 전달하여 데이터 수집 가능\n  // year: 년도 (기본값: 현재 시점의 년도)\n  // month: 달 (기본값: 현재 시점의 달)\n  // default: 급식이 없는 경우 기본값 (기본값: '')\n  // separator: 하루에 2개 이상의 일정이 있는 경우의 구분문자 (기본값: ,)\n  //            예: 겨울방학,토요휴업일\n  const optionCalendar = await school.getCalendar({\n    default: '일정 없는 날',\n    separator: '\\n',\n  });\n\n  console.log(optionMeal);\n  console.log(optionCalendar);\n};\n\nexample();\n```\n\n### 검색 데이터 형식\n\n`search` 반환 데이터 형식은 아래와 같습니다.\n\n| Key        |    Value    | 비고      |\n| :--------- | :---------: | :-------- |\n| name       |   학교명    |           |\n| schoolCode |  학교 코드  | NEIS 코드 |\n| address    | 학교 소재지 |           |\n\n```javascript\n// 경기, 소하 키워드 검색 결과\n[\n  {\n    name: '소하초등학교병설유치원',\n    schoolCode: 'J100005055',\n    address: '경기도 광명시 소하1동',\n  },\n  {\n    name: '소하초등학교',\n    schoolCode: 'J100001213',\n    address: '경기도 광명시 소하동',\n  },\n  { name: '소하중학교', schoolCode: 'J100001194', address: '경기도 광명시 소하동' },\n  {\n    name: '소하고등학교',\n    schoolCode: 'J100000632',\n    address: '경기도 광명시 소하1동',\n  },\n];\n```\n\n### 급식 데이터 형식\n\n`getMeal` 반환 데이터 형식은 아래와 같습니다.\n\n| Key    |      Value       | 비고                                              |\n| :----- | :--------------: | :------------------------------------------------ |\n| 1 ~ 31 | 해당 날짜의 급식 | 급식이 없는 경우 option.default 값 혹은 빈 문자열 |\n| year   |    조회 년도     |                                                   |\n| month  |     조회 달      |                                                   |\n| day    |    오늘 날짜     | 사용자 지정 년도/월이 이번 달이 아닌 경우 0       |\n| today  |    오늘 급식     | 급식이 없는 경우 기본 급식 값                     |\n\n```javascript\n{\n  '1': '[중식]\\n발아현미밥\\n미역국5.6.9....', // 이번달 1일 메뉴\n  '2': '[중식]\\n얼갈이된장무침5.6.\\n칼슘찹쌀....', // 이번달 2일 메뉴\n  '3': '[중식]\\n투움바파스타(주식)1.2.5.6.9.13.15.\\n....', // 이번달 3일 메뉴\n  '4': '', // 급식이 없을 경우 option.default 값 혹은 빈 문자열\n  '5': '',\n  ...\n  'year': 2018, // 이번 년도\n  'month': 5,   // 이번 달\n  'day': 3,     // 오늘 날짜\n  'today': '[중식]\\n투움바파스타(주식)1.2.5.6.9.13.15.\\n....' // 오늘 메뉴\n}\n```\n\n### 학사일정 데이터 형식\n\n`getCalendar` 반환 데이터 형식은 아래와 같습니다.\n\n| Key    |      Value       | 비고                                              |\n| :----- | :--------------: | :------------------------------------------------ |\n| 1 ~ 31 | 해당 날짜의 일정 | 일정이 없는 경우 option.default 값 혹은 빈 문자열 |\n| year   |    조회 년도     |                                                   |\n| month  |     조회 달      |                                                   |\n| day    |    오늘 날짜     | 사용자 지정 년도/월이 이번 달이 아닌 경우 0       |\n| today  |    오늘 급식     | 일정이 없는 경우 기본 일정 값                     |\n\n```javascript\n{\n  '1': '', // 이번 달 1일의 일정\n  '2': '', // 일정이 없을 경우 option.default 값 혹은 빈 문자열\n  '3': '',\n  '4': '개교기념일', // 4일 일정\n  '5': '',\n  '6': '',\n  '7': '대체공휴일',\n  ...\n  'year': 2018,\n  'month': 5 // 이번 달\n  'day': 4,  // 오늘 날짜\n  'today': '개교기념일' // 오늘의 일정\n}\n```\n\n## 문제 신고\n\nv3 미만의 버전을 사용하시는 경우 교육청 홈페이지의 리뉴얼 등의 문제로 파싱이 불가능 할 수 있습니다. v3 이상 사용을 권장하며, 문제가 발생할 경우 [이슈](https://github.com/leegeunhyeok/school-kr/issues)를 남겨주시면 최대한 빠르게 수정하여 반영하도록 하겠습니다.\n\n## 변경사항\n\n- `3.1.2`\n  - [Issue #26](https://github.com/leegeunhyeok/school-kr/issues/25) 3월 이전의 학사일정을 제대로 불러오지 못하던 문제 수정 - Thanks to [cjaewon](https://github.com/cjaewon)\n- `3.1.1`\n  - [Issue #19](https://github.com/leegeunhyeok/school-kr/issues/19) 서로 다른 지역의 학교 데이터를 불러올 경우 발생하던 문제 수정 (검색, 급식, 공지 모두 해당함)\n  - 개발 의존성 모듈 업데이트\n- `3.1.0`\n  - [Issue #9](https://github.com/leegeunhyeok/school-kr/issues/9) 세션 관련 로직 개선 (확인 필요)\n  - [Issue #16](https://github.com/leegeunhyeok/school-kr/issues/16) 타입스크립트 지원(d.ts 추가) - Thanks to [cjaewon](https://github.com/cjaewon)\n  - ESLint 구성 추가 및 코드 스타일 수정\n- `3.0.3`\n  - [Issue #15](https://github.com/leegeunhyeok/school-kr/issues/15) 모듈을 불러올 수 없던 문제 수정\n- `3.0.2`\n  - [Issue #11](https://github.com/leegeunhyeok/school-kr/issues/11), [Issue #14](https://github.com/leegeunhyeok/school-kr/issues/14) 1년 이전 데이터가 파싱되던 문제 수정\n- `3.0.1`\n  - [Issue #10](https://github.com/leegeunhyeok/school-kr/issues/10) 교육청 지역별 세션 유지하도록 수정\n- `3.0.0`\n  - node-school-kr -\u003e school-kr로 모듈명 변경\n  - HTTP 요청 코드를 기존의 request에서 모두 axios로 변경\n  - 페이지 HTML 파싱 방식에서 API 데이터 요청 방식으로 변경함에 따라 데이터 수집 성능 개선 - `약 25%`\n  - [Issue #2](https://github.com/leegeunhyeok/school-kr/issues/2) 학교 정보(코드) 조회를 위한 search 메소드 추가 - [참고](#method-schoolsearch)\n  - [Issue #6](https://github.com/leegeunhyeok/school-kr/issues/6) 1~2월 데이터를 조회할 경우 잘못된 데이터가 나오던 문제 수정 - [참고](https://github.com/leegeunhyeok/school-kr/issues/6#issuecomment-575427817)\n  - 3.0.0 부터 사용하지 않음 (Deprecated)\n    - `School.reset`\n    - `School.getTargetURL`\n  - 3.0.0에 맞도록 문서 수정, [Issue #7](https://github.com/leegeunhyeok/school-kr/issues/5) 마크다운 형식 수정\n- `2.2.2`\n  - [Issue #5](https://github.com/leegeunhyeok/school-kr/issues/5) 대전 교육청 URL 문제 수정\n- `2.2.1`\n  - [Issue #4](https://github.com/leegeunhyeok/school-kr/issues/4) 학사일정 기본값 오류 수정\n- `2.2.0`\n  - [Issue #3](https://github.com/leegeunhyeok/school-kr/issues/3) 기본값 옵션 추가\n  - `getMeal`, `getCalendar` 옵션 호출방식 추가\n- `2.1.2`\n  - [Issue #1](https://github.com/leegeunhyeok/school-kr/issues/1) 경북 교육청 접속문제 수정\n  - 의존 라이브러리의 보안 취약성 업데이트\n- `2.1.1`\n  - 의존 라이브러리의 보안 취약성 업데이트\n- `2.1.0`\n  - 급식 / 학사일정 데이터를 불러올 때 년도와 월을 지정할 수 있도록 기능 추가\n  - 급식 / 학사일정 데이터에 년도 추가\n  - README에 개발 문서 추가 작성\n- `2.0.1`\n  - 의존 라이브러리의 보안 취약성 업데이트\n- `2.0.0`\n  - ※ 기존 버전과 `호환되지 않습니다.` (아래 변경사항을 확인 해주세요)\n  - Type, Region 프로퍼티 값을 Symbol 기반으로 구현\n    - Type, Region 접근 방식이 조금 변경 됨, [참고1](#학교-종류), [참고2](#교육청-관할-지역)\n  - 에러 발생 상황 추가 및 기존 에러 메시지 수정\n  - getNotice 메소드명 변경 -\u003e `getCalendar`\n  - getTargetURL 메소드 추가 (파싱할 타겟 URL을 반환합니다, [참고](#타겟-URL-조회))\n  - 예제 및 README 내용 수정사항에 맞게 업데이트 / 내용 추가\n  - 코드 주석 업데이트\n- `1.0.1`\n  - NPM 저장소와 이름 동일하게 Git 저장소 이름 변경 (이미 사용중인 이름)\n    - node-school -\u003e node-school-kr\n  - README 문서 내용 수정\n  - 에러 메시지 구분 문자 추가 (급식 파싱 에러인지 학사일정 파싱 에러인지 구분)\n- `1.0.0` - 첫 번째 릴리즈!\n\n## 라이센스\n\n[MIT](https://github.com/leegeunhyeok/school-kr/blob/master/LICENSE)\n\n## 정보\n\n본 프로젝트는 [School API](https://github.com/agemor/school-api)를 참고하여 Node.js 환경에서 사용할 수 있도록 새로 포팅한 프로젝트입니다.  \n`3.0.0` 버전부터 완전히 새롭게 개발되어 성능 및 안정성이 크게 개선되었습니다.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fleegeunhyeok%2Fschool-kr","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fleegeunhyeok%2Fschool-kr","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fleegeunhyeok%2Fschool-kr/lists"}