열차·공통 모델¶

열차 조회, 좌석, 역·달력 같은 공통 응답과 조회 입력입니다.

KorailSession ¶

KorailSession(
    jsessionid: str | None = None,
    member_no: str | None = None,
    raw: Mapping[str, object] = dict[str, object](),
    member_card_no: str | None = None,
    customer_no: str | None = None,
)

로그인 쿠키와 계정 식별자를 보관합니다.

고객번호(customer_no)와 회원번호(member_no)는 서로 다른 값입니다. raw와 repr은 개인정보를 가리지 않으므로 로그에 남기지 마세요.

BaseKorailResponse ¶

BaseKorailResponse(
    h_msg_cd: str | None = None,
    h_msg_txt: str | None = None,
    str_result: str | None = None,
    raw: Mapping[str, object] = dict[str, object](),
)

응답의 공통 상태·메시지와 원본을 담습니다.

str_result, h_msg_cd, h_msg_txt는 모든 응답에 공통인 봉투 필드이며, raw에는 서버가 보낸 응답이 그대로 남습니다.

from_raw ¶

from_raw(raw: object) -> Self

봉투 세 필드를 그대로 옮겨 담아 응답을 만듭니다.

성공·실패는 판정하지 않습니다. raw가 JSON 객체가 아니거나 봉투 필드가 문자열·정수·null이 아니면 KorailProtocolError가 발생합니다.

AppVersionInfo ¶

AppVersionInfo(
    message: str | None = None,
    new_version: str | None = None,
    store_url: str | None = None,
)

앱 버전과 업데이트 안내 주소를 담습니다.

store_url ¶

store_url: str | None = None

앱 업데이트 안내 주소(CNTAURL)입니다.

AppDataResponse ¶

AppDataResponse(
    h_msg_cd: str | None = None,
    h_msg_txt: str | None = None,
    str_result: str | None = None,
    raw: Mapping[str, object] = dict[str, object](),
    disability_certification_msg: str | None = None,
    railplus_cardinfo: str | None = None,
    version: AppVersionInfo | None = None,
    notice: NoticeResponse | None = None,
)

Bases: BaseKorailResponse

앱 메인 캐시의 버전·공지 정보를 담습니다.

NoticeResponse ¶

NoticeResponse(
    h_msg_cd: str | None = None,
    h_msg_txt: str | None = None,
    str_result: str | None = None,
    raw: Mapping[str, object] = dict[str, object](),
    board_id: str | None = None,
    post_sequence: str | None = None,
    post_title: str | None = None,
    post_content: str | None = None,
)

Bases: BaseKorailResponse

앱 메인 화면의 공지를 담습니다.

UuidResponse ¶

UuidResponse(
    h_msg_cd: str | None = None,
    h_msg_txt: str | None = None,
    str_result: str | None = None,
    raw: Mapping[str, object] = dict[str, object](),
    verification_code: str | None = None,
)

Bases: BaseKorailResponse

서버가 발급한 단말 검증값을 담습니다.

MaasMenuItem ¶

MaasMenuItem(
    active: str | None = None,
    additional_service_code: str | None = None,
    app_data: str | None = None,
    icon_off: str | None = None,
    icon_on: str | None = None,
    info: str | None = None,
    login_required: str | None = None,
    name: str | None = None,
    popup_image: str | None = None,
    menu_type: str | None = None,
    url: str | None = None,
    raw: Mapping[str, object] = dict[str, object](),
)

부가서비스 메뉴 한 항목과 역 선택 조건을 담습니다.

uses_station_selection ¶

uses_station_selection: bool

메뉴가 역 선택을 사용하는지 판정합니다.

active가 "Y"이고, menu_type이 "N"이 아니고, app_data가 비어 있지 않으면서 "N"도 아니고, additional_service_code가 있을 때 True입니다.

MaasMenuListResponse ¶

MaasMenuListResponse(
    h_msg_cd: str | None = None,
    h_msg_txt: str | None = None,
    str_result: str | None = None,
    raw: Mapping[str, object] = dict[str, object](),
    items: tuple[MaasMenuItem, ...] = (),
    departure_elevator_url: str | None = None,
    departure_navigation_url: str | None = None,
    departure_parking_url: str | None = None,
    arrival_elevator_url: str | None = None,
    arrival_bus_info_url: str | None = None,
    arrival_parking_url: str | None = None,
    arrival_baggage_transfer_robot_url: str | None = None,
)

