Thsr Timetable

Base directory: /Users/htlin/Mail/.claude/skills/thsr-timetable

Quick start

python3 .claude/skills/thsr-timetable/scripts/thsr.py 嘉義 台北 "2026-06-05 17:30"

Output (live API):

嘉義 → 台北    2026/06/05(五) 17:30

車次    出發     抵達     費時     停靠站
----  -----  -----  -----  --------------------
0666  17:32  18:59  01:27  台中、新竹、桃園、板橋
0846  18:00  19:39  01:39  雲林、彰化、台中、苗栗、新竹、桃園、板橋
0670  18:08  19:33  01:25  台中、新竹、桃園、板橋
...

Invocation

python3 scripts/thsr.py [--json] <from> <to> [datetime]

Examples:

# 找出明早從台北南下嘉義的班次
python3 scripts/thsr.py 台北 嘉義 "2026-06-05 08:00"

# 用「現在」當基準找最近一班北上
python3 scripts/thsr.py 嘉義 台北

# 取 JSON 結構（要塞進其他工具時）
python3 scripts/thsr.py --json 嘉義 台北 "2026-06-05 18:00"

What the API returns

Per train: id (車次), departure_time (start station), destination_time (end station), duration (HH:MM), non_reserved_Car (自由座車廂), note, cross_night, plus station_info[] listing every station the train stops at (departure_time is empty string when the train skips that station).

Default table view shows: 車次 / 出發 / 抵達 / 費時 / 停靠站（中間經過）. The 停靠站 column is derived client-side from station_info (filters to stops strictly between start and end).

Getting credentials (Superior APIs)

This skill does not ship a token — the API is served through the Superior APIs proxy marketplace, and each user brings their own. One-time setup:

1. Open the API's interface page and sign in (free account): https://superiorapis.cteam.com.tw/zh-tw/interface/596498115dc8?tab=api&tryme=596501c7a587
2. 訂閱 (subscribe) to this THSR timetable API. The tryme tab lets you fire a test request in-browser first.
3. After subscribing the platform issues you two things, both shown on that page:
   • a personal token — a long JWT (starts eyJ…) → goes in THSR_API_TOKEN
   • the proxy endpoint URL, of the form https://superiorapis-creator.cteam.com.tw/manager/feature/proxy/<feature_id>/<pub_id> → goes in THSR_API_URL
4. Write them into .env (sibling of SKILL.md):

   cat > .env <<'ENV'
   THSR_API_URL=https://superiorapis-creator.cteam.com.tw/manager/feature/proxy/<feature_id>/<pub_id>
   THSR_API_TOKEN=eyJ…
   ENV
   

The wire call (handled by scripts/thsr.py, mirrored in references/api.js): POST <THSR_API_URL> with headers Content-Type: application/json + token: <THSR_API_TOKEN>, body { "start_station_no": <1-12>, "end_station_no": <1-12>, "datetime": "<ISO8601>" }. The token is a long-lived JWT with no refresh flow — when it expires the API returns HTTP 401, and you re-copy a fresh one from the same page.

Credentials & repo hygiene

• Token + URL live in .env (sibling of SKILL.md); never commit.
• .gitignore already excludes .env and __pycache__/.
• references/api.js keeps the upstream Superior APIs example for reference only — Claude should call scripts/thsr.py, not re-implement the JS.

Gotchas

1. Datetime is Taipei-local, not UTC. The API accepts an ISO string ending in Z but treats the time as local. Don't pre-convert to UTC. The wrapper handles this for you.
2. The API returns trains departing at or after the supplied time at the start station — not "around" it. To see trains that already left, query with an earlier time.
3. Result count is fixed at ~16 trains forward from the queried time. For a full-day picture, query twice (e.g. 08:00 and 15:00).
4. Station names must be exact 2-char Traditional Chinese (嘉義, not Chiayi / Jiayi / 嘉義站). The script will reject and list valid names.
5. No date-of-week filtering exposed. All trains shown actually run on the queried date — the API already filters out trains that don't operate that day, so no need to cross-check the dot patterns from the static PDF timetable.
6. Auth is a long-lived JWT. If the token rotates, replace THSR_API_TOKEN in .env. There's no refresh flow; the API will return HTTP 401 / a JSON error when expired.

When to use this skill

• Planning round-trip HSR for a speaking engagement / meeting in another city.
• Filling 講師資料表 / 出差申請 fields like 「到達 XX 高鐵站時間」.
• Comparing express vs all-stop trains (use the 停靠站 column — fewer stops = faster).
• Quick "what's the next 北上 train?" lookup.

For the static fare table or PDF download (when the user wants to print the schedule), see https://www.thsrc.com.tw/ArticleContent/a3b630bb-1066-4352-a1ef-58c7b4e8ef7c. This skill does not wrap fares — only timetable.