routes.py

Functions:

build_routes_points

• description:

  • takes in coordinates of a route you require directions for and returns a formatted string of the coordinates to be used in a query. (Query is fully formatted with this string of coordinates in another function.)

• inputs:

  • waypoints: a Python list of dictionaries. Each dictionary contains a coordinate - one latitude which is the dict key, one longitude as the dict value. All keys and values should be strings.
    Example: [{"45": "34"}, {"46": "35"}, {"47": "36"}, {"48": "37"}]

  • viawaypoints: a Python list of dictionaries. Each dictionary contains 0 (yes, 0) or more coordinates as key-value pairs - latitudes are keys and longitudes are values. All keys and values should be strings. Length of the full list should be one less than the length of the waypoints list, however, the code will automatically ignore extra elements, be careful with your code.
    Example: [{"45.5": "74.5", "46": "-75"}, {}, {"47": "-75"}]

• outputs:

  • points: a string of all the coordinates given in the inputs formatted as required by the API.
    For the examples given for waypoints and viawaypoints above, the output would therefore be:
    wp.1=45,34&vwp.2=45.5,74.5&vwp.3=46,-75&wp.4=46,35&wp.5=47,36&vwp.6=47,-75&wp.7=48,37
    where wp stands for waypoint and vwp stands for viawaypoint.

• constraints:

  • A max of 25 waypoint coordinates are allowed by the API. The code will accept more, the error is handled by the API which will return an empty response with an error message.

  • A max of 10 viawaypoint coordinates per dictionary. This corresponds to the API’s constraint of allowing up to 10 viawaypoints between waypoints. (This will make more sense if you look at the examples above).

    • Proposal: if there is a need (there likely is) for more than 25 waypoints, the team could define implement logic to separate the intended route into segments

format_routes_query

• description:

  • Takes in parameters and formats them into a query acceptable to the API, the output can then be put into the getter function in common.py to return the API response.

• inputs:

  • points: a string of formatted coordinates.
    Example: wp.1=45,34&vwp.2=45.5,74.5&vwp.3=46,-75&wp.4=46,35&wp.5=47,36&vwp.6=47,-75&wp.7=48,37
    (seem familiar? look above if not)

  • route_attrs: (optional) a string that can be a combination of 5 options. It determines what type of data you get back from the API when sending the request.

    1. “routePath”: This is the default, gives detailed list of maneuvers/directions and a huge list of coordinates

    2. “excludeItinerary”: no list of maneuvers, will give back a list of points with street names and descriptions of the street plus current traffic conditions

    3. “transitStops”: you might think this gives you a list of public transit stops along the route but it does not. It is the same as the “routePath” option except without the huge list of coordinates. No, I have no clue either.

    4. “regionTravelSummary”: gives coordinates, maneuvers, plus a summary of time and distance by “region”; can be asked for along with other options above (see below for example)

    5. “routeSummariesOnly”: only a summary, other options cannot be selected

       • Examples: routePath, transitStops,regionTravelSummary

  • dist_unit: (optional) choose the unit the API will return distances in

    1. “km”: the correct option since we’re Canadian, and therefore the default

    2. “mi”: I disown you

parse_routing_data

• description:

  • After retrieving an API response, pass it into this function to be parsed into a Pandas DataFrame. This can be written into a CSV or into a database

• inputs:

  • response: a Python dictionary to be parsed - the API returns a JSON, however the getter in common.py changes it into a dictionary

• outputs:

  • route_df: a Pandas DataFrame consisting of 6 columns of parsed data for us to enjoy and potentially also use, depends on the day I guess

    1. 'Latitude': the latitude of a given maneuver

    2. 'Longitude': the longitude of a given maneuver

    3. 'Maneuver Instruction': the instruction on how to perform the maneuver at the given coordinates

    4. 'Distance to Maneuver': the distance between the maneuver and the one preceding it

    5. 'Direction': the direction that the car will be driving after performing the maneuver

    6. 'Street': the street that the car will be on after performing the maneuver