Tutorials / Using the Reverse Geocoding API with Postman
Last Updated: August 31, 2020
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:
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.
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.
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.