Introduction

In this tutorial we are going to give you an introduction to the concept of Geocoding and a hands-on practical exploration of the HERE Geocoding and Search API using Postman.

First up, what is Reverse Geocoding and the differences between Forward and Reverse Geocoding?

Reverse Geocoding is the process of converting geocoordinates (latitude and longitude) to human readable addresses.

Forward Geocoding vs Reverse Geocoding

Forward Geocoding(Geocoding), receives an address as input and then returns the matching latitude and longitude to a particular address. To do this HERE maintains a global database of postal addresses mapped to GPS/GNSS locations. The Forward Geocoding API provides access to this database over the Internet. On the other hand, the process of Reverse Geocoding receives latitude and longitude as input and then returns an address or multiple addresses (should there be multiple addresses at a single position).

Forward Geocoding	Reverse Geocoding
Translate a destination address into latitude and longitudinal coordinates. This is useful when conduction route planning.	Convert the current position (latitude and longitude) of an asset into a postal address. This is useful when trying to understand where an asset is on a map and to visually verify the destination. Additionally, when knowing the current position, you can more easily generate ETAs and routes

We have built a few interactive examples for you to check out for both Geocoding and Reverse Geocoding:

• Geocoding and Search Application
• Reverse Geocoding Application

Forward and Reverse Geocoding are often used in Fleet Management, Connected Driving, and Asset Tracking.

What You’ll Need

For this tutorial you will need a few things to complete the exercises below.

• A Developer Account from developer.here.com.
• Postman

What You’ll Learn

• You will get a quick introduction to the Reverse Geocoding API and its applications.
• You will learn how to work with Reverse Geocoding using Postman.

Reverse Geocoding API and its Applications

To look for an address, you will need to provide geocoordinates to the Reverse Geocoding API endpoint. For example, your application presents a user with a clickable map. When the user clicks on a location on the map, your application interprets the location of the click and then pass the geocoordinates to the revgeocode endpoint and try to obtain a postal address.

Since we don’t have an application, we have chosen some coordinates for you to use and pass manually to the Reverse Geocoding API. Long Island City - Latitude: 40.730610 - Longitude: -73.935242

Below is an example implementation of the Reverse Geocoding endpoint where your application has passed the latitude and longitude information for Long Island City to the endpoint. In order to make this request, you will also need to replace the “YOUR-API-KEY” with the API key obtained from developer.here.com.

https://revgeocode.search.hereapi.com/v1/revgeocode?apikey=YOUR-API-KEY&at=40.730610,-73.935242&lang=en-US

The above API request returns the address in the JSON format.

{
    "items": [
        {
            "title": "38-20 Review Ave, Long Island City, NY 11101, United States",
            "id": "here:af:streetsection:luxVAiVu6grOpILoeMx5lD:CgcIBCDbisQgEAEaBTM4LTIw",
            "resultType": "houseNumber",
            "houseNumberType": "PA",
            "address": {
                "label": "38-20 Review Ave, Long Island City, NY 11101, United States",
                "countryCode": "USA",
                "countryName": "United States",
                "state": "New York",
                "county": "Queens",
                "city": "Long Island City",
                "district": "Sunnyside",
                "street": "Review Ave",
                "postalCode": "11101",
                "houseNumber": "38-20"
            },
            "position": {
                "lat": 40.7309,
                "lng": -73.93551
            },
            "access": [
                {
                    "lat": 40.73142,
                    "lng": -73.93488
                }
            ],
            "distance": 39,
            "mapView": {
                "west": -73.94095,
                "south": 40.72911,
                "east": -73.93019,
                "north": 40.7387
            }
        }
    ]
}

Let’s take a look at the structure of the results. Below is a description of each data element returned by the API.

Items: (Click to Expand)

In the response you will see an “items” array. This is because the position coordinates have varying levels of accuracy based on how many digits the Latitude and Longitude contain. Additionally, there could be multiple addresses at the same position. This could happen if there was a shopping mall or high-raise apartment building.

Title: : (Click to Expand)

The title is a localized description of a result. You can change this by adjusting the “lang” parameter. For example, in our request above we used “en-US” for US English, but we could have passed any one of the BCP47 compliant Language Codes (e.g. “fr” for French or “de” for German).

ID: : (Click to Expand)

This is an identifier unique to HERE Location Services and can also be used to search for a specific location or business.

resultType: : (Click to Expand)

The result type indicates why kind of result was returned from the HERE Database. For example, it could be a specific house number or an administrative region (aka Town or County).

houseNumberType: : (Click to Expand)

The House Number Type is an indicator of whether or not HERE inferred (or Interpolated) an address. For some positions since there are multiple potential results the Reverse Geocoding API will return a list of results sorted by HERE’s best guess first.

Now that we have a good understanding of how to craft a Reverse Geocoding API request and what the API is sending back to us, let’s use Postman to actually execute the request and further explore the API.

Reverse Geocoding using Postman

Let’s explore Reverse Geocode API using postman. To do this, open your Postman application. Create a new GET request. In the URI entry area copy and paste the following reverse geocode endpoint. Make sure to replace the YOUR-API-KEY with your HERE API key.

https://revgeocode.search.hereapi.com/v1/revgeocode?apikey=YOUR-API-KEY&at=40.730610,-73.935242&lang=en-US

Your request should look like the screenshot below:

To send the request, click on the Send button. Check out the screenshot shown below:

In the response you will get the resultType, title, address, position, access, id, distance and mapView.

• resultType - HERE Geocoding and Search supports multiple location object types (place, street, locality, …).
• title - a localized string of the result, this could be the name of a place, or a complete address.
• address - a breakdown of the resulting address into manageable fields.
• position - the geopositioned (latitude and longitude) result; this is to be used to display the result on a map.
• access - the geo-position of the access to the result (aka the main entrance to a building).
• id - the identifier of the item. Its value can be used to retrieve the very same object using the lookup endpoint.
• distance - the distance in meters from the position specified in the query at parameter.
• mapView - bounding box of the location optimized for display. (this is helpful when displaying a map)

Let’s try another request by changing the language parameter to de-de for German language. Check out more documentation on different language support.

https://revgeocode.search.hereapi.com/v1/revgeocode?at=51.1657,10.4515&lang=de-de&apikey=YOUR-API-KEY

Your request should look like below:

To send the request, click on the Send button. Check out the screenshot shown below:

To know even more about the API and parameters, check out this link.

Conclusion

After going through to this tutorial:

• You should have learned what Forward Geocoding and Reverse Geocoding are and when to use them.
• You should have an understanding of the variables the API supports and how to interpret the response returned by the API.
• You should also have a base understanding of how to make requests to the HERE Forward Geocoding API by using Postman.

Next Steps

Now that you have a good understanding of the Reverse Geocoding API, be sure to check out our other tutorials covering topics like Autosuggest (which takes a location as input and returns potential addresses or businesses in from the HERE Database). Finally, if you have a large set of human collected / inputted addresses that you would like to clean up, be sure to check out the Address Cleansing tutorial below to learn how you can use the Geocoding to speed this process up.

• How to Clean Address Data with JavaScript and the HERE Geocoder