norikae-guide

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:

1. 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.

2. 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.

3. 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