Bases: BaseKorailResponse

부가서비스 메뉴 목록을 담습니다.

KorailStation ¶

KorailStation(
    code: str,
    name: str,
    longitude: str | None = None,
    latitude: str | None = None,
    raw: Mapping[str, object] = dict[str, object](),
    group: str | None = None,
    major: str | None = None,
    popup_type: str | None = None,
    popup_message: str | None = None,
    popup_link_title: str | None = None,
    popup_link_url: str | None = None,
    area: str | None = None,
    stop: str | None = None,
)

역 코드·이름과 역별 안내 정보를 담습니다.

popup_type ¶

popup_type: str | None = None

역 안내 팝업의 종류(popupType)입니다. 서버가 정수로 보내도 문자열로 담습니다.

StationDataResponse ¶

StationDataResponse(
    h_msg_cd: str | None = None,
    h_msg_txt: str | None = None,
    str_result: str | None = None,
    raw: Mapping[str, object] = dict[str, object](),
    stations: tuple[KorailStation, ...] = (),
)

Bases: BaseKorailResponse

전체 역 목록을 담습니다.

StationInfoResponse ¶

StationInfoResponse(
    h_msg_cd: str | None = None,
    h_msg_txt: str | None = None,
    str_result: str | None = None,
    raw: Mapping[str, object] = dict[str, object](),
    count: str = "",
    map_version: str | None = None,
)

Bases: BaseKorailResponse

역 데이터의 판본과 역 수를 담습니다.

count ¶

count: str = ''

역 수입니다. 정수로 바꾸지 않고 문자열로 담습니다.

TrainCalendarDay ¶

TrainCalendarDay(
    run_date: str | None = None,
    business_day_stage_code: str | None = None,
    day_division_code: str | None = None,
    holiday_division_code: str | None = None,
    sale_day_division_code: str | None = None,
    a_train_operation_flag: str | None = None,
    d_train_operation_flag: str | None = None,
    g_train_operation_flag: str | None = None,
    o_train_operation_flag: str | None = None,
    s_train_operation_flag: str | None = None,
    v_train_operation_flag: str | None = None,
    x_train_operation_flag: str | None = None,
    raw: Mapping[str, object] = dict[str, object](),
)

열차 운행일 한 날짜와 예매 조건을 담습니다.

TrainCalendarResponse ¶

TrainCalendarResponse(
    h_msg_cd: str | None = None,
    h_msg_txt: str | None = None,
    str_result: str | None = None,
    raw: Mapping[str, object] = dict[str, object](),
    days: tuple[TrainCalendarDay, ...] = (),
)

Bases: BaseKorailResponse

예매 가능한 운행일 달력을 담습니다.

TrainScheduleStop ¶

TrainScheduleStop(
    station_code: str | None = None,
    station_name: str | None = None,
    station_construction_order: str | None = None,
    run_order: str | None = None,
    actual_arrival_delay_count: str | None = None,
    actual_arrival_date: str | None = None,
    actual_arrival_time: str | None = None,
    actual_departure_date: str | None = None,
    actual_departure_time: str | None = None,
    planned_arrival_date: str | None = None,
    planned_arrival_time: str | None = None,
    planned_departure_date: str | None = None,
    planned_departure_time: str | None = None,
    delay_fare_return_division_code: str | None = None,
    delay_fare_return_division_name: str | None = None,
    solo_operation_delay_flag: str | None = None,
    detour_driver_delay_count: str | None = None,
    expected_arrival_delay_count: str | None = None,
    expected_departure_delay_count: str | None = None,
    regular_flag: str | None = None,
    service_flag: str | None = None,
    raw: Mapping[str, object] = dict[str, object](),
)

열차의 정차역 한 곳과 도착·출발 정보를 담습니다.

TrainScheduleResponse ¶

