This topic provides information to help you get started using the Data API, including setup tasks such as getting your credentials and platform APIs.
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.
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 getting or publishing data and creating catalogs.
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:
The Command Line Interface (CLI) 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 Data SDK for Java and Scala, which contains tools to facilitate integration between the various HERE platform component services and other infrastructure-level services like Authentication and Authorization. The Data SDK for Java and Scala 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 Data SDK for Java and Scala. See the Marketplace Consumer User's Guide or the Marketplace Provider User's Guide for information on downloading the Data Client Library.