Get started with the REST API

The HERE Workspace provides REST APIs for:

• Reading and writing data to catalogs
• Managing catalogs
• Managing data processing pipelines

The Data API consists of the APIs listed in this API Reference.

The Pipelines API consists of the APIs listed in this API Reference.

Get credentials

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:

~/.here/credentials.properties

For more information about obtaining a credentials.properties file, see the Identity & Access Management Guide.

Look up base URLs for HERE APIs

Use the api-lookup service to get the base URLs of all the HERE APIs. HERE APIs are those that are not tied to a specific catalog or pipeline. To get a list of all HERE 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 HERE 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.

Read data from a catalog

A good way to try out the REST API is to use it to read data from a catalog. In this example, you will read data from a catalog containing the location of potholes in downtown Chicago.

First, get an authorization token. The simplest way to get an authorization token is to use the HERE Authorization, Authentication, and Accounting SDK. This SDK includes a sample application that you can use to request tokens. You can access the Authorization, Authentication and Accounting SDK on GitHub. See the readme for instructions on compiling and running the sample application.

Once you have a token, make this request to get the data handles for the partitions in the catalog, specifying your authorization token in the Authorization header where indicated:

GET /metadata/v1/catalogs/chicago-rivernorth-biking-demo/layers/pothole-data/partitions?version=1 HTTP/1.1
Host: metadata.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://metadata.data.api.platform.here.com/metadata/v1/catalogs/chicago-rivernorth-biking-demo/layers/pothole-data/partitions?version=1

The response is a listing of the partitions in the layer:

{
    "partitions": [
        {
            "version": 0,
            "partition": "321535565",
            "layer": "pothole-data",
            "dataHandle": "9cc994e9-e684-48b5-a116-f6dd578edcd9"
        },
        {
            "version": 0,
            "partition": "321535576",
            "layer": "pothole-data",
            "dataHandle": "067de87d-1637-4987-be0d-80ceb96e3f5a"
        },
        {
            "version": 0,
            "partition": "321535577",
            "layer": "pothole-data",
            "dataHandle": "657dee99-7b36-4bd1-9a77-f98b7e0d0f11"
        }
    ]
}

Each partition represents a geographic area in Chicago. You can view the partitions on a map in the portal using the inspect feature. The three rectangles represent the three partitions returned above.

Now that you have a list of the partitions you can use the blob API to read the data from a partition using this request:

GET /blobstore/v1/catalogs/chicago-rivernorth-biking-demo/layers/pothole-data/data/9cc994e9-e684-48b5-a116-f6dd578edcd9 HTTP/1.1
Host: blobstore.data.api.platform.here.com
Authorization: Bearer <Authorization Token>
Cache-Control: no-cache

curl -X GET
  https://blobstore.data.api.platform.here.com/blobstore/v1/catalogs/chicago-rivernorth-biking-demo/layers/pothole-data/data/9cc994e9-e684-48b5-a116-f6dd578edcd9
  -H "Authorization: Bearer <Authorization Token>"
  -H "Cache-Control: no-cache"

The response contains the binary data from the partition.

Learn more

To learn more about the REST APIs for data and pipelines, see:

• The Pipelines Developer's Guide
• The Data Developer's Guide