Thrills and Hills Tutorial: Understanding Route Parameters in the Routing API

The Routing API contains a few unique parameters which allow developers to create unique journeys for their users, so that drivers have the freedom to explore new terrains and scenic routes by car while navigating safely to their destination. In this article, I’ll explain how to implement these features, what they do, and how they affect the driver’s experience.

TomTom's Routing API

The Routing API contains a few unique parameters which allow developers to create unique journeys for their users, so that drivers have the freedom to explore new terrains and scenic routes by car while navigating safely to their destination. In this article, I’ll explain how to implement these features, what they do, and how they affect the driver’s experience.

When looking at directions from a developer perspective, it’s easy to get lost in all the attributes that work to navigate you – from one point to the next, and the next, and the next! So many factors come into play when constructing driving plans, which is why I decided to deconstruct some of what’s necessary to work with our Routing API.

Especially if you’re new to the topic of routing as a whole, it can be best to understand it in two ways, from a far and close perspective:

• At a helicopter view, directions encompass basic, necessary points that make it possible to calculate navigation from point A to B. These are things like point, a latitude/longitude pair, and dateTime, represented as RFC 339 – time represented in the order: year, month, day, time (military) as hours, minutes, seconds.

• At a close view, we’ll examine a subset of one of these parameters, called routeType, which help customize routes to the user’s preference. In a final product, we presume to understand that a driver may not have shortest travel time as their first directional priority. Instead, a driver may want an exciting road trip, where we begin to think of what a “thrilling” route might mean.

What is a routeType, anyhow?

You don’t specifically need to indicate routeType to use the Directions API, as it is an optional parameter, unlike the location from which your driver is travelling. RouteType encompasses three types of route, which also adjoin different attributes that contribute to the driver’s journey.

[[{"fid":"24671","view_mode":"default","fields":{"format":"default","field_file_image_alt_text[und][0][value]":"What is a routeType?","field_file_image_title_text[und][0][value]":"Example of a routeType. "},"type":"media","field_deltas":{"1":{"format":"default","field_file_image_alt_text[und][0][value]":"What is a routeType?","field_file_image_title_text[und][0][value]":"Example of a routeType. "}},"attributes":{"alt":"What is a routeType?","title":"Example of a routeType. ","class":"media-element file-default","data-delta":"1"}}]]

The fastest route will always route the most efficient route in terms of time, traffic and other factors, while the shortest route will purely sort the journey by distance, regardless of the actual travel time that may be effective. Eco type routes are specifically designed to conserve fuel regardless of engine – combustion or electric. Eco routing specifically can be used to help electric vehicles with heavy batteries balance, distance remaining, and kwH energy to preserve battery level on arrival.

Different routes have various driver personas in mind. A fast route may appeal most to delivery drivers, while a short route (in the API’s vernacular) might be best suited to a commute driver avoiding troublesome areas. Eco drivers may be carpooling and looking to conserve energy.

Lastly, thrilling routes include parameters to be set for varying degrees of desired hilliness and windingness, and also include few freeways whenever possible so that roads are more likely to be scenic, less traveled and more interesting. A driver selecting a thrilling route might want to enjoy more diverse scenery and new areas to explore.

How do we actually calculate a thrilling route?

Lastly, thrilling routes include parameters to be set for varying degrees of desired hilliness and windingness, and also include few freeways whenever possible so that roads are more likely to be scenic, less traveled and more interesting. A driver selecting a thrilling route might want to enjoy more diverse scenery and new areas to explore.

How do we actually calculate a thrilling route?

Here, we’ll actually head to the API explorer to see what a functional query looks like involving the Directions API.

Here, we add two sets of coordinates that correspond to areas in Berlin and Dresden, Germany, respectively.

Represented with a basic route for speed displayed, these are the points in relation to each other.

We add basic information into the API explorer about our vehicle (a car with a combustion engine), and how much hilliness and windingness we want our driver to encounter.

Executing this GET returns a very long list of points. If we were to manually (and painfully) take each and every point and plot it onto a map as a stop between our first and last coordinates, the summation of our waypoints would provide us with our thrilling route.

Let’s get visual.

As expected, there’s a much easier way to visualize this. First, I’ll take just one of these waypoints and plot it out as a single stop to illustrate my point above.

Again, manually placing a random waypoint on an otherwise speed-priority calculated map gives us the indicated route, which we can immediately tell takes a longer turn off the optimally fastest route from its counterpart above.

As we haven’t instructed this particular route planner to do anything else than to calculate the fastest way to go from A to B to C, our journey returns from its waypoint in the middle back to the quickest way to our destination.

And finally, instead of manually planning all the points, we’ll use our own tool to visualize the final assembly of all those (and many more) points from the executed query on the TomTom Map:

And there you have it! All the little points, fitted to a drivable route. This was created using a sample from the TomTom SDK for Web, found here, which I modified for this article. [Pointing to tutorials once here and once below intentionally.]

Go have some thrills.

I walked you through my personal favorite way to get acquainted with using the Directions API as a newcomer, and adjusting to the terminology used to differentiate different ways of driving from starting point to finish. From here, you can go and play with the varying levels of hilliness, windingness, distance, and differences with EV’s and gas-powered vehicles to see where you find interesting variation along your theoretical journeys.

Now that you know a little more about how to have a thrilling road trip, don’t forget to check out our tutorials and examples on our developer portal, especially about creating Routes.

Happy Mapping!