| name | norikae-guide |
| description | Search Japan train routes and station timetables via Yahoo! 乗換案内. Use when users ask about train routing, schedules, or timetables in Japan. |
Norikae Guide
Search Japan train routes and look up station timetables using Yahoo! 乗換案内.
Supports English, Chinese, and Japanese input — always convert station names to Japanese before querying (e.g. Shibuya → 渋谷, 涩谷 → 渋谷).
Route Search
python3 scripts/fetch_norikae_routes.py --from <出発駅> --to <到着駅> --show-url [options]
--show-url must always be included.
Options:
--via <駅> (repeatable, max 3)--year/--month/--day/--hour/--minute — resolve relative dates to absolute values; defaults to now--time-type: departure (default), arrival, first_train, last_train, unspecified--sort-by: time (default), fare, transfer--ticket: ic (default), cash--seat-preference: non_reserved (default), reserved, green--walk-speed: slightly_slow (default), fast, slightly_fast, slow--no-use-shinkansen, --no-use-express, --no-use-airline, --no-use-highway-bus, --no-use-local-bus, --no-use-ferry
You can also fetch from an existing URL:
python3 scripts/fetch_norikae_routes.py --url '<full-yahoo-url>' --show-url
Intent Mapping
| User intent | CLI flags |
|---|
| cheapest / 最便宜 | --sort-by fare |
| fastest / 最快 | --sort-by time |
| fewest transfers / 换乘最少 | --sort-by transfer |
| no shinkansen / 不要新干线 | --no-use-shinkansen |
| local trains only / 在来线 | --no-use-shinkansen --no-use-express |
| no buses / 不要巴士 | --no-use-highway-bus --no-use-local-bus |
| cash fare / 现金票价 | --ticket cash |
| reserved seat / 指定席 | --seat-preference reserved |
| Green Car / 绿车 | --seat-preference green |
| arrive by / XX点前到 | --time-type arrival |
| first train / 始発 | --time-type first_train |
| last train / 終電 | --time-type last_train |
Timetable Lookup
Follow these steps in order:
-
Search for the station code:
python3 scripts/fetch_timetable.py search <station-name-in-japanese> --station-only
Use --station-only to exclude bus stops. Pick the matching station code from the results.
-
List lines and directions at the station:
python3 scripts/fetch_timetable.py lines <station-code>
This returns available lines with their gid (group ID). If the user specified a line, match it; otherwise ask which line/direction they want. If there is only one line, skip asking and proceed.
-
Show the departure timetable:
python3 scripts/fetch_timetable.py timetable <station-code> <gid> [--kind 1|2|4]
--kind: 1 = weekday, 2 = saturday, 4 = holiday. Defaults to today's schedule.
Clarification Rules
Ask one concise clarification when:
- Station name is ambiguous (multiple matches)
- Departure station is missing and cannot be inferred
- User gives conflicting priorities (e.g. "fastest" and "cheapest") without tie-break
- Station has multiple lines and user didn't specify which one
