12306

12306 Train Query

Query train schedules and remaining tickets from China Railway 12306.

Query Tickets

node {baseDir}/scripts/query.mjs <from> <to> [options]

HTML mode (default): writes file, prints path to stdout
Markdown mode (-f md): prints table to stdout

Examples

# All trains from Beijing to Shanghai (defaults to today)
node {baseDir}/scripts/query.mjs 北京 上海

Markdown table output (to stdout, good for chat)

node {baseDir}/scripts/query.mjs 北京上海 -t G -f md

Morning departures, 2h max, with second class available

node {baseDir}/scripts/query.mjs 上海杭州 -t G --depart 06:00-12:00 --max-duration 1h --seat ze

Only bookable trains arriving before 6pm

node {baseDir}/scripts/query.mjs 深圳长沙 --available --arrive -18:00

Custom output path

node {baseDir}/scripts/query.mjs 广州武汉 -o /tmp/tickets.html

JSON output (to stdout)

node {baseDir}/scripts/query.mjs 广州武汉 --json


### Options

- `-d, --date <YYYY-MM-DD>`: Travel date (default: today)
- `-t, --type <G|D|Z|T|K>`: Filter train types (combinable, e.g. `GD`)
- `--depart <HH:MM-HH:MM>`: Depart time range (e.g. `08:00-12:00`, `18:00-`)
- `--arrive <HH:MM-HH:MM>`: Arrive time range (e.g. `-18:00`, `14:00-20:00`)
- `--max-duration <duration>`: Max travel time (e.g. `2h`, `90m`, `1h30m`)
- `--available`: Only show bookable trains
- `--seat <types>`: Only show trains with tickets for given seat types (comma-separated: `swz,zy,ze,rw,dw,yw,yz,wz`)
- `-f, --format <html|md>`: Output format — `html` (default, saves file) or `md` (markdown table to stdout)
- `-o, --output <path>`: Output file path, html mode only (default: `{baseDir}/data/<from>-<to>-<date>.html`)
- `--json`: Output raw JSON to stdout

### Output Columns

| Column | Meaning |
|--------|---------|
| 商务/特等 | Business class / Premium (swz) |
| 一等座 | First class (zy) |
| 二等座 | Second class (ze) |
| 软卧/动卧 | Soft sleeper / Bullet sleeper (rw/dw) |
| 硬卧 | Hard sleeper (yw) |
| 硬座 | Hard seat (yz) |
| 无座 | Standing (wz) |

Values: number = remaining seats, `有` = available (qty unknown), `—` = not applicable

## Station Lookup

```bash
node {baseDir}/scripts/stations.mjs 杭州
node {baseDir}/scripts/stations.mjs 香港西九龙

Important Notes for AI Assistant

⚠️ Station Name Resolution Warning

CRITICAL: When querying by city name (e.g., "武汉", "上海", "深圳", "广州"), the API may return trains from/to ANY station in that city, not just the main station.

Common Pitfalls:

武汉 includes: 武汉站 (main), 汉口站 (Hankou), 武昌站 (Wuchang), 武汉东站
上海 includes: 上海虹桥 (Hongqiao), 上海站 (main), 上海南站, 上海松江站
深圳 includes: 深圳北站 (main), 深圳站 (Luohu), 福田站, 深圳东站
广州 includes: 广州南站 (main), 广州站, 广州东站, 广州北站

Best Practice - Always verify exact stations:

First, use stations.mjs to list all stations in the city:
```
node {baseDir}/scripts/stations.mjs 武汉
```

Then, query with exact station names for accurate results:

node {baseDir}/scripts/query.mjs 武汉 上海虹桥 -f md

🔄 Transfer/Connection Guidelines

When planning transfers (中转):

Use JSON output (--json) to verify exact station names
Ensure both segments use the SAME station (e.g., both use 武汉站, not 武汉→汉口)
Recommended minimum transfer time: 20-30 minutes for same station
Different stations in same city require additional travel time (e.g., 武汉→汉口 = 30+ min by subway)

📋 Query Workflow Recommendation

For accurate results, follow this workflow:

List stations in departure city:

node {baseDir}/scripts/stations.mjs 北京

List stations in arrival city:

node {baseDir}/scripts/stations.mjs 上海

Query with exact station names (e.g., 北京南 → 上海虹桥):

node {baseDir}/scripts/query.mjs 北京南 上海虹桥 -d 2026-03-05 -f md

For transfers: Always verify both segments use the same station by checking fromStation and toStation in JSON output.

Technical Notes

Data comes directly from 12306 official API (no key needed)
Station data is cached for 7 days in {baseDir}/data/stations.json
Works for all train types: G (高铁), D (动车), Z (直达), T (特快), K (快速)