Migrate from HERE Places (Search) API to HERE Geocoding and Search v7

HERE Geocoding and Search v7 provides increased POI coverage and a higher cadence of data updates. In addition, HERE Geocoding and Search v7 offers a simplified API that integrates the features of both the "HERE Places (Search) API" and "HERE Geocoder API" products.

HERE Places (Search) API is currently in Maintenance.

In this document, we will use the following shorter names:

"Places API" for "HERE Places (Search) API"
"GS7" for "HERE Geocoding and Search v7"

Changes Overview

The following general actions must be taken to complete the migration:

understand conceptual changes: Base URLs, services, endpoints, headers, location context, result types
adapt or change authentication method
update request parameters and output format for each entrypoint used

Note

There are some input as well as output parameters that are no longer supported due to conceptual changes. These are detailed in this guide.

Naming

Places API and GS7 use different names for similar concepts:

Places API	GS7	note
"Entrypoint"	"Service"	See below from Entrypoints to Services
"resource"	"endpoint"
Entrypoint "parameter"	endpoint query "parameter"
"Media Type"	"response element"
Media Type "attribute"	"response element"

base URL

Places API is accessible via URLs depending on both target segments and authorization method:

Base URL	Variant	Authorization method
`https://places.ls.hereapi.com`	Public, Automotive	Oauth2 or API key
`https://places.api.here.com`	Public	app_id/app_code
`https://places.cc.api.here.com`	Automotive	app_id/app_code

GS7 related URLs are not based on target segments nor authorization methods, but on the general concept of HERE platform "Service". A "Service" corresponds to what is known in Places API as an "Entrypoint".

HERE platform Service domain names comply to the schema [service].[product].hereapi.com.

GS7 product part is search, so that the base URLs to migrate follows the schema https://[service].search.hereapi.com.

There are 4 services in GS7 corresponding to the Places API entrypoints. Those are Discover, Browse, Autosuggest and Lookup. All service are authorized through either a Oauth token or an API Key. So that the base URLs in are:

Base URL	Service	Authorization method
`https://autosuggest.search.hereapi.com`	Autosuggest Service	Oauth2 or API key
`https://discover.search.hereapi.com`	Discover Service	Oauth2 or API key
`https://browse.search.hereapi.com`	Browse Service	Oauth2 or API key
`https://lookup.search.hereapi.com`	Lookup Service	Oauth2 or API key

from Entrypoints to Services

The mapping below summarizes how Places API entrypoints corresponds to GS7 services.

Places API Entrypoint	GS7 equivalence	status	Comment
Autosuggest Entrypoint	Autosuggest Service	available
Search Entrypoint	Discover Service	available
Browse Entrypoint	Browse Service	available
Lookup Entrypoint	Lookup Service	available
Explore Entrypoint	Browse Service	partly	A service comparable to the Places API entrypoint is not currently available. Please note that the GS7 Browse Service may fulfill your needs. If not, please contact GS7 Management.
Browse by Corridor Entrypoint	Browse Service	available
Suggest Entrypoint	Autosuggest Service	available	The Suggest Entrypoint was deprecated in Places API. See Entrypoint maturity.
Here Entrypoint	Browse Service	available	The Here Entrypoint was deprecated in Places API. See Entrypoint maturity.
Around Entrypoint	Browse Service	available	The Around Entrypoint was deprecated in Places API. See Entrypoint maturity.
Place Categories Entrypoint		currently not available	A GS7 service comparable to the Places Categories is not currently available. Check Categories list in Developer Guide for details about GS7 supported places categories.
Cuisine Categories Entrypoint		currently not available	A GS7 service comparable to the Places Cuisines is not currently available. Food-Types list in Developer Guide for details about GS7 supported places cuisines.
Actions Entrypoint		currently not available
Health Entrypoint		currently not available
Corridor Shortener Entrypoint	(none)	out of scope	Simplification described in Developer Guide
Browse-Pt-Stops Entrypoint	(none)	out of scope	Please use HERE Public Transit API.

Paths

Technically each Places API entrypoint and GS7 service is mapped to a REST API endpoint resource. Below is a subset of the different endpoint resource paths used in both products:

Product	Entrypoint	Places API Base URL	Places API Version	Places API Resource path
Places API	Search	`https://places.ls.hereapi.com`(*)	`/places/v1`	`/discover/search`
Places API	Autosuggest	`https://places.ls.hereapi.com`(*)	`/places/v1`	`/autosuggest`
Places API	Browse	`https://places.ls.hereapi.com`(*)	`/places/v1`	`/browse`
Places API	Lookup	`https://places.ls.hereapi.com`(*)	`/places/v1`	`/lookup`

Product	Service	GS7 Base URL	GS7 Version	GS7 Endpoint path
GS7	Autosuggest	`https://autosuggest.search.hereapi.com`	`/v1`	`/autosuggest`
GS7	Discover	`https://discover.search.hereapi.com`	`/v1`	`/discover`
GS7	Browse	`https://browse.search.hereapi.com`	`/v1`	`/browse`
GS7	Lookup	`https://lookup.search.hereapi.com`	`/v1`	`/lookup`

(*) also https://places.api.here.com and https://places.cc.api.here.com.

Migrate from HERE Places API to HERE Geocoding and Search API