Hands on

Using the HERE Geocoder API with cURL and Postman

By Nic Raboy | 26 September 2018

If you’ve been keeping up with my tutorials, you’ll remember that I’ve written about Angular, Vue.js, and other development technologies. However, to consume data from the HERE APIs, a particular SDK is not a requirement because at the end of the day, REST is still an option.

We’re going to explore how to use the HERE Geocoder API with popular and quickly available tools such as cURL and Postman.

Creating a Free Developer Account for HERE Application Development

To use the HERE Location Services (HLS), a freemium account is required. As of now, you get 250,000 free requests every month before needing a credit card.

After creating an account, you’ll be able to access a list of your available projects:

here-projects

Don’t worry about the number of projects you have or how many applications you need to connect. I like to think of it as one project per every one application, but feel free to change it up for your needs.

Pick a project, and you should have something that looks like the following:

here-project-tokens

If you haven’t already generated JavaScript / REST tokens, you’ll need to in order to use the HERE APIs. Through the tokens you’ll be able to track usage of the APIs in your applications, including requests made through HTTP.

Consuming Geolocation Data with cURL and the Command Line

There are numerous ways to use a REST API in your application. Most programming languages offer a way to make HTTP requests, but in case you’d rather use scripts or other tooling, we have other options.

cURL is a great option for working with HERE data because cURL is readily available on most operating systems and can be included in shell scripts for reporting or other purposes.

Take the following cURL request for example in the Command Prompt (Windows) or Terminal (Mac and Linux):

curl -X GET \
    https://geocoder.api.here.com/6.2/geocode.json?app_id=<APP-ID-HERE>&app_code=<APP-CODE-HERE>&searchtext=Tracy+CA

The app_id and app_code should be replaced with the values found in your developer account, but the searchtext is the address information you want to search for. Running the above query will give you results similar to the following:

{
    "Response": {
        "MetaInfo": {
            "Timestamp": "2018-09-24T21:10:29.219+0000"
        },
        "View": [
            {
                "Result": [
                    {
                        "Location": {
                            "Address": {
                                "AdditionalData": [
                                    {
                                        "key": "CountryName",
                                        "value": "United States"
                                    },
                                    {
                                        "key": "StateName",
                                        "value": "California"
                                    },
                                    {
                                        "key": "CountyName",
                                        "value": "San Joaquin"
                                    },
                                    {
                                        "key": "PostalCodeType",
                                        "value": "N"
                                    }
                                ],
                                "City": "Tracy",
                                "Country": "USA",
                                "County": "San Joaquin",
                                "Label": "Tracy, CA, United States",
                                "PostalCode": "95376",
                                "State": "CA"
                            },
                            "DisplayPosition": {
                                "Latitude": 37.7397,
                                "Longitude": -121.42641
                            },
                            "LocationId": "NT_xAlrGP4IQF8iid.6Qry-PA",
                            "LocationType": "point",
                            "MapView": {
                                "BottomRight": {
                                    "Latitude": 37.67872,
                                    "Longitude": -121.38
                                },
                                "TopLeft": {
                                    "Latitude": 37.77642,
                                    "Longitude": -121.54868
                                }
                            },
                            "NavigationPosition": [
                                {
                                    "Latitude": 37.7397,
                                    "Longitude": -121.42641
                                }
                            ]
                        },
                        "MatchLevel": "city",
                        "MatchQuality": {
                            "City": 1.0,
                            "State": 1.0
                        },
                        "Relevance": 1.0
                    }
                ],
                "ViewId": 0,
                "_type": "SearchResultsViewType"
            }
        ]
    }
}

A lot of information came back, but probably some of the most useful is in the Response.View[].Result[].Location path as it took a very vague search query and gathered information about the country, postal code, latitude, and longitude.

A little tip, if you have Python installed, you can format your JSON response rather than getting a mashed mess. Execute the command below to see it in action:

curl -X GET \
    https://geocoder.api.here.com/6.2/geocode.json?app_id=<APP-ID-HERE>&app_code=<APP-CODE-HERE>&searchtext=Tracy+CA | python -m json.tool

The above command pipes the API response into Python and then the result is pretty printed.

In terms of using the HERE Geocoder API, some results may be more complicated than what I had demonstrated with my “Tracy CA” query. For example, multiple results could be returned for a particular query, where in my example, only one result was returned. The more specific you are with the query, the fewer results will be returned.

While cURL is a great tool for making requests to the HERE API, it isn’t the only thing available.

Using Postman with the HERE REST API

Postman is a very popular tool amongst developers because of how easy it is to generate requests using a very easy to understand interface. Let’s take a look at that same request that we made with cURL, but this time with Postman.

here-geocoder-postman

In the above image you’ll notice that the request is set to GET and the URL to the API is provided. For the parameters, each parameter can be entered without having to manually construct the URL that we saw in cURL. While not terribly complicated, it does make life significantly simpler.

Postman does allow you to keep track of previously ran requests or save them as favorites to be executed at a later time.

Conclusion

There is no wrong way (at least to my knowledge), when it comes to making HTTP requests against the HERE APIs. It all comes down to the requirement of the task and the preference. For example, using Postman probably isn’t an option if you need to script something on a scheduler. Also you probably wouldn’t use cURL or Postman in your applications that use JavaScript or another programming technology.

Pick the right tool for the job, but know that it isn’t difficult to make HTTP requests against any of the HERE APIs, including the HERE Geocoder API.