TrainScheduleResponse(
    h_msg_cd: str | None = None,
    h_msg_txt: str | None = None,
    str_result: str | None = None,
    raw: Mapping[str, object] = dict[str, object](),
    delay_detail_reason_content: str | None = None,
    stops: tuple[TrainScheduleStop, ...] = (),
    delay_station_construction_order: str | None = None,
    integrated_message_code: str | None = None,
    message_code: str | None = None,
    message_content: str | None = None,
    message_text: str | None = None,
    origin_station_code: str | None = None,
    origin_station_name: str | None = None,
    route_code: str | None = None,
    route_name: str | None = None,
    run_date: str | None = None,
    run_segment_order: str | None = None,
    regular_sale_flag: str | None = None,
    standard_train_class_code: str | None = None,
    terminal_station_code: str | None = None,
    terminal_station_name: str | None = None,
    train_attribute_code: str | None = None,
    train_departure_flag: str | None = None,
    train_no: str | None = None,
    special_train_flag: str | None = None,
    up_down_division_code: str | None = None,
)

Bases: BaseKorailResponse

열차 한 편의 정차역 목록을 담습니다.

TransferStation ¶

TransferStation(
    station_code: str | None = None,
    station_name: str | None = None,
    raw: Mapping[str, object] = dict[str, object](),
)

환승 가능한 역 한 곳을 나타냅니다.

TransferStationListResponse ¶

TransferStationListResponse(
    h_msg_cd: str | None = None,
    h_msg_txt: str | None = None,
    str_result: str | None = None,
    raw: Mapping[str, object] = dict[str, object](),
    stations: tuple[TransferStation, ...] = (),
)

Bases: BaseKorailResponse

환승 가능한 역 목록을 담습니다.

TrainSearchQuery ¶

TrainSearchQuery(
    departure_station_code: str,
    arrival_station_code: str,
    departure_date: str,
    departure_time: str = "000000",
    passengers: int = 1,
    train_group_code: str = "109",
    include_srt: bool = False,
    child_passengers: int = 0,
    senior_passengers: int = 0,
    high_disability_passengers: int = 0,
    low_disability_passengers: int = 0,
    seat_attribute_code: str = "015",
    connection_station_codes: tuple[str, ...] = (),
    connection_train_group_code: str | None = None,
    query_division_code: str = "1",
    teenager_passengers: int = 0,
    infant_passengers: int = 0,
    guide_dog_passengers: int = 0,
    include_nearby_stations: bool = False,
)

직통·환승 열차의 조회 조건을 구성합니다.

출발역·도착역에 숫자로만 된 역 코드를 넣으면 클라이언트가 역 목록을 조회해 역 이름으로 바꿔 보내고, 그 밖의 값은 역 이름으로 보고 그대로 보냅니다. 앱이 쓰는 열차군·조회 구분 코드는 앱 내부 값이 공개돼 있지 않아 확인하지 못했습니다. 기본값과 다른 값이 필요하면 train_group_code와 query_division_code를 직접 지정하세요.

query_division_code ¶

query_division_code: str = '1'

조회 구분 코드(qryDvCd)입니다. 앱의 정렬 선택별 값은 앱 내부 값이 공개돼 있지 않아 확인하지 못했으므로, 다른 값이 필요하면 직접 지정하세요.

teenager_passengers ¶

teenager_passengers: int = 0

청소년 승객 수입니다. 앱처럼 청소년·안내견은 어른 칸(txtPsgFlg_1)에, 유아는 어린이 칸(txtPsgFlg_2)에 더해 보냅니다.

include_nearby_stations ¶

include_nearby_stations: bool = False

인접역을 포함해 조회합니다. 기본값은 기존 요청과 같은 False입니다.

TrainSummary ¶

