# Thsr Timetable

> Look up live Taiwan High Speed Rail (THSR) train timetables — given two stations and a Taipei-local datetime, returns the next ~16 trains with departure / arrival / duration / intermediate stops. Use whenever planning HSR travel (medical talks, meetings, day trips), comparing train options, or filling 高鐵 times into a form. Wraps Superior APIs proxy. No PDF parsing, no scraping.

- Skill: `htlin222/thsr-timetable` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add htlin222/thsr-timetable`
- Raw SKILL.md: https://api.skillmd.com/api/skills/htlin222/thsr-timetable/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: htlin222 (https://skillmd.com/u/htlin222)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/htlin222/thsr-timetable

---


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

## Quick start

```bash
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]
```

| 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` (車次), `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`):
   ```bash
   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.