Get partition metadata

Partition metadata consists of information about the partition such as a partition's data handle, ID, version, and the name of the layer that contains the partition. You need the partition metadata in order to read data from a layer because the metadata contains the partition's data handle.

There are two ways to get partition metadata:

• Get the metadata for all partitions in a layer using the metadata v1 API.
• Get partition metadata for one or more specific partitions using the query v1 API.

For performance reasons, it is best to use query only for getting metadata for a specific partition, like you would in an interactive process. For batch processes, and for getting metadata for many partitions or all partitions in a layer, use metadata.

The following sections provide an overview of how to use these APIs to get partition metadata. For complete information on using these APIs, see the API Reference.

Getting metadata for all partitions in a layer

1. Obtain an authorization token. For more information, see the Identity & Access Management Guide.
2. Get the catalog configuration metadata for the catalog containing the partition. Catalog metadata consists of the catalog ID, the layer ID, and, the version of the catalog (for versioned layers only). For information on getting a catalog's configuration metadata, see Get catalog and layer metadata.
3. Use the API Lookup service to get the API endpoint for the metadata v1 API for the catalog HRN. For instructions, see the API Lookup Developer's Guide.
4. Use the metadata API to get the partition metadata for all partitions in the layer:

   GET /<Base path for the metadata API from the API Lookup Service>/layers/<Layer ID>/partitions?version=<Catalog Version> HTTP/1.1
   Host: <Hostname for the metadata API from the API Lookup Service>
   Authorization: Bearer <Authorization Token>
   Cache-Control: no-cache
   

   The service returns a list of all the partitions in the layer for the requested version of the catalog (for versioned layers) or for the latest data (volatile layers). For volatile layers, the version field typically contains 0 but can contain other versions.

   {
    "partitions": [
        {
            "version": <Partition Version>,
            "partition": "<Partition ID>",
            "dataHandle": "<Data Handle>"
        },
        {
            "version": <Partition Version>,
            "partition": "<Partition ID>",
            "dataHandle": "<Data Handle>"
        },
        {
            "version": <Partition Version>,
            "partition": "<Partition ID>",
            "dataHandle": "<Data Handle>"
        },
        ...
    ]
   }
   

For complete information on using the metadata API, see the API Reference.

Example

You want to get map data in order to render a map. First, use the metadata API to get all partitions:

GET /metadata/v1/catalogs/catalog-example/layers/layer-example/partitions?version=0 HTTP/1.1
Host: <Base path for the Metadata API from the API Lookup Service>
Authorization: Bearer <Authorization Token>
Cache-Control: no-cache

curl -X GET https://<Base path for the Metadata API from the API Lookup Service>/metadata/v1/catalogs/catalog-example/layers/layer-example/partitions?version=0 \
-H 'Authorization: Bearer <Authorization Token>'
-H 'Cache-Control: no-cache'

The response is:

{
    "partitions": [
        {
            "version": 0,
            "partition": "73982",
            "dataHandle": "73982"
        },
        {
            "version": 0,
            "partition": "73983",
            "dataHandle": "73983"
        },
        {
            "version": 0,
            "partition": "74147",
            "dataHandle": "74147"
        },
        ...

Note that only the first three partitions are listed in the example response.

Getting partition metadata for a single partition

1. Obtain an authorization token. For more information, see the Identity & Access Management Guide.
2. Get the catalog configuration metadata for the catalog containing the partition. Catalog metadata consists of the catalog ID, the layer ID, and, the version of the catalog (for versioned layers only). For information on getting a catalog's configuration metadata, see Get catalog and layer metadata.
3. Use the API Lookup service to get the API endpoint for the query v1 API for the catalog HRN
4. Use the query API to get the metadata for the partition you want. You can specify multiple partition parameters.

   GET /<Base path for the query API from the API Lookup Service>/layers/<Layer ID>/partitions?version=<Catalog Version>&amp;partition=<Partition ID> HTTP/1.1
   Host: <Hostname for the query API from the API Lookup Service>
   Authorization: Bearer <Authorization Token>
   Cache-Control: no-cache
   

   The service returns the metadata for the partitions you requested:

   {
    "partitions": [
        {
            "version": "<Partition Version>",
            "partition": "<Partition ID>",
            "dataHandle": "<Data Handle>"
        }
    ]
   }
   

For complete information on using the metadata API, see the API Reference.

Example

You want to get traffic incident data for Berlin from the HERE Real Time Traffic catalog.

First, determine the partition ID that contains the data for Berlin. One way to do this is to use the Data Client Library (available in the HERE platform SDK) which provides a way to calculate the partition ID. You can also use the HERE platform portal to visually navigate the map to find the partition ID of the map tile for Berlin, which is 23618402.

Next, send the partition ID to the query API to get the data handle for the partition:

GET /query/v1/catalogs/xxx/layers/traffic-flow/partitions?version=0&partition=23618402 HTTP/1.1
Host: <Base path for the Query API from the API Lookup Service>
Authorization: Bearer <Authorization Token>
Cache-Control: no-cache

curl -X GET https://<Base path for the Query API from the API Lookup Service>/query/v1/catalogs/xxx/layers/traffic-flow/partitions?version=0&amp;partition=23618402 \
-H 'Authorization: Bearer <Authorization Token>' \
-H 'Cache-Control: no-cache'

The service returns the metadata for the partition, including the partition data handle:

{
    "partitions": [
        {
            "version": 0,
            "partition": "23618402",
            "dataHandle": "23618402"
        }
    ]
}

Finally, use the data handle to get the data from the partition using a request to the blob API.

GET /blob/v1/catalogs/xxx/layers/traffic-flow/data/23618402 HTTP/1.1
Host: blob.data.api.platform.here.com
Authorization: Bearer <Authorization Token>
Cache-Control: no-cache

curl -X GET https://blob.data.api.platform.here.com/blob/v1/catalogs/xxx/layers/traffic-flow/data/23618402 \
-H 'Authorization: Bearer <Authorization Token>' \
-H 'Cache-Control: no-cache'

The blob API returns a data blob containing the traffic incident data for the partition containing Berlin.