나이스(NEIS) 학교 코드 가져오기, 직접 만든 npm 패키지 공개

학교 급식이나 학사일정 API를 만들려면 먼저 학교 코드가 필요하다. 그런데 기존에 학교 코드를 가져오는 주소가 리뉴얼되면서 공인인증서를 요구하고 있다.

그래서 많은 학교 급식 API들이 기존 DB를 사용하거나, Excel 혹은 노가다(?)로 학교 코드를 가져오고 있다. 그러던 중 유일하게 아직 안 막힌 곳을 찾아 파싱했다.

다운받아 쓰거나 수정하여 자기한테 맞게 쓰셔도 된다. 이왕이면 코드를 같이 발전시켜나갔으면 좋겠다.

• 깃허브: https://github.com/yousung/neis-school-list
• NPM: https://www.npmjs.com/package/neis-api

사용 방법

const neisApi = require("neis-api");

/**
 * 학교명을 입력하면 학교 리스트를 반환
 */

neisApi("고기").then(list => console.log(list));

학교명 일부만 넣어도 매칭되는 학교 목록이 나온다. 반환값에는 학교 코드, 시도교육청 코드, 학교 종류, 주소 등이 담긴다.

왜 학교 코드가 필요한가

나이스 급식·시간표·학사일정 API는 전부 두 개의 키를 요구한다.

• 시도교육청 코드 (ATPT_OFCDC_SC_CODE) — 서울, 경기 같은 지역 단위
• 표준학교 코드 (SD_SCHUL_CODE) — 학교 하나를 식별하는 7자리 코드

사용자가 "우리 아이 학교"를 고르게 하려면 학교명으로 이 두 코드를 찾아주는 검색 기능이 반드시 필요하다. 그런데 정작 그 검색을 위한 공식 경로가 막혀 있었던 것이다.

지금은 공식 API가 있다

이 글을 쓴 이후 상황이 바뀌었다. 나이스 교육정보 개방 포털에서 공식 오픈 API를 제공하기 시작했고, 여기에 학교 기본정보 조회가 포함돼 있다.

GET https://open.neis.go.kr/hub/schoolInfo
  ?KEY=인증키
  &Type=json
  &SCHUL_NM=고기초등학교

응답에서 필요한 값을 꺼내 쓰면 된다.

const res = await fetch(url);
const json = await res.json();
const rows = json.schoolInfo?.[1]?.row ?? [];

rows.forEach(s => {
  console.log(s.SCHUL_NM, s.ATPT_OFCDC_SC_CODE, s.SD_SCHUL_CODE);
});

인증키는 포털에서 회원가입 후 신청하면 발급된다. 인증키 없이도 하루 일정 횟수까지는 호출되지만, 서비스로 쓸 거라면 발급받는 게 맞다.

그래도 파싱 방식이 필요한 경우

• 인증키 발급 없이 빠르게 프로토타이핑할 때
• 공식 API 응답에 없는 정보가 필요할 때
• 호출 제한을 피하고 싶어 자체 DB로 한 번 말아둘 때

마지막이 실무적으로 유용하다. 학교 목록은 거의 바뀌지 않으므로, 한 번 전체를 받아 로컬 DB에 넣어두고 검색은 자체적으로 처리하는 편이 훨씬 빠르고 안정적이다.

스크래핑으로 만들 때 주의할 것

공식 API가 없어서 파싱해야 하는 상황이라면 몇 가지는 지키는 게 좋다.

• robots.txt와 이용약관을 확인한다. 명시적으로 금지된 곳은 피한다
• 요청 간격을 둔다. 짧은 시간에 대량 호출하면 상대 서버에 부담이 되고 IP가 차단된다
• User-Agent에 연락처를 넣는다. 문제가 생겼을 때 상대가 연락할 수 있게
• 결과를 캐싱한다. 같은 데이터를 반복해서 긁지 않는다
• 구조 변경에 대비한다. HTML 파싱은 상대가 화면을 바꾸는 순간 깨진다. 실패 시 알림을 받도록 해두면 좋다

무엇보다 공식 API가 생기면 그쪽으로 갈아타는 게 맞다. 이 패키지도 그런 경우다.

정리

• 학교 코드 조회 경로가 막혀서 남아 있는 곳을 파싱해 패키지로 공개했다
• npm i neis-api 로 설치, 학교명으로 목록 조회
• 지금은 나이스 교육정보 개방 포털 공식 API가 있으니 그쪽이 우선
• 학교 목록은 거의 안 바뀌므로 자체 DB에 캐싱하는 구조가 실용적이다
• 스크래핑은 요청 간격·캐싱·약관 확인이 기본