Upload and download a large data

If a device collects large amounts of data, the data can be uploaded into the Tracking Backend via the Tracking API as a large data blob. The user can later download the uploaded data from the Tracking API. The data upload is done by a device, and the data download is done by the user.

Prerequisites

A valid HERE account user
A valid Tracking project
A claimed device

Log in device

Log in user

Upload a large data

Upload process has three phases: creating a new upload, uploading parts of the data and, once all the data parts have been uploaded, completing the data upload.

Create a new large data upload

curl -X POST \
  'https://tracking.api.here.com/largedata/v4' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {deviceToken}' \
  -d '{
  "name":"My large data",
  "description":"Description for my large data"
}'

This will return dataId which is the identifier for the large data.

{
  "dataId": "DATA-dummyDataId"
}

Check the status of the large data upload creation

When the first large data upload for a project was created, it will take some time to setup the data storage. Make the following request to get metadata for the large data and check the upload creation status:

curl -X GET \
  'https://tracking.api.here.com/largedata/v4/{dataId}/metadata' \
  -H 'Authorization: Bearer {userToken}'

The metadata contains information such as a status of the upload, number of parts and a size of the whole large data:

{
  "dataId": "DATA-dummyDataId",
  "trackingId": "HERE-dummyHereId",
  "name": "My large data",
  "description": "Description for my large data",
  "numberOfParts": 2,
  "size": 6,
  "status": "completed",
  "createdAt": "2021-06-24T08:27:53.933Z",
  "completedAt": "2021-06-24T08:29:08.966Z"
}

Only when the status is no longer preparing, the user can continue with uploading the data parts. Otherwise, in case the data storage for the upload is still being created, an upload data part request will return 409 error code.

Upload a part of a large data

In the example below a data file called mylargedata1.bin is uploaded as part 1, and then another file called mylargedata2.bin is uploaded as part 2. This can be done in parallel. If the user uses the same part number in a subsequent request, the new upload will override the old one.

curl -X PUT \
  'https://tracking.api.here.com/largedata/v4/{dataId}/parts/1' \
  -H 'Content-Type: application/octet-stream' \
  -H 'Authorization: Bearer {deviceToken}' \
  --data-binary '@mylargedata1.bin'

curl -X PUT \
  'https://tracking.api.here.com/largedata/v4/{dataId}/parts/2' \
  -H 'Content-Type: application/octet-stream' \
  -H 'Authorization: Bearer {deviceToken}' \
  --data-binary '@mylargedata2.bin'

Complete a large data upload

Once the user has successfully uploaded all the parts of the large data, the upload must be completed. Once the upload has been completed, it is no longer possible to override parts or upload new parts of the large data.

curl -X POST \
  'https://tracking.api.here.com/largedata/v4/{dataId}' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {deviceToken}'

Download large data

Suppose that the first part of our example contained a word my and the second part contained a word data.

curl -X GET \
  'https://tracking.api.here.com/largedata/v4/{dataId}/data' \
  -H 'Accept: application/json, application/octet-stream' \
  -H 'Authorization: Bearer {userToken}'

This will return a word mydata, as the part 1 my and the part 2 data have been concatenated.

curl -X GET \
  'https://tracking.api.here.com/largedata/v4/{dataId}/data?offset=1&count=3' \
  -H 'Accept: application/json, application/octet-stream' \
  -H 'Authorization: Bearer {userToken}'

This will return a word yda as the offset is 1 and the count is 3. The offset moves the starting point forward by the specified number of bytes and the count tells how many bytes of data to get from the offset onwards.

Delete a large data

curl -X DELETE \
  'https://tracking.api.here.com/largedata/v4/{dataId}' \
  -H 'Authorization: Bearer {userToken}'

Get parts information listing for a large data

The user can get a detailed information and the upload status on each of the large data parts.

curl -X GET \
  'https://tracking.api.here.com/largedata/v4/{dataId}/parts' \
  -H 'Authorization: Bearer {userToken}'

{
  "limit": 100,
  "count": 2,
  "items": [
    {
      "partNumber": 1,
      "size": 2,
      "md5": "6864f389d9876436bc8778ff071d1b6c",
      "status": "completed"
    },
    {
      "partNumber": 2,
      "size": 4,
      "md5": "8d777f385d3dfec8815d20f7496026dc",
      "status": "completed"
    }
  ]
}

Get metadata listing for all large data for a device

The device trackingId needs to be specified in the request path to get metadata for all the large data objects for a given device.

curl -X \
  GET 'https://tracking.api.here.com/largedata/v4/devices/{trackingId}/metadata' \
  -H 'Authorization: Bearer {userToken}'

{
  "limit": 100,
  "count": 1,
  "items": [
    {
      "dataId": "DATA-dummyDataId",
      "trackingId": "HERE-dummyHereId",
      "name": "My large data",
      "description": "Description for my large data",
      "numberOfParts": 2,
      "size": 6,
      "status": "completed",
      "createdAt": "2021-06-24T08:27:53.933Z",
      "completedAt": "2021-06-24T08:29:08.966Z"
    }
  ]
}

Upload and download large data