Difference between parameters

Introduction

There are many endpoints supported by HERE Geocoding & Search API v7

Discover
Geocoder
Autocomplete
Autosuggest
Reverse Geocode
Lookup
Browse

This video outlines the use of /geocode endpoint and helps the user to migrate from HERE Geocoder API 6.2

As you all know, the HERE Geocoder API 6.2 is no longer being actively developed.

Instead, we recommend using the new HERE Geocoding and Search API v7 service. The new HERE Geocoding & Search API v7 is also addressed as GS7.

The /geocode endpoint is used to find the geo- coordinates of a known address, place, locality or administrative area, even if the query is incomplete or partly incorrect. It also returns a complete postal address string and address details.

Who/Why to Migrate?

HERE Geocoding and Search v7 aligns former Geocoding and Places/Search APIs into one simplified API that integrates the features of both. In addition, expect

Increased POI coverage by up to 50%.
Fresher Places and address data due to a much higher update frequency.
New feature places geocoding that improves accuracy and match rate: geocoding now recognizes POIs, matches them, and returns the address and a matching place.

The users who are currently using the HERE Geocoder API 6.2 or HERE Search API should migrate to GS7 as it offers a simplified API, integrating the features of both the "HERE Geocoder API 6.2" and "HERE Search API" products.

Valid Authentication Types for GS7

GS7 introduces a new way to authenticate the application. Instead of using the Appid/Appcode combination, you must use the API Key or OAuth 2.0 token authentication methods for improved security. App code credentials are now on the verge of deprecation as they are the least secure of the authentication credential types.

HERE ensures that you will have sufficient time for the upgrade once the new service versions are available.

Register on HERE platform for ApiKey

HERE API keys provide simple and secure authentication of your application. Utilize the API key credentials key-rotation feature to ensure continued security of your application over time. This is done by creating a second API key for your application and deleting the original key when it is no longer required. You can use a maximum of two API keys at once for each application.

Step 1: Register your app

If you don't already have a HERE account, see Get a HERE account.
Sign in to the HERE platform.
Open the Access Manager from the Launcher.
On the Apps tab, click Register new app and provide the requested information.
Click Register. The platform creates a new app with a unique app ID.
On the Credentials tab, select API Keys and then click Create API key to generate a maximum of two API Keys for your application authentication credentials. The API key is created and displayed.

Step 2: Get an API key

Sign in to the HERE platform.
Open the Access Manager from the Launcher.
On the Apps tab, click the app you created in Step 1 or an existing app for which you want to generate an API key and provide the requested information.
On the Credentials tab, select API Keys and then click Create API key to generate a maximum of two API Keys for your application authentication credentials. The API key is created and displayed.

Upgrade Guide

Before going forward we recommend to use our Upgrade Guide which has all the minute details that will help you with upgrade.

While constructing the request for /geocode endpoint, make sure you change the base url, version and resource as shown in the comparison table below.

There are changes in the query parameters and responses too. Please refer to the upgrade guide to get complete knowledge of the required changes. Our upgrade guide also provides information on what is not supported in GS7.

Geocoder 6.2 Request & Response to geocode an address:

Request:

GET https://geocoder.ls.hereapi.com/6.2/geocode.json?searchtext=425+W+Randolph+Chicago&apiKey={YOUR_API_KEY}

Response:

{
"Response": {
"MetaInfo": {
"Timestamp": "2022-09-19T10:25:52.355+0000"
},
"View": [
{
"_type": "SearchResultsViewType",
"ViewId": 0,
"Result": [
{
"Relevance": 1,
"MatchLevel": "houseNumber",
"MatchQuality": {
"City": 1,
"Street": [
0.9
],
"HouseNumber": 1
},
"MatchType": "pointAddress",
"Location": {
"LocationId": "NT_Opil2LPZVRLZjlWNLJQuWB_0ITN",
"LocationType": "point",
"DisplayPosition": {
"Latitude": 41.88432,
"Longitude": -87.63877
},
"NavigationPosition": [
{
"Latitude": 41.88449,
"Longitude": -87.63877
}
],
"MapView": {
"TopLeft": {
"Latitude": 41.8854442,
"Longitude": -87.64028
},
"BottomRight": {
"Latitude": 41.8831958,
"Longitude": -87.63726
}
},
"Address": {
"Label": "425 W Randolph St, Chicago, IL 60606, United States",
"Country": "USA",
"State": "IL",
"County": "Cook",
"City": "Chicago",
"District": "West Loop",
"Street": "W Randolph St",
"HouseNumber": "425",
"PostalCode": "60606",
"AdditionalData": [
{
"value": "United States",
"key": "CountryName"
},
{
"value": "Illinois",
"key": "StateName"
},
{
"value": "Cook",
"key": "CountyName"
},
{
"value": "N",
"key": "PostalCodeType"
}
]
}
}
}
]
}
]
}
}

GS7 Request & Response to geocode an address:

Request:

GET https://geocode.search.hereapi.com/v1/geocode?q=425+W+Randolph+Chicago&apiKey={YOUR_API_KEY}

Response:

{
"items": [
{
"title": "425 W Randolph St, Chicago, IL 60606-1506, United States",
"id": "here:af:streetsection:hdZ6xBRUraY46IQZCqZidD:CgcIBCDMlOElEAEaAzQyNQ",
"resultType": "houseNumber",
"houseNumberType": "PA",
"address": {
"label": "425 W Randolph St, Chicago, IL 60606-1506, United States",
"countryCode": "USA",
"countryName": "United States",
"stateCode": "IL",
"state": "Illinois",
"county": "Cook",
"city": "Chicago",
"district": "West Loop",
"street": "W Randolph St",
"postalCode": "60606-1506",
"houseNumber": "425"
},
"position": {
"lat": 41.88432,
"lng": -87.63877
},
"access": [
{
"lat": 41.88449,
"lng": -87.63877
}
],
"mapView": {
"west": -87.63998,
"south": 41.88342,
"east": -87.63756,
"north": 41.88522
},
"scoring": {
"queryScore": 0.99,
"fieldScore": {
"city": 1.0,
"streets": [
0.9
],
"houseNumber": 1.0
}
}
}
]
}

GS7 response includes geo-coordinates of the address and complete postal address string with correct postal code.

resultType -HERE Geocoding and Search /geocode is able to return items of several types: houseNumber, place, locality, street, administrativeArea, addressBlock, intersection, postalCodePoint.
title -a representative string for the result. In case of address it is the complete postal address string.
address -the detailed address of the result.
position -a representative geo-position (WGS 84) of the result. This is to be used to display the result on a map.
access -the geo-position of the access to the result (for instance the entrance).
mapView -bounding box of the location optimized for display.
scoring -the /geocode endpoint returns scoring information, which indicates for each result how good it matches to the original query. This can be used by the customer application to accept or reject the results depending on how “expensive” is the mistake for their use case.
id -the identifier of the result object. Its value can be used to retrieve the very same object through the /lookup endpoint.

As compared to Geocoder 6.2 response, GS7 response does not include metainfo, does not have additional level of view, does not support location additional data.

The location id of HERE Geocoder API 6.2 and id of GS7 have different formats and are not compatible.

When geocoding an area, please note that access position is not included in the area result.

When geocoding a place, you need to provide a location context to make the geocode endpoint work, the result will show the category and foodtypes elements too.

When using spatial reference, the response will provide “distance” field, which is the distance in meters from the “at” position to the result.

Helpful Links (/geocode)

Generic Resources

Important place to visit for all other generic help.