공통과 역 정보¶
각 반환 타입은 모델 레퍼런스에 있습니다. timestamp_ms를 받는 조회는 생략 시 현재 Unix epoch 밀리초를 사용합니다. 명시한 값은 문자열로 전송하며 범위나 달력 의미를 추가 검사하지 않습니다.
get_service_status¶
반환값 · ServiceStatusResponse
서비스 운영 상태를 조회합니다. 선택 인자 timestamp_ms는 캐시 요청 시각입니다. 결과는 h_msg_cd, h_msg_txt, str_result와 raw를 담습니다. 개별 열차의 가용 여부를 확인하는 메서드는 아닙니다.
get_app_data¶
반환값 · AppDataResponse
앱 메인 캐시의 버전·공지 정보를 조회합니다. version은 AppVersionInfo, notice는 NoticeResponse이며 해당 객체가 없으면 None입니다. 기타 선택 필드와 전체 원문도 보존합니다. 캐시를 로컬에 쓰거나 앱을 업데이트하지 않습니다.
get_common_codes¶
반환값 · BaseKorailResponse
공통 코드와 설정을 조회합니다. Sequence는 문자열 목록·tuple 등을 뜻하며 bytes나 문자열이 아닌 항목은 거절합니다. 여러 항목은 같은 code 키를 반복해 순서와 중복을 유지합니다. 빈 목록은 코드 필드를 보내지 않습니다. 기본 빈 문자열은 빈 코드 값으로 전송되며, 성공을 확인한 조건은 아래의 명시적 두 코드입니다.
코드별 데이터는 raw에서 읽습니다. 실서버 관측은 app.limousine.stationNm과 app.limousine.stationCd였으며 다른 코드의 응답 형태를 보장하지 않습니다. 사용 예제를 참고하세요.
get_uuid¶
반환값 · UuidResponse
서버 발급 단말 검증값을 조회합니다. 인자는 없고 비어 있지 않은 verification_code를 반환합니다. 필수 값이 누락되거나 비어 있으면 KorailProtocolError가 발생합니다. 검증값을 저장하거나 다른 요청의 인증 값으로 자동 사용하지 않습니다. repr()에는 숨기지만 원문은 필드와 raw에 있으므로 그대로 로그에 남기지 마세요.
list_crew_request_reasons¶
KorailClient.list_crew_request_reasons(*, timestamp_ms: int | None = None) -> CrewRequestListResponse
반환값 · CrewRequestListResponse
승무원 호출 화면의 요청 사유 선택지를 조회합니다. timestamp_ms는 키워드 인자입니다. items는 CrewRequestOption tuple이며 message_code와 content를 제공합니다. 실제 호출 요청은 전송하지 않습니다.
list_stations¶
반환값 · StationDataResponse
전체 역 목록을 한 번에 받습니다. stations의 각 KorailStation은 code, name, 선택적인 좌표와 안내 정보를 담습니다. 좌표는 문자열이며 지도 좌표로 자동 변환하지 않습니다. 서버가 역 코드·이름을 생략하면 빈 문자열로 읽고, 목록 구조가 잘못되면 KorailProtocolError가 발생합니다.
get_station_list_version¶
반환값 · StationInfoResponse
역 데이터의 판본 map_version과 수록 역 수 count를 조회합니다. 서버가 정수로 준 값도 문자열로 읽으며 두 키는 필수입니다. 이 값으로 list_stations()의 저장·갱신 여부를 호출자가 결정할 수 있습니다. SDK는 자동 캐시를 유지하지 않습니다.
get_train_calendar¶
반환값 · TrainCalendarResponse
운행일 달력을 조회합니다. days는 TrainCalendarDay tuple이며 run_date와 휴일·판매일·운행 구분 등의 원래 코드 값을 보존합니다. 서버가 목록을 생략하면 빈 tuple일 수 있습니다. 특정 열차의 실제 운행이나 좌석 확보를 보장하는 데이터는 아닙니다.
close¶
HTTP 연결 풀을 닫습니다. 추가 서버 요청은 없으며 여러 번 호출할 수 있습니다. 닫힌 클라이언트로 다시 조회하면 KorailProtocolError가 발생합니다. 일반적으로 with KorailClient() as client:를 사용하면 별도 호출 없이 정리됩니다.