Trucking Made Easy With the HERE Truck Routing API

Breaker One-Nine, this here’s the Rubber Duck and everything I know about trucking I learned from Convoy. Well, almost everything. I also know that trucks and their drivers work hard every day to get me my stuff. I like stuff!

A lot has changed since 1978 and the CB radio is no longer the most advanced piece of technology in a truck’s cab. In fact, location data and services like those offered by the HERE location platform have become key components of modern logistics.

Central to this is of course routing. Let’s face it, finding the best way from A to B is critical to getting me my stuff. Trucks have a harder time getting from A to B though, not just because they are big and heavy, but also because of the many legal requirements and restrictions they face. Just because a route exists, doesn’t mean a truck can drive it and just because a truck can drive a route, doesn’t mean it is allowed to. Fortunately, HERE offers a dedicated truck routing feature to provide truck drivers and operators with safe and efficient routes for their trucks.

To see how this feature works, let’s have a look at our Routing API. To get a basic route we need just three things: waypoints, a routing mode and credentials. Let’s have a closer look at each.

Waypoints define where we start, where we want to end up and any potential points we want to pass through or stop at along the way. We need at least two waypoints: a start and a destination. Waypoints are defined by using a latitude and a longitude (geographic coordinates). For example, the Brandenburg Gate in Berlin is located at a latitude of 52.5163 and a longitude of 13.37801.

There are multiple ways to get geographic coordinates. For example, for our starting waypoint we can ask the device for its current location or use our Positioning API. For the destination waypoint we could use the Geocoder API to convert any delivery addresses we may have into geographic coordinates.

An easy way to get some test coordinates is to use HERE WeGo. We can simply right click on any location on the map, then click the address that pops up and choose “See more info” on the left. This will display additional information about the location, including its latitude and longitude.

Not all possible routes are made equal, and the routing mode allows us to provide additional information to the routing algorithm. It uses this information to determine the most suitable route for our specific situation. To set the routing mode, we must first choose between the type of route (fastest or shortest) and the transport mode, for example walking, biking or driving by car.

Credentials are used for authentication. They consist of an app id and an app code. You can get your own set of credentials by signing up on developer.here.com. There’s a 90 day free trial available that includes all of our routing features. If you’ve already signed up, you can access your credentials on your projects page.

Let’s have a look at an example. Let’s say we’re in Berlin and we want to drive our car from the Brandenburg Gate to the East Side Gallery on the fastest route. Here’s how that API call would look like.

Pretty simple. Just remember to replace the credentials placeholders with your own app id and app code! It’s also easy to add additional waypoints or change the mode of transport. Let’s say that we want to get from the gate to the gallery again, but this time we want to walk on the fastest route. We also need our daily caffeine fix, so we are going to pick up an Americano to go at Oslo Kaffeebar on the way. Our API call would now look like this.

Both of these API calls will return a response in JSON, which contains a route array. This in turn contains one or more leg arrays. Each leg represents the route between two waypoints. As we have three waypoints in our second example, we get a response with one route containing two legs. Each leg then contains a set of maneuver arrays. Maneuvers represent the actions needed to move from one road segment on the route to the next. Let’s have a look at a maneuver.

As you can see the maneuver contains various information about the segment of the route, including its position and appropriate instructions to follow the route. You can check out the documentation for full details on the response.

So far, so good. That said, we’re not walking or driving a car. We’re in a truck and trucks are special.

Trucks also don’t do much sightseeing, so let’s pick a slightly more suitable route. Let’s pretend we’re in Durham, NC at the Northgate Mall and our truck has just picked up a delivery for a customer in Gregson Street. If we ask the Routing API for a fastest car route, the response will look like this.

At first glance that looks fine. There’s just one small problem. This route would take us right under the infamous Canopener Bridge.

We don’t want to crash our truck and/or endure public humiliation on the web, so what do we do? Let’s try changing the routing mode from “car” to “truck”!

That helps a bit, because it changes our route to comply with certain legal restriction, including turn restrictions and no trucks allowed areas. However, as we can see above, the route still take us right under the bridge. Into the bridge, really.

Clearly, using the truck routing mode alone is not enough. We also have to give the routing algorithm additional information about our truck. For example, to prevent us from crashing into the Canopener Bridge, it needs to know the height of our truck. We can provide it with this information by using the truck profile parameters. Let’s give that a try.

The bridge famously has a clearance of 11 foot 8 inches, which translates to about 3.56 meters. So let’s pretend our truck 3.8 meters high. There’s plenty of other opportunities to embarrass ourselves, so let’s also set the width and weight of the truck to 2.4 meters and 10 tons respectively. Just to be sure. We do this using the height, width and limitedWeight parameters. Our API call now looks like this.

As you can see this protects us from crashing into bridges and other hazards related to being big and heavy. Nice!

Of course it doesn’t stop us from exploding.

This is a bigger risk than you might think, as trucks often carry dangerous goods, including explosives, radioactive materials and boxes filled with poisonous Redback spiders. (That last one may or may not be true, but I definitely worry about it.)

Obviously if you’re carrying hazardous goods, there are some restrictions. For example, when you’re carrying cargo that could be harmful to water, the government generally doesn’t want you to drive near the water source for a major city. Also, if you’re carrying boxes full of radioactive Redback spiders, I really don’t want you to drive anywhere near my house. Ever.

Anyway, our routing algorithm can also find you a suitable route for a truck filled with hazardous materials. Let’s assume we want to transport a load of toxic sludge from the small town of Erkner in Brandenburg to Berlin-Friedrichshagen. Without toxic sludge, this would be easy. Just follow the road for about 12 minutes and you’re there.

Unfortunately this route goes right past two lakes and a canal system. While Hollywood has taught us that toxic sludge is great for superhero origin stories, it’s also technically harmful to water and the German government takes a dim view of environmental pollution. This means we’re not allowed to drive there. So let’s set the shippedHazardousGoods parameter and try this again.

As we can see this means we have to go around. Way around. Still, better safe than sorry, particularly when dealing with toxic sludge. One thing to note: there are some special rules for hazardous goods and tunnels that are only taken into account when you set the tunnelCategory parameter as well. Check out the documentation for additional details.

Before I let you keep on trucking, here are some helpful tips.

• Truck routing always calculates the fastest route, so you can’t use the shortest parameter.
• Truck routing uses truck speed profiles to calculate the time it takes to complete the route. Basically this means that the weight of the truck (as set in the limitedWeight parameter) influences the reported travel time.
• You can also use our Routing Reference Client to experiment with the various routing parameters.
• Never transport toxic sludge and Redback spiders in the same vehicle. The consequences could be catastrophic!
• We have other truck features, too. Check out our truck restrictions map tiles, which show where truck restrictions apply right on the map!
• Finally, remember that truck routing is also available in our JavaScript API and our Mobile SDKs for Android and iOS.

Happy trucking!