Hands On

HERE Fleet Telematics Route Matching API

By Shruti Kuber | 06 September 2019

Often wonder why does the route trace show that your delivery truck drove right through an apartment building? You will find out why and ways to fix it, in the tutorial below

As much as a map is useful during the drive to help you navigate, it is equally useful in giving you insights about your trip once done. Fleet management services use this trip report to not only show where the vehicle traveled, but also information like the time when it reached a certain location, the average speed, driving behaviour, etc. This information is paramount to increase the efficiency of the fleet. While the trace of the route is pretty straight-forward for open roads, the trace of a route where the road is flanked by tall buildings can look like this,

Screen Shot 2019-09-04 at 2.39.48 AM
Raw trace with skewed route


This can happen due to many reasons, where multipath effect due to the surrounding tall buildings is a major contributer. The signals received by the GNSS receiver from the satellites is interrupted by the tall buildings. This signal reflects and follows an alternative path to the receiver. The receiver thus receives two signals , with the same content but at different times. This confuses the receiver and thus it can skew the positon, by a little.

multipath effect Multipath effect

To adjust for this skew in position, a complex algorithm had to be written to snap the vehicle to the nearest possible point on the road. Today it is possible by simply using the HERE Fleet Telematics Route Match API This API is a REST call which reads the raw route and returns a 'cleaned up' version of the route. To use this API, you need an app_id and app_code. If you don't have credentials yet, you can get them by signing up for free at the HERE Developer Portal

We begin by getting the route waypoints in a csv/ gpx format. Make sure that the csv contains columns named 'latitude' and 'longitude'. We then convert this file into a zipped and Base64-encoded format. This can be done using simple online tools like this We do this as the route match API accepts a zipped and Base64-encoded csv/ gpx file as a parameter while calculating the corrected route. The REST call then looks like this:


   GET https://rme.api.here.com/2/matchroute.json?app_id={{YOUR_APP_ID}}&app_code={{YOUR_APP_CODE}}&routemode=truck&file=bGF0aXR1ZGUsbG9uZ2l0dWRlLHRpbWVzdGFtcCxzcGVlZF9rbWgsdmVoaWNsZUlkCjQ4LjEyMTAy
ODkwMDEsLTEuNjg3NzExOTU0MSwyMDE5LTA2LTE2VDEyOjQzOjAzKzAyOjAwLDcuOTEsUm9tYW4n
cyBDYXIgMQo0OC4xMjEwMjUwODU0LC0xLjY4Nzc2OTAzMTUsMjAxOS0wNi0xNlQxMjo0MzowNCsw
MjowMCw4LjIsUm9tYW4ncyBDYXIgMQo0OC4xMjEwMjEyNzA3LC0xLjY4NzgyNjA2MTIsMjAxOS0w
Ni0xNlQxMjo0MzowNSswMjowMCw4Ljc4LFJvbWFuJ3MgQ2FyIDEKNDguMTIwOTk0NTY3OCwtMS42
ODc4NjA5NjU3LDIwMTktMDYtMTZUMTI6NDM6MDYrMDI6MDAsOC45OCxSb21hbidzIENhciAxCjQ4
LjEyMDk2Nzg2NDksLTEuNjg3OTAxMDIsMjAxOS0wNi0xNlQxMjo0MzowNyswMjowMCw4LjgsUm9t
YW4ncyBDYXIgMQo0OC4xMjA5NDg3OTE1LC0xLjY4Nzk1Mzk0ODksMjAxOS0wNi0xNlQxMjo0Mzow
OCswMjowMCwxMC4wLFJvbWFuJ3MgQ2FyIDEKNDguMTIwOTQ0OTc2OCwtMS42ODgwMDIwMTQxLDIw
MTktMDYtMTZUMTI6NDM6MDkrMDI6MDAsMTAuOTgsUm9tYW4ncyBDYXIgMQo0OC4xMjA5Mjk3MTgs
LTEuNjg4MDU3OTk0OCwyMDE5LTA2LTE2VDEyOjQzOjEwKzAyOjAwLDEyLjI2LFJvbWFuJ3MgQ2Fy

Here the parameter file is has the encoded file discussed above. The parameter routemode supports arguements "car, bus, taxi, carHOV, pedestrian, truck, delivery, emergency, motorcycle, roadtrain, custom1, bdouble, bicycle, tractorTruck". The response of this GET call incliudes a JSON object with the original waypoints and linkid. What we are interested in, is the object named TracePoints which contains the latMatched and lonMatched objects which are the matched points corresponding to the given input. You can find details about other parameters in the response here. We can now use the TracePoints.latMatched and TracePoints.lonMatched to draw a polyline within them to display the route.


    var xmlhttp = new XMLHttpRequest();
var points = [];


xmlhttp.onreadystatechange = function() {
  if (this.readyState == 4 && this.status == 200) {
   
    var myObj = JSON.parse(this.responseText);
    var i;
    for (i=0; i < myObj.TracePoints.length; i++){
      points[i] = {"lat": myObj.TracePoints[i].latMatched, "lng": myObj.TracePoints[i].lonMatched};
      
    }
    addPolylineToMap(map, points);
  }
    
  };

  xmlhttp.open("GET", "https://ks.github.io/hosted/route_match_response.json", true);
  xmlhttp.send();


  function addPolylineToMap(map,points) {
    var lineString = new H.geo.LineString();
  
    points.forEach(function(point) {
        lineString.pushPoint(point);
      });
  
      polyline = map.addObject(new H.map.Polyline(
      lineString, { style: { lineWidth: 4 }}
    ));
      
      map.setViewBounds(polyline.getBounds());
  
  }

The url used in this GET request is where I have hosted the JSON response received from the routematch API. You can chose to handle it in any manner. The important part is the plotting of the polyline with the {"lat": myObj.TracePoints[i].latMatched, "lng": myObj.TracePoints[i].lonMatched}. You can plot both the routes side-by-side and see the difference for yourself.

Comparison of raw route with the matched route
Comparison of original route with the matched route

You can now get rid of illogical traces and get clean traces with a simple API. Happy coding!