SuperAPI AI Directory

trainclaw

Coding & development

View repository

Updated 10-15 19:52

About this skill

TrainClaw 🚄 - China Rail Ticket Query / 车票查询AI助手

概述 / Overview

3-in-1 China 12306 query: tickets + route stops + transfer plans, zero login. Three-in-one 12306 query: remaining tickets + route stops + transfers, zero login.

Call trainclaw.py Complete the query with one command. No login, no API Key, no extra configuration required—only depends on Python + requests, ready to use out of the box. Supports train type filtering, time windows, sorting, and text/json/csv multi-format output.

One command via trainclaw.py. No login, no API key, no extra config — just Python + requests, ready to go. Filter by train type, time window, sort by duration. Output: text / json / csv.

触发方式 / Trigger

Triggered when the user mentions keywords such as train tickets, high-speed rail tickets, bullet train tickets, train number query, remaining tickets, route stops, transfers, 12306, etc.

Trigger when user mentions train tickets, bullet train, remaining tickets, route stops, transfer, 12306, China rail, etc.

快速示例 / Quick Examples

  • "Check tomorrow's high-speed rail tickets from Beijing to Shanghai" → remaining ticket query
  • "Any bullet trains from Beijing to Shanghai tomorrow?" → Ticket query
  • "Which stations does G1033 stop at?" → route stops query
  • "What stops does G1033 make?" → Route stops
  • "How do I transfer from Shenzhen to Lhasa?" → transfer query
  • "How to get from Shenzhen to Lhasa by train?" → Transfer plan
  • "Bullet trains from Nanjing to Shanghai, departing in the morning, sorted by duration" → remaining ticket query with filters
  • "EMU trains Nanjing to Shanghai, morning only, sort by duration" → Filtered query

工作流程 / Workflow

用户说:"查明天北京到上海的高铁"
    ↓
提取参数:出发=北京,到达=上海,日期=明天,类型=G
    ↓
执行命令:
  python trainclaw.py query -f 北京 -t 上海 -d 2026-03-04 --type G
    ↓
返回余票信息(text 格式,直接展示给用户)

子命令 / Subcommands

1. 余票查询 / Ticket Query (query)

Query remaining ticket information between two stations, with support for filtering and sorting.

# 基础查询
python trainclaw.py query -f 北京 -t 上海

# 完整参数
python trainclaw.py query -f 北京 -t 上海 -d 2026-03-04 \
  --type G --earliest 8 --latest 18 --sort duration -n 10 -o text

2. 经停站查询 / Route Stops (route)

Query all route stop information for a train number.

python trainclaw.py route -c G1033 -d 2026-03-04
python trainclaw.py route -c G1 -d 2026-03-04 -o json

3. 中转查询 / Transfer Plans (transfer)

Query transfer plans that require a change of trains.

# 自动推荐中转站
python trainclaw.py transfer -f 深圳 -t 拉萨 -n 5

# 指定中转站
python trainclaw.py transfer -f 深圳 -t 拉萨 -m 西安 -d 2026-03-04

参数说明 / Parameters

通用参数 / Common Parameters

Parameter Description Default Value
-d, --date Query date (yyyy-MM-dd) Today
-o, --format Output format: text / json / csv text

筛选参数 / Filter Parameters (query / transfer)

Parameter Description Default Value
-f, --from Departure station (station name/city name/three-letter code) Required
-t, --to Arrival station (station name/city name/three-letter code) Required
--type Train type filter (see table below) No filter
--earliest Earliest departure hour (0-24) 0
--latest Latest departure hour (0-24) 24
--sort Sort: startTime / arriveTime / duration No sorting
--reverse Reverse order No
-n, --limit Maximum number of results query: unlimited, transfer: 10

车次类型代码 / Train Type Codes

Code Meaning
G High-speed rail/intercity (starting with G/C)
D Bullet train
Z Direct express
T Express
K Fast
O Other (non-GDZTK)
F Fuxing
S Smart EMU

Can be used in combination, e.g. --type GD means high-speed rail + bullet train.

车站名解析 / Station Name Input

Supports three input formats, automatically recognized:

  1. Exact station name: 北京南、上海虹桥、南京南 → Direct match
  2. City name: 北京、上海、南京 → Match a representative station in that city
  3. Three-letter code: BJP、SHH、NJH → Use directly

Output Formats / Output Formats

text format (default, recommended for user reading)

车次 | 出发站→到达站 | 出发→到达 | 历时 | 席位信息 | 标签
G25 | 北京南→上海虹桥 | 17:00→21:18 | 04:18 | 商务座:1张/2318.0元, 一等座:有票/1060.0元 | 复兴号

json format (recommended for program processing)

Full JSON array, containing all fields.

csv format (only supported by query)

Standard CSV, with a header row.

Files / Files

  • Main program: trainclaw.py
  • Configuration file: config.py
  • Cache directory: cache/(station data is automatically cached for 7 days)

Notes / Notes

  1. Date limit: Only supports querying tickets for today and within the next 15 days
  2. Network dependency: First run requires downloading station data (~3000 stations), afterwards uses local cache
  3. Error output: Error messages are output to stderr, data is output to stdout, supports pipeline operations
  4. Transfer limitation: Transfer query results depend on 12306's recommendations, not all combinations have results
  5. Dependencies: Only requires Python 3.8+ and requests library

Usage Scenarios / Usage Scenarios

Daily Check / Daily Check

用户: "明天北京到上海有什么高铁?"
→ python trainclaw.py query -f 北京 -t 上海 -d {明天日期} --type G

Time Filter / Time Filter

用户: "上午 8 点到 12 点从南京到杭州的动车"
→ python trainclaw.py query -f 南京 -t 杭州 --type D --earliest 8 --latest 12

Route Stops / Route Stops

用户: "G1033 都停哪些站?"
→ python trainclaw.py route -c G1033 -d {今天日期}

Transfer Plan / Transfer Plan

用户: "从北京怎么坐火车去成都?"
→ python trainclaw.py transfer -f 北京 -t 成都 -n 5

Author / Author

Community-driven, open-source, free for everyone. / Community-driven, open-source, free for everyone.