TrainSummary(
    train_no: str,
    train_group_code: str | None = None,
    departure_station_code: str | None = None,
    arrival_station_code: str | None = None,
    departure_date: str | None = None,
    departure_time: str | None = None,
    arrival_time: str | None = None,
    raw: Mapping[str, object] = dict[str, object](),
    departure_station_name: str | None = None,
    arrival_station_name: str | None = None,
    run_date: str | None = None,
    train_class_code: str | None = None,
    departure_run_order: str | None = None,
    arrival_run_order: str | None = None,
    seat_map_flag: str | None = None,
    general_reservation_code: str | None = None,
    general_reservation_flag: str | None = None,
    departure_construction_order: str | None = None,
    arrival_construction_order: str | None = None,
    seat_attribute_code: str | None = None,
    car_type_code: str | None = None,
    car_type_name: str | None = None,
    train_class_name: str | None = None,
    train_group_name: str | None = None,
    general_room_class_name: str | None = None,
    special_room_class_name: str | None = None,
    secondary_general_reservation_code: str | None = None,
    special_reservation_code: str | None = None,
    special_reservation_flag: str | None = None,
    secondary_special_reservation_code: str | None = None,
    free_reservation_code: str | None = None,
    free_reservation_flag: str | None = None,
    standing_reservation_code: str | None = None,
    standing_reservation_flag: str | None = None,
    reservation_available_flag: str | None = None,
    general_availability_name: str | None = None,
    special_availability_name: str | None = None,
    wait_reservation_flag: str | None = None,
    standard_remaining_seat_count: str | None = None,
    first_class_remaining_seat_count: str | None = None,
    free_remaining_seat_count: str | None = None,
    standing_remaining_seat_count: str | None = None,
    free_car_count: str | None = None,
    reservation_wait_passenger_count: str | None = None,
    total_passenger_count: int | None = None,
    goods_no: str | None = None,
    train_sequence: str | None = None,
    change_train_sequence: str | None = None,
    change_train_division_code: str | None = None,
    merge_seat_application_flag: str | None = None,
    train_suspension_flag: str | None = None,
    general_fare_text: str | None = None,
    special_fare_text: str | None = None,
    standing_availability_name: str | None = None,
    free_availability_name: str | None = None,
    arrival_date: str | None = None,
)

열차 한 편의 식별자·예약 상태·운임 표시를 담습니다.

좌석 예약 상태(general_reservation_code 등)와 운임 문구(general_fare_text, special_fare_text)는 서로 다른 필드입니다.

train_sequence ¶

train_sequence: str | None = None

열차 순번(h_trn_seq)입니다. 앱은 환승 조회 결과에서 이 값이 같은 두 행을 한 여정으로 묶습니다.

change_train_sequence ¶

change_train_sequence: str | None = None

환승 여정 안에서 이 열차 구간의 순서(h_chg_trn_seq)입니다. train_sequence와는 다른 값입니다.

change_train_division_code ¶

change_train_division_code: str | None = None

직통·환승 구분 코드(h_chg_trn_dv_cd)입니다.

merge_seat_application_flag ¶

merge_seat_application_flag: str | None = None

병합 좌석 적용 플래그(h_yms_apl_flg)입니다. 앱은 이 값으로 병합 좌석 여부를 판정합니다.

from_raw ¶

from_raw(raw: Mapping[str, object]) -> Self

검색 응답의 행 하나를 TrainSummary로 만듭니다.

주요 값은 h_ 접두 철자와 접두 없는 철자를 둘 다 찾습니다(h_trn_no와 trnNo 등). 정수로 온 값은 문자열로 바꾸고, 선택 필드에 문자열·정수가 아닌 값이 오면 None이 됩니다. train_no에 문자열·정수·null이 아닌 값이 오면 KorailProtocolError가 발생합니다.

ReservationPassengerInfo ¶

ReservationPassengerInfo(
    passenger_type_code: str | None = None,
    passenger_count: str | None = None,
    discount_kind_code: str | None = None,
    discount_kind_code_2: str | None = None,
    discount_proof_no: str | None = None,
    discount_proof_no_2: str | None = None,
    delay_original_window_no: str | None = None,
    delay_original_sale_date: str | None = None,
    delay_original_sale_sequence: str | None = None,
    delay_original_return_password: str | None = None,
    raw: Mapping[str, object] = dict[str, object](),
)

예약 응답의 승객 유형별 인원과 할인 정보를 담습니다.

SeatAttribute ¶

SeatAttribute(name: str, code: str | None = None)

좌석 속성 코드와 표시 이름을 담습니다.

SeatCar ¶

SeatCar(
    car_no: int | None,
    room_class_name: str,
    remaining_seat_count: int | None,
    attributes: tuple[SeatAttribute, ...],
    room_class_code: str | None = None,
    total_seat_count: int | None = None,
)

좌석 조회에 사용할 호차 번호와 좌석 속성을 담습니다.

