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.
- 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
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")
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")
The GetDirections instance exposes a number of properties to the programmer. These include:
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.
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."
>>> 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:
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")
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
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
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
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.
Text string either “walking”, “driving”, “bicycling” or “transit”. Note that transit doesn’t seem to be widely supported outside of the US.
Returns: self – Returns an instance of the GetDirections object to allow for object chaining. Return type: GetDirections
Provides access to the raw gmaps.directions.Directions class object.
Returns: _directions – The raw Directions object. Return type: gmaps.Directions