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.
Hint
When working with partitions, it is helpful to understand the partitioning schemes used in the HERE platform. For more information, see Partitions.
- Obtain an authorization token. For more information, see the Identity & Access Management Guide.
- 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.
- 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. - 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.
- Obtain an authorization token. For more information, see the Identity & Access Management Guide.
- 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.
- Use the API Lookup service to get the API endpoint for the
query
v1
API for the catalog HRN - 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>&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&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.