시간표 데이터 API
NEIS 시간표 데이터 API를 통해 학년·반별 교시 및 과목 시간표를 조회할 수 있습니다.
엔드포인트
GET /v1/neis/timetables요청 파라미터
| 파라미터 | 타입 | 필수 여부 | 설명 | 예시 |
|---|---|---|---|---|
grade | Int | 필수 | 학년 (1 ~ 3) | 2 |
classNum | Int | 필수 | 반 (1 ~ 4) | 3 |
date | LocalDate | 선택 | 특정 날짜의 시간표 조회 (ISO 8601 형식) | 2025-12-15 |
fromDate | LocalDate | 선택 | 조회 시작 날짜 (ISO 8601 형식) | 2025-12-01 |
toDate | LocalDate | 선택 | 조회 종료 날짜 (ISO 8601 형식) | 2025-12-31 |
날짜 파라미터 사용 규칙:
date,fromDate,toDate중 하나 이상 반드시 지정해야 합니다.date: 특정 날짜의 시간표 데이터만 조회fromDate와toDate: 기간 범위 내의 시간표 데이터 조회date와fromDate/toDate는 동시에 사용할 수 없습니다.- 최대 조회 기간은 365일입니다.
응답 형식
모든 성공 응답은 다음과 같은 구조로 반환됩니다.
| 필드 | 타입 | 설명 | 예시 |
|---|---|---|---|
status | String | HTTP 상태 메시지 | OK |
code | Int | HTTP 상태 코드 | 200 |
message | String | 응답 메시지 | OK |
data | Object | 시간표 응답 객체 | - |
data 객체
| 필드 | 타입 | 설명 | 예시 |
|---|---|---|---|
timetables | Array | 시간표 데이터 목록 배열 | - |
timetables 배열
timetables 필드는 시간표 단건 데이터 객체의 배열이며, 각 객체는 다음 필드를 포함합니다.
| 필드 | 타입 | 설명 | 예시 |
|---|---|---|---|
timetableId | String | 시간표 ID | 7430310_20251215_2_3_1 |
schoolCode | String | 학교 코드 | 7430310 |
schoolName | String | 학교명 | 광주소프트웨어마이스터고등학교 |
officeCode | String | 시도교육청 코드 | G10 |
officeName | String | 시도교육청명 | 광주광역시교육청 |
timetableDate | LocalDate | 시간표 날짜 | 2025-12-15 |
academicYear | String | 학년도 | 2025 |
semester | String? | 학기 (없는 경우 null) | 1 |
grade | Int | 학년 | 2 |
classNum | Int | 반 | 3 |
period | Int | 교시 | 1 |
subject | String? | 과목명 (없는 경우 null) | 수학 |
요청 예시
# 특정 날짜 조회
curl -X GET "https://api.datagsm.com/v1/neis/timetables?grade=2&classNum=3&date=2025-12-15" \
-H "X-API-KEY: your-api-key-here"
# 기간 범위 조회
curl -X GET "https://api.datagsm.com/v1/neis/timetables?grade=2&classNum=3&fromDate=2025-12-01&toDate=2025-12-31" \
-H "X-API-KEY: your-api-key-here"응답 예시
{
"status": "OK",
"code": 200,
"message": "OK",
"data": {
"timetables": [
{
"timetableId": "7430310_20251215_2_3_1",
"schoolCode": "7430310",
"schoolName": "광주소프트웨어마이스터고등학교",
"officeCode": "G10",
"officeName": "광주광역시교육청",
"timetableDate": "2025-12-15",
"academicYear": "2025",
"semester": "2",
"grade": 2,
"classNum": 3,
"period": 1,
"subject": "수학"
},
{
"timetableId": "7430310_20251215_2_3_2",
"schoolCode": "7430310",
"schoolName": "광주소프트웨어마이스터고등학교",
"officeCode": "G10",
"officeName": "광주광역시교육청",
"timetableDate": "2025-12-15",
"academicYear": "2025",
"semester": "2",
"grade": 2,
"classNum": 3,
"period": 2,
"subject": "영어"
}
]
}
}오류 응답
| 상태 코드 | 설명 |
|---|---|
401 Unauthorized | API 키가 유효하지 않거나 만료됨 |
403 Forbidden | 권한 범위 부족 |
429 Too Many Requests | 단위 시간에 너무 많은 요청량 발생 |
400 Bad Request | 잘못된 요청 파라미터 |
사용 예제
다음은 여러 언어에서 시간표 데이터를 조회하는 예제입니다.
const axios = require('axios');
async function getTimetables(grade, classNum, date) {
try {
const response = await axios.get('https://api.datagsm.com/v1/neis/timetables', {
headers: {
'X-API-KEY': 'your-api-key-here',
},
params: {
grade: grade,
classNum: classNum,
date: date,
},
});
return response.data;
} catch (error) {
console.error('Error:', error.message);
throw error;
}
}import requests
def get_timetables(grade, class_num, date):
try:
response = requests.get(
'https://api.datagsm.com/v1/neis/timetables',
headers={'X-API-KEY': 'your-api-key-here'},
params={'grade': grade, 'classNum': class_num, 'date': date}
)
response.raise_for_status()
return response.json()
except requests.exceptions.RequestException as e:
print(f'Error: {e}')
raiseimport java.net.http.*;
import java.net.URI;
public class NeisAPI {
public static String getTimetables(int grade, int classNum, String date) throws Exception {
HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create(
"https://api.datagsm.com/v1/neis/timetables?grade=" + grade +
"&classNum=" + classNum + "&date=" + date
))
.header("X-API-KEY", "your-api-key-here")
.GET()
.build();
HttpResponse<String> response = client.send(request,
HttpResponse.BodyHandlers.ofString());
return response.body();
}
}import java.net.http.HttpClient
import java.net.http.HttpRequest
import java.net.http.HttpResponse
import java.net.URI
fun getTimetables(grade: Int, classNum: Int, date: String): String {
val client = HttpClient.newHttpClient()
val request = HttpRequest.newBuilder()
.uri(URI.create(
"https://api.datagsm.com/v1/neis/timetables?grade=${grade}&classNum=${classNum}&date=${date}"
))
.header("X-API-KEY", "your-api-key-here")
.GET()
.build()
val response = client.send(request, HttpResponse.BodyHandlers.ofString())
return response.body()
}