SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsthsr-timetable

thsr-timetable

General & other

View repository

Updated 10-15 22:14

About this skill

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

Train No. Departure Arrival Duration Stops

0666 17:32 18:59 01:27 Taichung, Hsinchu, Taoyuan, Banqiao 0846 18:00 19:39 01:39 Yunlin, Changhua, Taichung, Miaoli, Hsinchu, Taoyuan, Banqiao 0670 18:08 19:33 01:25 Taichung, Hsinchu, Taoyuan, Banqiao ...


## Invocation

python3 scripts/thsr.py [--json] [datetime]


| Arg | Required | Format | Notes |
|---|---|---|---|
| `<from>` | yes | 中文站名 | 南港 台北 板橋 桃園 新竹 苗栗 台中 彰化 雲林 嘉義 台南 左營 |
| `<to>` | yes | 中文站名 | same set |
| `[datetime]` | no | `YYYY-MM-DD HH:MM` | Asia/Taipei local time. Defaults to now. |
| `--json` | no | flag | Raw API JSON instead of table. |

Examples:

```bash
# 找出明早從台北南下嘉義的班次
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 (Train No.), departure_time (start station), destination_time (end station), duration (HH:MM), non_reserved_Car (Non-reserved seat 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: Train No. / Departure / Arrival / Duration / Stops (intermediate). The Stops 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 (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 in the Lecturer Data Form / Business Trip Application fields such as "Arrival time at XX HSR Station".
  • Comparing express vs all-stop trains (use the Stops column — fewer stops = faster).
  • Quick "what's the next northbound 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.