korail-mobile-api 4.0.0

시작하기 · API 레퍼런스 · 요청 흐름 · 4.0으로 옮기기

열차 운행 스케줄, 역 정보와 공통 데이터를 조회하는 비공식 동기 Python 클라이언트입니다. 4.0.0은 로그인·DynaPath·NetFunnel 없이 사용하는 조회 기능 14개를 제공합니다. Python 3.11 이상이 필요하며 런타임 의존성은 HTTPX 하나입니다.

4.0은 3.x와 호환되지 않습니다. 인증·예약·결제 기능을 제거한 조회 전용 버전입니다. 기존 사용자는 마이그레이션 안내를 먼저 확인하세요.

설치

Python 3.11 이상이 필요합니다. 필수 런타임 의존성은 HTTPX 하나입니다.

python -m pip install --upgrade korail-mobile-api

이 문서와 같은 버전을 고정하려면 korail-mobile-api==4.0.0으로 설치하세요. 가상환경 설정과 소스 설치는 시작하기에 있습니다. 로그인 정보와 로컬 세션 파일은 필요하지 않습니다.

빠르게 써보기

열차 한 편의 운행 스케줄은 운행일과 열차번호로 조회합니다. 로그인 정보와 로컬 세션 파일은 필요하지 않습니다.

from datetime import datetime, timedelta, timezone

from korail_mobile_api import KorailClient

kst = timezone(timedelta(hours=9))
run_date = (datetime.now(kst) + timedelta(days=1)).strftime("%Y%m%d")
with KorailClient() as client:
    schedule = client.get_train_schedule(run_date, "00001")
    for stop in schedule.stops:
        print(stop.station_name, stop.arrival_time, stop.departure_time)

날짜와 열차번호는 실제 조회할 대상으로 바꾸세요. 예제를 실행하면 서버에 조회 요청을 보냅니다. 위 그림은 실행 화면의 구성을 보여 주는 합성 데이터입니다.

좌석배정용 열차 목록의 전체 입력 예제는 시작하기에 있습니다. 일반 search_trains와는 다른 조회 경로입니다. 전체 역 목록은 client.list_stations()로 받을 수 있습니다.

지원 기능

일반 직통·환승 열차 검색, 운임, 예약·취소, 발권·결제·환불, 계정·승차권, 체크인, 패스와 공항버스 운행·좌석 조회는 제공하지 않습니다. 관련 인증·세션·토큰·대기열 구현과 설정도 포함하지 않습니다.

요청 흐름

입력을 검사하고 지원 조회 경로에 한 번 요청한 뒤 응답을 dataclass로 읽습니다. 내부 규칙과 원문 보존 방식은 요청 흐름에 정리했습니다.

응답과 연결

• 응답은 타입이 지정된 dataclass이며 목록은 tuple로 반환합니다. 서버가 생략한 선택 필드는 None일 수 있습니다.
• with KorailClient() 또는 close()로 HTTP 연결을 정리합니다.
• 자동 페이지 순회·재시도·리다이렉트·자동 로그인은 없습니다. 쿠키와 환경변수 프록시도 사용하지 않습니다.
• HTTP 실패, 서버의 업무 오류, 잘못된 응답 형식은 각각 구분된 예외로 반환합니다.
• 응답과 예외의 raw는 자동 마스킹되지 않습니다. 단말 검증값을 포함한 원문을 그대로 로그에 남기지 마세요.

자주 묻는 질문

로그인 없이 일반 열차 검색도 가능한가요? 4.0은 운행 스케줄과 좌석배정용 목록만 제공합니다. 일반 직통·환승 검색은 제거했으며 두 조회를 같은 API로 취급하지 않습니다.

3.x를 쓰던 코드는 그대로 실행되나요? 지원 메서드 14개의 이름은 유지하지만 간편 API와 인증·거래 기능 및 관련 모델은 제거했습니다. 마이그레이션 안내를 확인하세요.

서버가 P058이나 MACRO ERROR를 반환하면요? KorailAppError에서 서버 코드와 메시지를 확인할 수 있습니다. 자동 로그인·대기열 처리·재시도는 수행하지 않습니다.

4.0의 실서버 성공을 확인한 건가요? 유지 범위의 근거는 3.0.0에서 세 기능을 모두 끈 관측입니다. 4.0 자체의 검증은 합성 응답을 이용한 오프라인 검사이며 확인 범위를 구분해 기록했습니다.

문서와 참여

4.0 API에 맞춘 배포 문서입니다.

• 설치와 사용 예제
• API 목록 · 설정 · 오류 처리
• 3.x에서 4.0으로 옮기기
• 검증 범위 · 변경 이력 · 개발과 검증

유지한 기능의 실서버 응답은 2026년 10월 25일, 3.0.0에서 로그인·DynaPath·NetFunnel을 모두 끈 조건으로 확인했습니다. 4.0.0 코드는 합성 응답과 네트워크 차단을 이용해 검사합니다. 이 둘은 검증 대상이 다르며 모든 날짜·입력의 성공을 보장하지 않습니다.

버그나 문서 개선은 이슈와 Pull Request로 참여해 주세요. 제보할 때는 원문 응답과 단말 검증값 대신 사용 버전·입력 조건·오류 코드를 정리해 주세요.

개발

개발과 검증에 로컬 검사와 문서 미리보기 명령이 있습니다. 동작 규칙, 오프라인 검사 기준, 에이전트 작업 가이드도 함께 확인하세요. 테스트에서는 실제 네트워크를 차단합니다.

라이선스와 서비스 이용

소스는 Apache License 2.0으로 제공합니다. 이 프로젝트는 KORAIL의 공식 서비스나 제휴 프로젝트가 아닙니다. 서버 응답 여부가 공식 이용 허가를 뜻하지 않으며, 소스 라이선스가 서버 데이터나 서비스 이용 권한을 부여하지는 않습니다. 자세한 내용은 프로젝트와 데이터 이용을 참고하세요.