Get data from a volatile layer

You can get data from a volatile layer by getting all the partitions for a layer, or by querying the layer for specific partitions or partitions that have changed in a given time frame.

Note

The use of the blob v1 API for getting data from a volatile layer is deprecated in favor of volatile-blob v1.

The typical flow for getting data consists of the following steps.

  1. Obtain an authorization token
  2. Get API base URLs
  3. Get the data handle
  4. Get partition data

Obtain an authorization token

Obtain an authorization token for your HTTP requests. For instructions, see the Identity & Access Management Guide.

Get API base URLs

Use the API Lookup service to get the API endpoints for the APIs for the catalog you want to get data from. For instructions, see the API Lookup Developer's Guide.

Get the data handle

In order to get data from the layer, you must know the data handle of the partition that contains the data you want. How you get the data handle depends on which data you want to get.

Note

You may already know the data handle of the partition you want. If so, skip this step. For example, if the layer you are getting data from uses HERE tile partitioning and the data handle is a HERE Tile ID, you may already know the partition ID of the tile you want, and you can use this ID to get data without having to look up the ID. You can also avoid needing to look up the data handle by caching the results from the metadata response. You may need to re-read the layer's metadata if new partitions are added or existing partitions are removed.

To get all partitions in a layer, use the metadata API to get partition metadata from the layer:

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

To get all changed partitions, use the metadata API and specify a time range using the sinceTime parameter.

GET /<Base path for the metadata API from the API Lookup Service>/layers/<Layer ID>/changes?sinceTime=<Epoch Seconds> HTTP/1.1
Host: <Hostname for the metadata API from the API Lookup Service>
Authorization: Bearer <Authorization Token>
Cache-Control: no-cache

If a partition's metadata has changed since the time provided and its data has not, it is not included in the response.

To get a partition only if it has changed, use the query API and specify the partition and sinceTime parameters.

GET /<Base path for the query API from the API Lookup Service>/layers/<Layer ID>/changes?partition=<Partition ID>&sinceTime=<Epoch Seconds> HTTP/1.1
Host: <Hostname for the metadata API from the API Lookup Service>
Authorization: Bearer <Authorization Token>
Cache-Control: no-cache

Only partitions that contain changed data are included. If a partition's metadata has changed and its data has not, it is not included in the response.

Response

The response for each of these queries contains an array of partition metadata, including the data handle for each partition. For example:

{
  "partitions": [
    {
      "dataHandle": "1b2ca68f-d4a0-4379-8120-cd025640510c",
      "layer": "my-layer",
      "partition": "314010583",
      "partitionType": "reference",
      "version": 0
    }
  ]
}

Get partition data

In the partition metadata returned by the metadata API, find the data handle of the partition you want. Then, use the data handle to retrieve the data using the volatile-blob API:

GET /<Base path for the volatile-blob API from the API Lookup Service>/layers/<Layer ID>/data/<Data Handle> HTTP/1.1
Host: <Hostname for the volatile-blob API from the API Lookup Service>
Authorization: Bearer <Authorization Token>
Cache-Control: no-cache

The response will consist of the binary data that was uploaded most recently to the given data handle. The data stored at the data handle is volatile so it may change between calls.

Note

We recommend that your application includes retry logic for handling HTTP 5xx errors. Use exponential backoff in the retry logic.

results matching ""

    No results matching ""