py12306 0.1.0

China Railway (12306) API client for querying stations, trains, tickets, and transfers

py12306

Python client for China Railway (12306) — query stations, trains, tickets, and transfers.

Install

pip install py12306

CLI

# Ticket search
uvx py12306 tickets --date 2026-01-25 --from 北京南 --to 上海虹桥 \
    --trains G --sort duration --limit 5

# Transfer search
uvx py12306 transfers --date 2026-01-25 --from 成都 --to 杭州 \
    --trains G --limit 3

# Train stops
uvx py12306 stops G1 --date 2026-01-25

# Station lookup
uvx py12306 stations 北京

Options

tickets

Option	Description
--date	Travel date (YYYY-MM-DD)
--from/--to	Station or city name
--trains	Filter: G/D/C/Z/T/K
--depart-after/--depart-before	Hour range (0-23)
--sort	depart, arrive, duration
--limit	Max results

transfers

Option	Description
--date	Travel date (YYYY-MM-DD)
--from/--to	Station or city name
--via	Transfer station (optional, auto-detected)
--trains	Filter: G/D/C/Z/T/K
--min-wait/--max-wait	Transfer time in minutes
--sort	duration, depart, arrive
--limit	Max results

Python API

from py12306 import (
    load_stations,
    get_station_by_name,
    get_stations_in_city,
    get_train_stops,
    get_tickets,
    get_transfers,
)

# Station lookup
station = get_station_by_name("北京南")
stations = get_stations_in_city("北京")

# Train stops
train = get_train_stops(train="G1", date="2026-01-25")
for stop in train.stops:
    print(f"{stop.station} {stop.arrive}-{stop.depart}")

# Tickets
tickets = get_tickets(
    date="2026-01-25",
    src="VNP",
    dst="AOH",
    trains="G",
    sort="duration",
    limit=5,
)

# Transfers
transfers = get_transfers(
    date="2026-01-25",
    src="ICW",
    dst="HGH",
    trains="G",
    limit=5,
)

Train Types

Code	Type
G	高铁 (High-speed, 300-350 km/h)
D	动车 (EMU, 200-250 km/h)
C	城际 (Intercity)
Z	直达 (Direct express)
T	特快 (Express)
K	快速 (Fast)

License

MIT