Route search

The python script route-search.py is a command-line utility to query and find optimal transit connections in Oslo using the Entur national transit database. It is optimized to help you find the best bus, metro, and rail combinations from a starting coordinate to a destination, matching specific arrival constraints and jogging capabilities.

Features

1. Automated Geocoding: Translates text destinations (e.g., "Oslo S") directly into Entur’s National Stop Register IDs.
2. Radial Location Scan: Scans all transit stops within a custom radius (default 1.5 km) around your coordinates.
3. Jog Off Calculator: Computes the exact time you need to leave your coordinates (JOG OFF time), factoring in distance, jogging speed, and a pre-boarding buffer.
4. Optimal Ordering: Orders connections in descending order of the jog off time (so the latest departure is shown first).
5. Flexible Modes: Supports filtering by Metro (metro), Bus (bus), and Train (rail).

Installation & Dependencies

The script is written in standard Python 3 and requires no external dependencies. It uses built-in libraries (urllib, json, datetime, argparse, etc.) out of the box.

Simply run it with Python:

python3 route_search.py [arguments]

CLI Reference & Arguments

positional arguments:
  coords                Starting coordinates in 'lat,lon' format (e.g. '59.9224,10.7582')
  destination           Name of the destination stop/station (e.g. 'Oslo S')

options:
  -h, --help            show this help message and exit
  --target-time TARGET_TIME
                        Departure time of connection at destination, in HH:MM format (default: 08:22)
  --transfer-min TRANSFER_MIN
                        Desired transfer window range in minutes (default: 5-6)
  --radius RADIUS       Search radius in kilometers for starting stops (default: 1.5)
  --modes MODES         Allowed transport modes, comma-separated (default: bus,metro,rail)
  --date DATE           Date in YYYY-MM-DD format (defaults to today or tomorrow depending on target time)
  --jog-speed JOG_SPEED
                        Jogging speed to the stop in km/h (default: 8.0)
  --buffer-min BUFFER_MIN
                        Buffer time in minutes to arrive at the stop before departure (default: 3.0)

Example Usage

1. Default Route Search (Bus, Metro, & Train at 8 km/h with 3 min buffer)

python3 route_search.py "59.9224,10.7582" "Oslo S" --date "2026-06-03"

2. Custom Jogging Speed & Buffer

If you jog at 10 km/h and want a tighter 2-minute buffer before boarding:

python3 route_search.py "59.9224,10.7582" "Oslo S" --date "2026-06-03" --jog-speed 10.0 --buffer-min 2.0

3. Change Transfer Window at Oslo S

To arrive at Oslo S with 10 to 12 minutes to spare:

python3 route_search.py "59.9224,10.7582" "Oslo S" --date "2026-06-03" --transfer-min 10-12

Output Explanation

Each result represents a connection option, printed in order of latest departure:

#1: From: Jakob kirke (0.56 km)
  JOG OFF: 07:59:46 (Jog: 4.2 min + 3.0 min buffer at 8.0 km/h)
  Board Vehicle: 08:07:00 | Arr at Destination: 08:16:28
  Transfer Buffer: 5.53 min | Ride duration: 5.0 min (Total elapsed: 16.7 min)
  Route: BUS 34 (5.0 min)

• JOG OFF: The precise time you should leave your house/coordinates.
• Jog / Buffer: Shows the jogging time and buffer applied.
• Dep from Stop / Arr at Destination: When the vehicle leaves the stop, and when you arrive at your destination (e.g., Oslo S).
• Transfer Buffer: The amount of time you have to catch your connecting connection (e.g. 7.78 minutes before the 08:22 train).
• Ride duration: Total time spent on vehicles.
• Route: The transit lines used.

• Route
• Commute