directions - Google maps routes

The Directions module is part of the codefurther Python package, and is designed to be used in UK schools to provide students with access to data that describes journeys from one point to another.

Directions is part of a wider initiative that I’m referring to as CodeFurther. The hope is that by providing simple interfaces to information that is relevant to students, they will be able to relate to the data and imagine more ways in which they could consume and use it in their code - and hopefully CodeFurther.

The data that Directions accesses is provided by Google as part of its Google Maps API.


Features

Directions provides:

  • Simplified access to directions from a to b using Google Maps
  • Place names can be vague, Google will do it’s best to decipher them
  • Walking, cycling, driving and transit routes

Usage

Importing the module

Directions exposes a very simple API to developers. It is accessed by importing the GetDirections class into your module and creating an instance of this class, like so:

from codefurther.directions import GetDirections
directions = GetDirections("southampton", "winchester")

GetDirections parameters

The GetDirections object is initialised with a starting location and an end location. It can also be initialised with an optional mode parameter that describes the mode of transport to use.:

from codefurther.directions import GetDirections

driving_directions = GetDirections("southampton","winchester", "driving")
walking_directions = GetDirections("southampton","winchester", "walking)
bike_directions = GetDirections("southampton","winchester", "bicycling")
transit_directions = GetDirections("southampton","winchester", "transit")

GetDirections properties

The GetDirections instance exposes a number of properties to the programmer. These include:

Example program

The example code below shows how you can use these properties to get directions from one place to another.:

from codefurther.directions import GetDirections

directions = GetDirections("Southampton, UK", "Winchester, UK")

if directions.found:
    print( directions.heading )
    for step in directions.steps:
        print( step )
    print( directions.footer )

When run, this code results in the following extract being printed to the display.:

These are the steps for the (walking) journey from Southampton, Southampton, UK to Winchester, Winchester, Hampshire, UK.
1. Head east (8 m / 1 min)
2. Turn left toward Brunswick Pl/A3024 (7 m / 1 min)
3. Turn right toward Brunswick Pl/A3024 (0.2 km / 3 mins)
.
.
.
39. Turn right onto Colebrook St (85 m / 1 min)
Map data ©2014 Google

It is possible to run the same code without first checking if the result was found. In that case, CodeFurther will simply replace the header text with a message stating that the route could not be found, no direction steps will be returned, and the footer will be blank too.:

from codefurther.directions import GetDirections

directions = GetDirections("123l123", "345345l34")

print(directions.heading)
for step in directions.steps:
    print(step)
print(directions.footer)

When run, this code would produce the following output (returned by the GetDirections.heading property).

We couldn't find (walking) directions from: 123l123, to 345345l34.

The idea here is that when used in the classroom, the students will not be put off experimenting by having to remember to check for the GetDirections.found property.


Directions API

Return the directions from a given start point to a given end point.

class directions.GetDirections(starting_point, end_point, mode='walking')

A wrapper for the gmaps Direction class to make it simpler to deal with in the classroom

The GetDirections class is inititialised with a starting point, an end_point and and optional transport mode.

>>> directions = GetDirections("southampton, UK","winchester, UK", mode="walking")

This returns an object that can then be interrogated for information about the route.

>>> if directions.found:
>>>     print("Directions found!")
>>> else:
>>>     print("Couldn't find a route.")

If a valid route was found, simplified and prettified text can be accessed through:

>>> directions.heading
>>> "These are the steps for the (walking) journey from Southampton, Southampton, UK to Winchester, Winchester, Hampshire, UK."

and:

>>> directions.footer
>>> "Map data ©2014 Google"

and the steps of the route can be accessed through the GetDirections.steps property, which returns a list of str.

>>> directions.steps
>>> [
>>>     "1. Head east (8 m / 1 min)",
>>>     "2. Turn left toward Brunswick Pl/A3024 (7 m / 1 min)",
>>>     "3. Turn right toward Brunswick Pl/A3024 (0.2 km / 3 mins)",
>>>     "4. Turn right onto Brunswick Pl/A3024 (13 m / 1 min)",
>>>     .
>>>     .
>>>     .
>>>     "39. Turn right onto Colebrook St (85 m / 1 min)"
>>> ]

The raw gmaps.Directions object can be accessed using:

>>> directions.raw

Once the object has been created, subsequent calls to the GetDirections.journey() method will create new routes without the need to create a brand new GetDirections() object.

>>> new_directions = directions.new_journey("winchester, uk", "southampton, uk", "driving")
footer

Returns the text footer for this route.

Returns the text footer for this route which is usually a copyright notice - if valid. Or if not valid then a
null string is returned instead.
Returns:_footer – A text copyright notice if it is valid, or a null string if the route is not valid.
Return type:str
found

Reveals if the route specified was found.

Returns a boolean True if the route specified was found by Google, or False if the route could not be found.

Returns:_found – True if the route was valid or False if the route was invalid.
Return type:bool
heading

Returns the text heading for this route.

Returns the text heading for this route - if valid. Or if not valid then an appropriate message is returned
instead.
Returns:_heading – A text description of the route if it is valid, or an appropriate message if the route is not valid.
Return type:str
new_journey(starting_point, end_point, mode=None)

Create a new journey, specifying start and end points and the mode of travel.

This method pretty much mirrors the GetDirections.__init__() method.

If the journey appears valid to Google Maps, then this method sets appropriate values for the GetDirections.heading method, the GetDirections.footer and the GetDirections.steps methods.

Parameters:
  • starting_point (str) – The text string that describes the starting point for the route
  • end_point (str) – The text string that describes the end point for the route
  • mode (str, optional) – Text string either “walking”, “driving”, “bicycling” or “transit”, defaults to “walking”.
starting_point

str

The text string that describes the starting point for the route

end_point

str

The text string that describes the end point for the route

mode

str

Text string either “walking”, “driving”, “bicycling” or “transit”. Note that transit doesn’t seem to be widely supported outside of the US.

default_mode

str

The mode that was specified the first time the object instance was created.

Returns:self – Returns an instance of the GetDirections object to allow for object chaining.
Return type:GetDirections
raw

Provides access to the raw gmaps.directions.Directions class object.

Returns:_directions – The raw Directions object.
Return type:gmaps.Directions
steps

Returns a list of strings that describe the steps for this route.

Returns a list of strings or an empty list if the route is not valid.

Yields:(str) : A generator of list of strings that describe the steps for this route, or an empty list if the route is not valid.