car_no ¶

car_no: int | None

호차 번호입니다. 응답에 없거나 빈 문자열이면 None입니다.

remaining_seat_count ¶

remaining_seat_count: int | None

잔여 좌석 수입니다. 응답에 없거나 빈 문자열이면 None입니다.

SeatCarListResponse ¶

SeatCarListResponse(
    h_msg_cd: str | None = None,
    h_msg_txt: str | None = None,
    str_result: str | None = None,
    raw: Mapping[str, object] = dict[str, object](),
    recommended_car_no: int | None = None,
    train_no: str | None = None,
    cars: tuple[SeatCar, ...] = (),
    train_class_code: str | None = None,
    train_group_code: str | None = None,
    car_count: str | None = None,
)

Bases: BaseKorailResponse

열차 한 편의 조회 가능한 호차 목록을 담습니다.

car_count ¶

car_count: str | None = None

호차 수(h_scar_num)입니다. 문자열로 담으며, 응답에 없거나 읽을 수 없으면 None입니다.

PhysicalSeat ¶

PhysicalSeat(
    seat_no: str,
    sale_possible: str,
    direction_code: str,
    other_attribute_code: str | None,
    requested_attribute_code: str,
    floor: str | None,
    specification: str,
    sequence_no: str,
    message_code: str,
    message: str,
    visual_message_division_code: str | None,
)

좌석표 한 자리의 식별자·표시·판매 가능 여부를 담습니다.

좌석 지정에는 표시용 specification이 아니라 식별자 seat_no를 쓰세요. sale_possible이 "Y"인 좌석은 KorailSeatAssignment.from_inventory로 좌석 지정 입력으로 바꿀 수 있습니다. floor는 앱이 읽지 않는 값이며 응답에 없으면 None입니다.

SeatWindow ¶

SeatWindow(
    start_location_ratio: float | None,
    close_location_ratio: float | None,
)

좌석 배치도의 창문 위치 비율을 담습니다.

비율이 응답에 없거나 빈 문자열이면 None입니다.

SeatInventoryResponse ¶

SeatInventoryResponse(
    h_msg_cd: str | None = None,
    h_msg_txt: str | None = None,
    str_result: str | None = None,
    raw: Mapping[str, object] = dict[str, object](),
    layout_type: str = "",
    arrangement_code: str = "",
    remaining_count: int | None = None,
    total_count: int | None = None,
    seats: tuple[PhysicalSeat, ...] = (),
    windows: tuple[SeatWindow, ...] = (),
    vr_banner_url: str | None = None,
    car_type_code: str | None = None,
    car_no: int | None = None,
    up_down_division_code: str | None = None,
)

Bases: BaseKorailResponse

한 호차의 좌석 재고와 창문 위치를 담습니다.

car_no가 없으면 KorailSeatAssignment.from_inventory를 쓸 수 없으므로 KorailSeatAssignment(car_no=..., seat_no=...)로 직접 만드세요.

layout_type ¶

layout_type: str = ''

좌석 배치 형식입니다. 서버가 정수로 보내도 문자열로 담으며, 응답에 없으면 빈 문자열입니다.

remaining_count ¶

remaining_count: int | None = None

잔여 좌석 수(seat_remain_count)입니다. 음이 아닌 정수로 읽을 수 없으면 None입니다.

total_count ¶

total_count: int | None = None

전체 좌석 수(seat_total_count)입니다. 음이 아닌 정수로 읽을 수 없으면 None입니다.

TrainSearchMetadata ¶

TrainSearchMetadata(
    job_id: str | None = None,
    menu_id: str | None = None,
    product_no: str | None = None,
    next_page_flag: str | None = None,
    next_query_station_no: str | None = None,
    next_train_no: str | None = None,
    next_preceding_train_no: str | None = None,
    next_connecting_train_no: str | None = None,
    result_count: str | None = None,
    notice_message: str | None = None,
    first_seat_count: str | None = None,
    second_seat_count: str | None = None,
    first_departure_time: str | None = None,
    raw: Mapping[str, object] = dict[str, object](),
    agreement_text: str | None = None,
    remaining_seat_count: str | None = None,
)

열차 조회 결과의 공통 조건과 페이지 커서를 담습니다.

