gdir 0.1.3

gdir: Get Train/Bus Directions Using the Command Line

gdir is a command line tool which queries Google Directions for public transport routes. The tool displays results as human-readable text.

Installation

gdir is listed on the Python Package Index and may be installed using pip as follows:

$ pip install gdir

Configuration

You will need a Google Directions API key. See Google Directions API documentation for instructions on how to obtain a key.

Set the shell environment variable GOOGLE_MAPS_API_KEY to your API key. This typically involves adding something like the following to your .profile file:

export GOOGLE_MAPS_API_KEY="XXXXXXXXXXXXXXXX-XXXXXXXXXXXXX-XXXXXXXX"

Example Usage

Display directions from Tower Bridge, London to Buckingham Palace, using any mode of public transport and departing now:

$ gdir "Tower Bridge, London" "Buckingham Place"

08:02-08:30 (U) Tower Bridge, Tower Bridge Rd, London SE1 2UP, UK -> London SW1A
            1AA, UK 6.1km
      7mins Walk to Tower Hill 0.5km
08:10-08:21 TOWER HILL board Circle underground towards Edgware Road alight at
            ST. JAMES'S PARK
     10mins Walk to London SW1A 1AA, UK 0.8km

Display directions for the same origin and destination, but prefer to travel by bus and depart at 10:00am today:

$ gdir -b -d 10:00 "Tower Bridge, London" "Buckingham Place"

10:00-10:38 (BB) Tower Bridge, Tower Bridge Rd, London SE1 2UP, UK -> London
            SW1A 1AA, UK 7.0km
      4mins Walk to Boss Street (Stop T) 0.3km
10:03-10:18 BOSS STREET (STOP T) board 381 bus towards Waterloo alight at COUNTY
            HALL (STOP G)
      3mins Walk to Westminster Cathedral / Victoria Station (Stop M) 0.2km
10:29-10:30 WESTMINSTER CATHEDRAL / VICTORIA STATION (STOP M) board 11 bus
            towards Walham Green alight at VICTORIA STATION (STOP G)
     10mins Walk to London SW1A 1AA, UK 0.8km

Display multiple options for travelling from London to Edinburgh, arriving by 2pm on 10th August this year:

$ gdir -M -a 081014:00 "London" "Edinburgh"

09:00-13:20 (T) London, UK -> Edinburgh, UK 632km
09:00-13:20 KING'S CROSS board Lner train towards Edinburgh alight at EDINBURGH
            WAVERLEY

08:30-13:12 (T) London, UK -> Edinburgh, UK 632km
08:30-13:12 KING'S CROSS board Lner train towards Edinburgh alight at EDINBURGH
            WAVERLEY

08:10-13:29 (TT) London, UK -> Edinburgh, UK 644km
08:10-11:50 LONDON EUSTON board Avanti West Coast train towards Glasgow Central
            alight at CARLISLE
12:07-13:29 CARLISLE board Transpennine Express train towards Edinburgh alight
            at EDINBURGH WAVERLEY

08:00-12:20 (T) London, UK -> Edinburgh, UK 632km
08:00-12:20 KING'S CROSS board Lner train towards Edinburgh alight at EDINBURGH
            WAVERLEY

Display walking sub-steps for travelling from The National Gallery, London to Buckingham Palace, using any mode of public transport and departing now. (This route represents a special case, because it does not actually include any public transport steps):

$ gdir -S "The National Gallery, London" "Buckingham Place"

18mins Trafalgar Square, London WC2N 5DN, UK -> London SW1A 1AA, UK 1.4km
18mins Walk to London SW1A 1AA, UK 1.4km
     1 Walk west on Trafalgar Square towards A4 68m
     2 Continue onto Pall Mall E/A4 0.1km
     3 Turn left at Haymarket 8m
     4 Turn right onto Pall Mall/A4 0.6km
     5 Turn left onto Cleveland Row 0.2km
     6 Turn left 40m
     7 Turn right 0.1km
     8 Turn left towards Constitution Hill 66m
     9 Turn right towards Constitution Hill 81m
    10 Turn left onto Constitution Hill 0.1km
    11 Continue onto Spur RdDestination will be on the left 11m

Note: If you get a no directions found error, try appending the city to your origin/destination address. See also the -R flag below for setting region bias.

Detailed Help and List of Command Line Arguments

usage: gdir [-h] [-r] [-n] [-m] [-b] [-u] [-d time_arg | -a time_arg] [-S]
            [-M] [-N] [-R region_code] [-C]
            origin destination

Query the Google Directions API using public transport ('transit') mode and
write results to the standard output in human-readable format. Requires
environment variable GOOGLE_MAPS_API_KEY defining a valid API key. Language of
directions is determined from locale configuration using
locale.getdefaultlocale(), which reads from LC_ALL, LC_CTYPE, LANG and
LANGUAGE in descending order of priority. Word wrapping is achieved using
shutil.get_terminal_size(), which reads from COLUMNS and which may
alternatively use system calls to determine the terminal width, using a fall-
back value of 80 if the terminal width could not be determined. Scripts may
use the -N flag (see below) to disable word wrapping but should not make
excessive assumptions about the structure of output: When using the -N flag,
valid assumptions are 1) routes are delimited by empty lines 2) each route may
be represented as a two-column table, where rows are separated by newlines and
where the first and second column in the table are separated by a single space
3) values in the first column may be left-padded with a variable amount of
whitespace 4) the format of values in the first column may vary for all rows,
including the first row 5) routes output may be followed by two empty lines,
followed by travel warnings and/or copyright/transport agency information.
Status codes: 0 success; 1 generic Error; 2 invalid argument 3:
origin/desination not found; >=4 google-maps-services-python exceptions.

positional arguments:
  origin                start address (quote-enclosed) or latitude,longitude
                        pair
  destination           end address (quote-enclosed) or latitude,longitude
                        pair

optional arguments:
  -h, --help            show this help message and exit
  -r, --rail            prefer to travel by rail (equivalent to train, tram,
                        underground)
  -n, --train           prefer to travel by train
  -m, --tram            prefer to travel by tram
  -b, --bus             prefer to travel by bus
  -u, --underground     prefer to travel by underground (a.k.a. subway)
  -d time_arg, --depart time_arg
                        set departure time (see below)
  -a time_arg, --arrive time_arg
                        set arrival time (see below)
  -S, --substeps        show sub-steps in output
  -M, --multiple        show multiple routes, if available
  -N, --no-wrap         disable word wrapping (affects command line mode only;
                        potentially useful for scripting)
  -R region_code, --region region_code
                        set region bias using the specified top-level domain
                        two-character code (ccTLD)
  -C, --copyright       display copyright and transport agency information
                        (see Directions API terms and conditions)

Departure and arrival times are expressed in terms of local time at the origin
and destination, respectively. Times must be specified in the form
[[[[cc]yy]mm]dd]HH[:]MM, where ccyy is the year, mm is the month (ranging from
1 to 12), dd is the day (ranging from 1 to 31), HH is the hour (ranging from 0
to 23) and MM is the minute (ranging from 0 to 59). When left unspecified,
ccyy, mm and dd values are assumed to be the current year, month and day,
respectively. For ambiguous times arising from daylight saving transitions, it
is assumed that the ambiguous time is expressed in the time zone's standard
time.