Skip to content

Latest commit

 

History

History
245 lines (178 loc) · 8.14 KB

gtfsschedule.1.adoc

File metadata and controls

245 lines (178 loc) · 8.14 KB
Raw

GTFSSchedule(1) Manual Page

NAME

gtfsschedule - Be on time for your next public transport service.

SYNOPSIS

gtfsschedule search STRING

gtfsschedule setup [-s|--static-url URL]

gtfsschedule monitor STATION-ID[:MINUTES] [-u|--autoupdate] [-l|--limit] [--static-url URL] [--realtime-url URL] [--schedule-item-template STRING]

DESCRIPTION

gtfsschedule is a command line utility providing public transport schedule information following the GTFS specification from Google.

OPTIONS

setup --static-url='URL'

Populates a local database with static schedule information downloaded from the URL given with --static-url. The database is created by default in: $HOME/.local/share/gtfs/ The schedule information is typically a zip archive offered by the public transport authority containing CSV files following the GTFS Static Reference.

monitor STATION-ID[:MINUTES]

Print next departing services for a given stop. You can specify more than one station-id deliminted by spaces. Additionally the time to reach the station can be added to the station id using an integer separated by a +.

u, --autoupdate

Automatically update the static dataset if it becomes out of date. The gtfsschedule tool performs a check every run by performing a HEAD request against the URL given by the --static-url option. Note: Be careful using this flag, since there is no verification of the downloaded zip archive not containing malicious contents.

l, --limit

Set an upper limit as to how many schedule items are shown. Defaults to 3 items. The program enforces a maximum of 20 items.

--static-url='URL'

Providing this option will let the gtfsschedule tool performing a HEAD request to determine if the local dataset is outdated. If a new version is available online a message is message is printed to STDERR.

--realtime-url='URL'

URL to retrieve realtime information from. The tool will always retrieve the schedule first from the local database and update these services with realtime information if available.

--schedule-item-template='STRING'

Template which formats one single schedule item. If you provide a template string on the command line, be mindful that the characters in the template can be interpreted by the shell.

search NAME

Search for a stop id by giving the name of a possible stop. The search conducted is a sub-string search against the stop names in the database. Result is ordered by stopid in descending order. Regular expressions or wildcards are not supported.

Examples

Setting up the local database

Run the setup command like:

gtfsschedule setup --static-url https://gtfsrt.api.translink.com.au/GTFS/SEQ_GTFS.zip

Finding out your stop code

You can search for a stop by typing in the street name or landmark:

# Show all results like "Roma Street"
gtfsschedule search Roma

# Whitespace need to be quoted
$ gtfsschedule search "Roma St"
000138 Roma Street Stop 138 near Ann St

The printed stop id is the id you use to monitor for departures.

Retrieve next departing services

Once you have your stop code, invoke the command to show next departing services:

# Transport leaves in 11 minutes
gtfsschedule monitor 600248
Desitnation 11 min (13:17:00)

Using a count down

If you want to know when to leave your position in order to reach the service upon departure time, you can specify a delay:

# Transport leaves in 11 minutes, factor in a walk time to the stop/station of 7 minutes
gtfsschedule monitor 600248+7

# Include in realtime updates with possible delays
gtfsschedule monitor 600248+7 --realtime-url http://gtfsrt.api.translink.com.au/Feed/SEQ

Monitoring multiple stops

You can specify multiple stops with different delays to reach them:

gtfsschedule monitor 600248+7 600249+5

Schedule change indicators format

When you run the program with realtime updates, the following changes are indicated as follows:

# Delayed service
!GTPB Destination 11 min (13:17:06 (46s)) <-- delay
                          ^ departure time including delay

# Canceled service
GTPB Destination 11 min (13:17:00 !CANC!)

Updating the database

If you run the gtfsschedule tool with the static-url option, it automatically checks if the local dataset is up to date and prints a warning if it isn’t. Simply run:

gtfsschedule setup --static-url https://gtfsrt.api.translink.com.au/GTFS/SEQ_GTFS.zip

to update download a new dataset and update your database.

Automatically keeping the database up-to-date

You can invoke gtfsschedule monitor with -u to keep your static dataset up-to-date automatically:

gtfsschedule monitor -u --static-url https://gtfsrt.api.translink.com.au/GTFS/SEQ_GTFS.zip 600029

Notes

Even though the gtfsschedule program supports to receive feed updates or download the GTFS dataset from any arbitrary URL it is currently not tested and might not work. Feedback is welcome.

Configuration

A configuration file helps with making the use of the command line tool easier, especially if you’re always receiving updates from the same API and the dataset from the same URL. The command line options and arguments have precedence over the configuration file however.

The configuration file should be placed in ~/.conf/gtfs/config.cfg, should define one section default and supports setting the URLs to the realtime API and the static dataset. For example, for Brisbane the config file would look:

[default]
static-url = https://gtfsrt.api.translink.com.au/GTFS/SEQ_GTFS.zip
realtime-url = http://gtfsrt.api.translink.com.au/Feed/SEQ
schedule-item-template = $delayIndicator$$serviceName$ $minutesToDeparture$min $departureTime$ $scheduledDepartureTime$ $scheduleTypeDiff$

The format of the configuration file is documented here: https://hackage.haskell.org/package/ini/docs/Data-Ini.html

Note: I have not tested how well the support works with other GTFS feed APIs than Translink (QR) provides. Feedback is very welcome.

Custom schedule formatting

You can specify a custom template to format the schedule. In circumstances in which no value is returned for the given field it is not expanded.

Available fields which always return a value:

  • $serviceName$ - The service name which uses the short route name and the head sign of the service if available. If the head sign of the service is not available, the long route name is used.

  • $minutesToDeparture$ - Remaining minutes from now to departure time, including the delay it takes to walk to the station.

  • $departureTime$ - Departure time including any delays retrieved by the realtime feed.

  • $scheduledDepartureTime$ - Official departure time retrieved from the static data set.

  • $stopName$ - full name of the stop.

Available fields which may not return a value:

  • $delayIndicator$ - Prints an exclamation mark if the delay is not 0, otherwise nothing.

  • $readableDelay$ - Prints the delay as a formatted time (HH:MM:SS). Delay is indicated by a '-' prefix, while running ahead of schedule with a '+'. If the service has no delay, nothing is printed.

  • $congestionPercent$ - shows congestion level in percent. 0 means unknown congestion level while 100 means severe congestion. Nothing is printed if the feed does not provide this information.

  • $occupancyPercent$ - shows occupancy status in percent. 0 means empty while 100 means not accepting passengers. Nothing is printed if the feed does not provide this information.

  • $scheduleTypeDiff$ - status of the trip, which can be one of ADDED or CANCELED. The default is SCHEDULED and is not displayed.

Status monitor examples

Xmobar:

Run Com "gtfsschedule" ["monitor", "600248"] "gtfs" 600

Poor mans statusbar with watch. Use a terminal window and:

watch -n 60 "gtfsschedule monitor 600248+7"