next_page_flag가 "Y"여도 커서가 없으면 다음 페이지를 조회할 수 없습니다. 다음 조회에 넘길 값은 결과의 next_page로 만드세요.

next_preceding_train_no ¶

next_preceding_train_no: str | None = None

다음 환승 조회에 넘길 선행 열차 번호 커서입니다.

notice_message ¶

notice_message: str | None = None

검색 안내 문구(h_notice_msg)입니다. 앱은 값이 있으면 경고창으로 보여 줍니다.

TrainSearchContinuation ¶

TrainSearchContinuation(
    query_station_no: str,
    query_train_no: str,
    query_train_no2: str = "",
)

다음 열차 조회에 전달할 세 개의 커서 값을 담습니다.

보통 직접 만들지 않고 조회 결과의 next_page가 돌려주는 값을 씁니다. 세 값은 각각 qryStNo, qryStTrnNo, qryStTrnNo2로 보냅니다. query_station_no와 query_train_no는 비어 있지 않은 문자열이어야 하고 query_train_no2만 빈 문자열을 허용하며, 조건에 맞지 않으면 KorailProtocolError가 발생합니다.

TrainSearchResult ¶

TrainSearchResult(
    trains: list[TrainSummary],
    response: BaseKorailResponse,
    raw: Mapping[str, object] = dict[str, object](),
    metadata: TrainSearchMetadata = TrainSearchMetadata(),
)

직통 열차 조회 한 페이지와 후속 조회 정보를 담습니다.

예외 없이 반환돼도 trains가 비어 있을 수 있으므로 확인하세요.

next_page ¶

next_page() -> TrainSearchContinuation | None

다음 조회에 넘길 TrainSearchContinuation을 반환합니다.

next_page_flag가 "Y"이고 필수 커서가 모두 있을 때만 값을 돌려줍니다. trains가 비었거나 커서가 없으면 None입니다.

next_query_from_last_departure ¶

next_query_from_last_departure(
    query: TrainSearchQuery,
) -> TrainSearchQuery | None

query의 출발 날짜·시각을 마지막 열차의 출발 날짜·시각으로 바꾼 조회 조건을 만듭니다.

요청은 보내지 않습니다. trains가 비었거나 마지막 열차에 출발 날짜·시각이 없으면 None입니다.

TransferItinerary ¶

TransferItinerary(
    first: TrainSummary, second: TrainSummary
)

탑승 순서가 있는 두 구간의 환승 여정을 담습니다.

환승 조회 결과에서 train_sequence(h_trn_seq)가 같은 두 행을 응답에 나온 순서대로 묶은 것입니다. 구간 순서를 나타내는 change_train_sequence(h_chg_trn_seq)와는 다른 값입니다.

legs ¶

legs: tuple[TrainSummary, ...]

두 열차 구간을 탑승 순서대로 반환합니다.

transfer_station_code ¶

transfer_station_code: str | None

첫 구간 도착역과 다음 구간 출발역이 같을 때만 그 역 코드를 반환합니다.

다르면 None이므로 두 구간의 역을 직접 확인하세요.

transfer_station_name ¶

transfer_station_name: str | None

두 구간이 연결되는 환승역 이름을 반환합니다.

첫 구간 도착역 이름과 다음 구간 출발역 이름이 같을 때만 그 이름을 반환하고, 다르면 None입니다.

TransferSearchResult ¶

TransferSearchResult(
    itineraries: list[TransferItinerary],
    trains: list[TrainSummary],
    response: BaseKorailResponse,
    raw: Mapping[str, object] = dict[str, object](),
    metadata: TrainSearchMetadata = TrainSearchMetadata(),
)

환승 조회의 전체 열차 행과 두 구간으로 묶은 여정을 담습니다.

next_page ¶

next_page() -> TrainSearchContinuation | None

다음 조회에 넘길 TrainSearchContinuation을 반환합니다.

next_page_flag가 "Y"이고 커서가 있을 때만 값을 돌려줍니다. 환승 커서(next_preceding_train_no, next_connecting_train_no)가 둘 다 있으면 그 값을 쓰고, 하나라도 없으면 직통 커서(next_train_no)를 씁니다. trains가 비었거나 커서가 없으면 None입니다.