Hands On

Find Out Which Side of the Road to Drive on Using the HERE Geocoder API

By Richard Süselbeck | 06 May 2019

I’ve been working with the HERE Location APIs for a long time now, but I still keep finding neat new features. For example, you probably knew that you can ask the Geocoder API for the street address of a given location. For example:


https://reverse.geocoder.api.here.com/6.2/reversegeocode.json
?app_id={{app_id}}
&app_code={{app_code}}
&prox=51.50345,-0.12768
&mode=retrieveAddresses
&maxresults=1

One API call and a quick look at the (truncated) response tells us the latlong 51.50345,-0.12768 is at 10 Downing Street in London. (If you want to try this yourself, make sure to sign up for your free set of credentials and replace the app_id and app_code in the request.)


{
    ...
    "Address": {
        "Label": "10 Downing Street, London, SW1A 2AA, United Kingdom",
        "Country": "GBR",
        "State": "England",
        "County": "London",
        "City": "London",
        "District": "Westminster",
        "Street": "Downing Street",
        "HouseNumber": "10",
        "PostalCode": "SW1A 2AA",
        
        ...

    },
    ...
}

But did you also know that you can ask the Geocoder API which side of the road people are driving on in any given location? Well, you can!

To do this, we first need to know that using special parameters we can customize the response of the Geocoder API. This customization allows us to omit information we're not interested in or request additional information that isn’t part of the default response. You can check Customizing the Response in the Geocoder API documentation for full details on these parameters and on which elements you can add and/or omit.

In our case, we are looking for additional information, which is available as part of the AdminInfo attribute in the Location objects of the response. To ensure that this object is added to the response, we need to request it using the parameter locationattributes. This parameter allows us to customize the data of the Location objects in the response. The value AdminInfo indicates that we want this set of information included. (You can omit information by adding a - in front of the value. Try -address for example, to completely omit any address information.)

We already know that people in the UK drive on the wrong left side of the road, so let's try another country. How about Kenya, with a latlong of -1.27397, 36.81459?


https://reverse.geocoder.api.here.com/6.2/reversegeocode.json
?app_id={{app_id}}
&app_code={{app_code}}
&prox=-1.27397,36.81459
&mode=retrieveAddresses
&maxresults=1
&locationattributes=adminInfo
As we can see the response now includes an AdminInfo object with a DrivingSide value of right.

{
   ...
   "AdminInfo": {
        "TimeZoneOffset": "UTC+03:00",
        "LocalTime": "2019-05-03T13:49:06+0300",
        "Currency": "KES",
        "DrivingSide": "left",
        "SystemOfMeasure": "metric"
    }
    ...
}

This tells us that people in Kenya also drive on the left side. (A bad habit presumably picked up from the British.) There’s also some other interesting information, such as the local time, currency and whether metric or imperial measurements are preferred in this location.

Let’s fire up the JavaScript API and build a little tool that allows us to explore the world and find out where people are driving on the right side of the road. We want to be able to click on any place on the map and see a little info box about the country we clicked on. The end result should look something like this.

geocoder-drivingside-screenshot

To build this, we will combine elements from a selection of our JavaScript API examples.

First, we’ll need to set up a basic interactive map. Next, we need to be able to calculate a geographic location from a mouse click. We also need to be able to display the information on the map, for which I’ve chosen SVG Graphics Markers. The most interesting aspect for us is how to use the Geocoder API from within the JavaScript API, so we will look at this in some more detail below. You can check out the complete example in GitHub to see how all these elements work together.

The JavaScript API provides convenient wrappers for the various HERE REST APIs, which means we can simply create a GeocodingService object, pass it the parameters from our REST call above and then initiate a reverse geocode. We also need to provide OnSuccess and OnError callback functions to handle the response. First let's look at how to initiate the geocoding request.


function reverseGeocode(platform) {

    var geocoder = platform.getGeocodingService();  
    var prox = coord.lat + ',' + coord.lng;
    
    var reverseGeocodingParameters = {
        prox: prox,
        mode: 'retrieveAddresses',
        maxresults: '1',
        locationattributes: 'adminInfo'      
    };

    geocoder.reverseGeocode(
        reverseGeocodingParameters,
        onSuccess,
        onError
    );
}

Finally, we can parse the results in the OnSuccess function and format some strings to display in our marker. That's it.


function onSuccess(result) {
    locations = result.Response.View[0].Result;
    country = locations[0].Location.Address.AdditionalData[0].value;  
    adminInfo = locations[0].Location.AdminInfo;    
    localTime = adminInfo.LocalTime.substring(11,16);
    currency = adminInfo.Currency;  
    drivingSide = ((adminInfo.DrivingSide == 'right') ? 'right' : 'left');  
    systemOfMeasure = ((adminInfo.SystemOfMeasure == 'metric') ? 'ml' : 'fl oz');
    
    addAdminInfoMarker(map);
}

Happy Geocoding and safe driving!