API 문서

오늘시간표 Open API는 학교 홈페이지의 가정통신문과 급식 사진을 REST + JSON으로 제공합니다. 이 문서 하나면 연동에 필요한 모든 내용을 확인할 수 있습니다.

개요

Base URL

https://api.onultime.com

인증

모든 데이터 엔드포인트는 API 키가 필요합니다. 키는 키 발급 페이지에서 카카오 로그인으로만 발급됩니다 (카카오 계정당 1개, 3초 소요).

발급받은 키를 X-API-Key 헤더로 보내세요. 헤더를 쓸 수 없는 환경이면 ?key= 쿼리 파라미터도 지원합니다.

curl "$BASE/v1/notices?officeCode=J10&schoolCode=7611009" \
  -H "X-API-Key: YOUR_KEY"

호출 한도

항목기본값
일일 호출 한도키당 1,000회 (한국 시간 자정 리셋)
한도 초과 시429 Too Many Requests

더 큰 한도가 필요하면 이메일로 사용 목적과 함께 문의해주세요.

학교 코드 찾기

학교는 NEIS 표준 코드 2개로 식별합니다.

파라미터NEIS 필드예시
officeCodeATPT_OFCDC_SC_CODE (시도교육청코드)경기 J10, 서울 B10
schoolCodeSD_SCHUL_CODE (행정표준코드)7611009 (초지중학교)

학교명으로 schoolCode를 찾으려면 NEIS 학교기본정보 API를 사용하세요 (키 없이 테스트 가능). 결과의 SD_SCHUL_CODE가 학교 코드입니다:

curl "https://open.neis.go.kr/hub/schoolInfo?SCHUL_NM=초지중학교&Type=json"

시도교육청코드(officeCode) 표

📥 시도교육청코드.xlsx 다운로드 — 전국 17개 시도교육청코드 목록

officeCode시도교육청officeCode시도교육청
B10서울J10경기
C10부산K10강원
D10대구M10충북
E10인천N10충남
F10광주P10전북
G10대전Q10전남
H10울산R10경북
I10세종S10경남
T10제주

GET/v1/notices

학교의 가정통신문·공지사항 목록을 작성자와 첨부파일 포함으로 가져옵니다.

쿼리 파라미터

이름타입설명
officeCode 필수string시도교육청코드
schoolCode 필수string행정표준코드
page 선택number페이지 번호. 기본 1, 최대 10

응답

{
  "school": {
    "officeCode": "J10",
    "schoolCode": "7611009",
    "homepage": "https://choji-m.goeas.kr"
  },
  "page": 1,
  "notices": [
    {
      "title": "2026. 7. 21.(화) 방학식 일과 안내 가정통신문",
      "date": "2026.07.13",
      "writer": "최지혜",
      "boardName": "가정통신문",
      "nttSn": "1521211",
      "detailUrl": "https://choji-m.goeas.kr/choji-m/na/ntt/selectNttInfo.do?mi=2412&bbsId=5802&nttSn=1521211",
      "files": [
        {
          "name": "방학식 일과 안내.hwp",
          "url": "https://choji-m.goeas.kr/upload/…/xxxx.hwp"
        }
      ]
    }
  ]
}
필드설명
title게시글 제목 (새글·공지 등 뱃지 텍스트 제거됨)
date등록일 YYYY.MM.DD
writer작성자. 게시판이 노출하지 않으면 빈 문자열
boardName가정통신문 · 공지사항 · 알림
nttSn게시글 고유 번호 (중복 제거용 키로 사용 권장)
detailUrl원문 페이지 URL. /v1/notices/detail에 그대로 전달
files첨부파일 배열 {name, url}

GET/v1/notices/detail

가정통신문 1건의 본문 텍스트·첨부파일·본문 이미지를 가져옵니다.

쿼리 파라미터

이름타입설명
detailUrl 필수string/v1/notices 응답의 detailUrl. URL 인코딩 필요
curl -G "$BASE/v1/notices/detail" \
  --data-urlencode "detailUrl=https://choji-m.goeas.kr/choji-m/na/ntt/selectNttInfo.do?mi=2412&bbsId=5802&nttSn=1521211" \
  -H "X-API-Key: YOUR_KEY"

응답

{
  "content": "학부모님 안녕하십니까 … (최대 2,000자)",
  "files": [ { "name": "방학식 일과 안내.hwp", "url": "https://…" } ],
  "images": [ "https://…/dext5editordata/…/img.png" ]
}
본문이 첨부파일(hwp·pdf)에만 있는 게시글은 content가 빈 문자열일 수 있습니다. 이 경우 files의 파일을 안내하세요.

GET/v1/meals/photos

해당 날짜의 실제 급식 사진(영양사님이 학교 홈페이지에 올린 사진)과 메뉴를 가져옵니다.

쿼리 파라미터

이름타입설명
officeCode 필수string시도교육청코드
schoolCode 필수string행정표준코드
date 필수string날짜 YYYY-MM-DD

응답

{
  "school": { "officeCode": "J10", "schoolCode": "7611009", "homepage": "https://choji-m.goeas.kr" },
  "date": "2026-07-17",
  "photos": [
    {
      "imageUrl": "https://choji-m.goeas.kr/upload/common/fm/images/…/img.jpg",
      "menuSummary": "찹쌀밥 \n육개장 \n도토리묵야채무침 \n돈육동그랑땡/케찹 \n깍두기",
      "calorie": "812 kcal"
    }
  ]
}
사진을 올리지 않는 학교·날짜는 photos가 빈 배열입니다. 급식 식단 텍스트가 필요하면 NEIS 급식식단정보 API를 함께 사용하세요.

에러 코드

모든 에러는 아래 형식으로 반환됩니다.

{ "error": { "code": "unauthenticated", "message": "유효하지 않은 API 키입니다." } }
HTTPcode의미
400invalid-argument파라미터 누락·형식 오류
401unauthenticatedAPI 키 없음 또는 무효
404not-found학교 홈페이지를 찾을 수 없음 / 없는 엔드포인트
429resource-exhausted일일 호출 한도 초과
500internal서버 내부 오류 (재시도 권장)

정책·제한사항

문의: syselec208@gmail.com · © 2026 오늘시간표