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:
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.
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
.