The Data API is a REST interface that provides access to data and data management functions. Data consists of maps and location data provided by HERE as well as data provided by HERE platform users. You can bring your own data by creating a catalog then publishing your data to it. You can then share this data with the users you choose.
The Data API consists of the APIs listed in the API Reference.
You may want to use the Data API instead of the Data Client Library if you are programming in a language other than Java or Scala, or if you require more flexibility than the library allows. Using the Data API requires more low-level coding than the Data Client Library.
Get started with the Data API by exploring data, getting a credentials file, getting an authorization token, then discovering APIs and catalogs.
For the terms and conditions covering this documentation, see the HERE Documentation License.
The easiest way to familiarize yourself with data is to explore data using the HERE platform portal. Click Data in the navigation bar to see a list of catalogs and layers that you have permission to access, including HERE data as well as user-provided data that has been shared with you.
A catalog is a collection of data that is logically managed as a single set. Click on a catalog to view its details. The catalog details page presents all the catalog metadata, such as description, tags, data coverage, creation date, HERE Resource Name (HRN), and a list of the layers in the catalog.
A layer is a set of a specific data type, functional property, and structure. You can use layers to segment data based on semantics. For example, a catalog might contain a layer that contains road sign data and another layer containing road topology data.
Each layer is divided into partitions. A partition defines the organization of data in each partition of a layer, both the structure of the data and its content.
To ensure you can reliably connect to the Data API, note the following:
To use the REST API, you need to have a
credentials.properties file. You can obtain this file from platform.here.com. Once you have your credentials properties file, make sure to put it in this folder on your computer:
For more information about obtaining a
credentials.properties file, see the Identity & Access Management Guide.
HERE platform REST requests require an OAuth 2.0 token in the Authorization header to authenticate. To get an authorization token, use the Authentication and Authorization API. For information on using this API, see the Identity & Access Management Guide.
Authorization tokens expire after 24 hours.
api-lookup service to get the base URLs of all the platform APIs. Platform APIs are those that are not tied to a specific catalog. To get a list of all platform APIs, make this request:
GET /lookup/v1/platform/apis HTTP/1.1 Host: api-lookup.data.api.platform.here.com Authorization: Bearer <Authorization Token> Cache-Control: no-cache
curl -X GET -H "Authorization: Bearer <Authorization Token>" -H "Cache-Control: no-cache" https://api-lookup.data.api.platform.here.com/lookup/v1/platform/apis
The response is a list of the platform APIs that you have access to, including their base URLs.
For more information about the
api-lookup API, see the API Lookup Developer's Guide.
Now that you have a list of platform API base URLs from the
api-lookup service, you can use one of the services,
config, to get a list of catalogs available to you. Make the request shown below, specifying the base URL for the
config service that you obtained through the
api-lookup service, and specifying your authorization token in the Authorization header where indicated:
GET /config/v1/catalogs HTTP/1.1 Host: <Hostname for config> Authorization: Bearer <Authorization Token> Cache-Control: no-cache
curl -X GET -H "Authorization: Bearer <Authorization Token>" -H "Cache-Control: no-cache" https://<Hostname for config>/config/v1/catalogs
The response is a listing the catalogs you have access to.
If you have access to tens of thousands of catalogs or more, and it takes the server more than 50 seconds to generate the result, a partial response may be returned. Our testing indicates that a user with permission to access 50000 catalogs takes roughly 50 seconds to generate the result.
In the HERE platform, the base URL for an API is unique for each HERE Resource Name (HRN) served by the API. This means that instead of having static base URLs for each REST API, the HERE platform generates a base URL for each API for every HRN. For example, the base URL for the
publish service for catalog A is different from the base URL for the
publish service for catalog B.
You can obtain the API base URLs for a catalog by using the
api-lookup service, specifying the catalog's HRN where indicated:
GET /lookup/v1/resources/<HRN>/apis HTTP/1.1 Host: api-lookup.data.api.platform.here.com Authorization: Bearer <Authorization Token> Cache-Control: no-cache
curl -X GET -H "Authorization: Bearer <Authorization Token>" -H "Cache-Control: no-cache" https://api-lookup.data.api.platform.here.com/lookup/v1/resources/<HRN>/apis
The response is a list of the APIs for the catalog.
Now that you have discovered the APIs and catalogs available to you, you can perform common tasks such as:
For complete details on the Data API, see the API Reference.
Aside from the REST API, the HERE platform provides other ways of working with data.
The HERE platform portal provides access to basic data management features as well as data visualization. The platform portal is useful for:
For more information, see the Data User Guide.
The command line interface (CLI) is one of the HERE platform SDKs. It offers the same data management functions that are available in the platform portal (such as creating catalogs and layers, listing catalogs and layers, getting metadata), but the OLP CLI enables you to execute these commands in a programmatic way. Further, commands can be stored in scripts so you can run repetitive commands easily without rewriting them from scratch.
The CLI is useful for:
For more information, see the HERE Platform CLI Guide.
You must have the HERE Workspace Plan to access the CLI.
The Data Client Library is a Java/Scala library you can use to read and write data to the HERE platform. It provides a layer of abstraction from the REST APIs which shields you from changes that may occur to HERE platform APIs as they evolve. The Data Client Library also reduces the complexity involved in reading and writing data, reducing the time it takes to add HERE platform data interaction to your applications.
The Data Client Library is part of the HERE platform SDK which contains tools to facilitate integration between the various HERE platform component services and other infrastructure-level services like Authentication and Authorization. The HERE platform SDK helps you focus on designing transformations to meet your business needs rather than writing low-level code.
For more information, see the HERE Workspace for Java and Scala Developers Guide.
If you are a Marketplace user and you do not have the HERE Workspace Plan, you do not have access to the SDK. See the Marketplace Consumer User's Guide or the Marketplace Provider User's Guide for information on downloading the Data Client Library.