pykorail 0.4.0

서버는 조회 한 번에 한 쪽(보통 열 편)만 줍니다. max_pages 를 올리면 마지막 열차의 출발 시각부터 다시 조회해 이어 붙입니다.

trains = korail.trains.search("서울", "부산", include_no_seats=True, max_pages=5)
print(len(trains), trains[-1].dep_time)

쪽마다 요청이 한 번씩 더 나갑니다. 새 열차가 더 없으면 그 전에 멈춥니다.

trains = korail.trains.search("서울", "부산", include_waiting_list=True)
waitable = [t for t in trains if not t.has_seat() and t.has_waiting_list()]

reservation = korail.reservations.create(waitable[0])
assert reservation.is_waiting

앱의 "인접역" 옵션입니다. 용산 → 대전을 찾으면 서울 → 대전 · 용산 → 서대전 편도 함께 나옵니다. 직통이 없는 구간은 이걸 켜지 않으면 조회할 방법이 없습니다.

trains = korail.trains.search("용산", "대전", include_nearby_stations=True)

for train in trains:
    print(train.dep_name, "→", train.arr_name)
# 서울 → 대전 / 용산 → 서대전 / 서울 → 서대전 …

# 출발은 용산에서만 하고 싶다면 결과에서 고르면 됩니다
from_yongsan = [t for t in trains if t.dep_name == "용산"]

결과가 더해지는 것이 아니라 후보가 넓어지는 것이라, 켜면 인근역 편이 시간순으로 끼어들며 뒤쪽 직통편을 밀어낼 수 있습니다. 그래서 기본값은 꺼짐입니다.

직통이 없는 구간은 한 번 갈아타는 여정으로 찾습니다. 조회는 로그인하지 않아도 됩니다.

transfers = korail.trains.search_transfers("강릉", "목포")

for transfer in transfers:
    first, second = transfer.legs
    print(first.train_no, "→", transfer.station_name, "→", second.train_no)

first, second = korail.reservations.create_transfer(transfers[0])

print(first.rsv_id == second.rsv_id)  # True — 예약번호는 하나입니다

구간을 따로 create() 하면 첫 구간만 잡히고 둘째가 매진될 수 있습니다. 이쪽은 한 구간이라도 안 되면 서버가 통째로 거절하고, cancel() 은 예약번호 단위라 둘 중 어느 것을 넘겨도 두 구간이 함께 취소됩니다.

예약하기 전에 값을 봅니다. 로그인하지 않아도 됩니다.

train = korail.trains.search("서울", "부산")[0]

for fare in korail.trains.fares(train):
    print(fare.seat_class_name, fare.total)
# 일반실 59800
# 특실 83700

할인 전의 기준 운임입니다. 실제로 낼 금액은 예약한 뒤 Reservation.price 에 있습니다.

create() 는 좌석을 서버가 정합니다. 자리를 직접 고르려면 호차 목록 다음에 좌석 배치를 받아 create_with_seats() 에 넘깁니다. 둘 다 로그인이 필요합니다.

from pykorail import AdultPassenger

train = korail.trains.search("서울", "부산")[0]

# 좌석은 승객 한 명에 하나씩이라, 두 자리가 남은 호차를 고릅니다.
car = next(car for car in korail.trains.cars(train) if car.remaining_seats >= 2)
picked = [seat for seat in korail.trains.seats(train, car) if seat.is_available][:2]

reservation = korail.reservations.create_with_seats(train, picked, [AdultPassenger(2)])

좌석 수가 승객 수와 다르거나, 같은 좌석을 두 번 넘기거나, 객실이 섞이면 요청 전에 ValueError 로 막습니다.

for reservation in korail.reservations.all():
    print(reservation.train.dep_name, "→", reservation.train.arr_name, reservation.price)

for ticket in korail.tickets.all():
    print(ticket.ticket_no, ticket.car_no, ticket.seat_no)
    korail.tickets.refund(ticket)  # 환불

로그인 없이 됩니다. 코레일이 파는 것은 광명역 → 인천공항(T1 · T2) 방향뿐입니다.

buses = korail.airport_bus.search("광명역", "인천공항T1")
bus = next(bus for bus in buses if bus.has_seat())

print(bus, bus.price)
print([seat.seat_no for seat in korail.airport_bus.seats(bus) if seat.is_available])

mileage = korail.membership.mileage()
print(mileage.total, "마일리지,", mileage.expiring, "이번 달 소멸 예정")

for entry in mileage.entries:  # 최근 30일의 적립 · 사용 내역
    print(entry.date, entry.movement, entry.amount)  # 20261003 적립 2990

for coupon in korail.membership.coupons():
    print(coupon.title, coupon.valid_until)

프로파일마다 합성 Android ID가 하나 생성되며, 같은 프로파일을 쓰는 클라이언트는 그 ID를 재사용합니다. 재시작 후에도 유지하려면 id와 android_id를 함께 저장하세요. pykorail은 파일을 자동으로 읽거나 쓰지 않습니다.

from pykorail.device import profile_by_id, random_profile

profile = profile_by_id(saved_id, android_id=saved_android_id) or random_profile()
# 호출 앱의 설정에 profile.id와 profile.android_id를 함께 저장합니다.
korail = Korail(device_profile=profile)

전체 프로파일을 저장하려면 dataclasses.asdict(profile)을 직렬화한 뒤 DeviceProfile(**saved_data)로 복원할 수도 있습니다. ID는 Android 14의 SSAID 계산 방식과 코레일 공개 서명 인증서로 생성한 합성 값이며, 실제 기기에서 추출한 값은 아닙니다. 프로파일을 생략하면 클라이언트마다 새 ID가 생성됩니다. 이때도 korail.android_id를 저장하고 Korail(android_id=saved_android_id)로 복원할 수 있습니다. 프로파일 유무와 무관하게 User-Agent는 korailtalk입니다.

설치할 때 경고가 떴다면 curl_cffi 대신 requests 로 돌고 있을 수 있습니다. 코레일은 TLS 지문을 보기 때문에 이때 로그인이 거부될 수 있습니다. pip install curl_cffi 로 해결되는 경우가 대부분입니다.

휴대폰 번호는 010-1234-5678과 01012345678 모두 입력할 수 있습니다. 클라이언트가 휴대폰 로그인으로 분류하고 하이픈을 제거해 전송합니다.

PasswordChangeRequiredError 가 난다면 아이디 · 비밀번호는 맞습니다. 같은 비밀번호를 6개월 넘게 써서 코레일이 변경 안내를 띄운 상태이고, 그동안은 로그인이 끝나지 않습니다. 코레일톡 앱이나 홈페이지에서 안내를 처리한 뒤 다시 실행하세요.

curl_cffi 의 libcurl DLL 로드가 실패하는 환경이 있습니다. pip install "pykorail[fallback]" 로 requests 폴백을 함께 설치하세요. 다만 위에 적은 이유로 로그인이 막힐 수 있습니다.

코레일이 서버를 바꿨을 수 있습니다. API 변경 이슈 로 알려주시면 대응하겠습니다. 가장 도움이 되는 기여입니다.

이 라이브러리는 앱과 같은 요청을 보낼 뿐이고, 좌석 배정은 코레일 서버가 합니다. 명절 예매처럼 경쟁이 심한 상황에서 성공을 보장하지 않습니다.

없고, 앞으로도 넣지 않습니다. 프록시로 출처를 바꿔 가며 요청하는 것은 코레일 서버를 속여 정상 이용자보다 유리하게 예매하려는 부정한 방법입니다.