Upload and download a large data

If a device collects large amounts of data, device can upload it into the HERE Tracking as a large data blob. Then the user can download the data from the HERE Tracking.

Prerequisites

  • A HERE account
  • A valid project
  • A device which has been claimed and logged in device

For the upload a deviceToken is required for authorization of the requests, and then for the other requests a userToken is required. The metadata listing for all data for a device request requires a trackingId of the device.

Upload a large data

Upload process has three phases: creating a new upload, uploading parts of the data, and once all data parts have been uploaded, completion of 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"
}'

Response contains dataId which is the identifier for the large data.

{
  "dataId": "DATA-dummyDataId"
}

Note: when the first large data upload for a project is created, it will take some time to setup the data storage. The device should use the Get metadata for a large data query to check that the upload status is no longer preparing before uploading parts. If the storage for the upload is still being created the response code to upload part request is 409.

Upload a part of a large data

In the request below a binary data file called mylargedata1.bin is uploaded as part 1, and then another file called mylargedata2.bin is uploaded as part 2. These can be done in parallel. If the user uses same part number twice, 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, then 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 contains a word my and the second part 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}'

The response for this query would be mydata as the part 1 my and 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}'

The response for this query would be yda as the offset is 1 and the count 3. So, the offset moves the starting point forwards and the count then tells how much of data to get from that offset onwards.

Delete a large data

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

Get metadata for a large data

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

curl -X GET \
  'https://tracking.api.here.com/largedata/v4/{dataId}/metadata' \
  -H 'Authorization: Bearer {userToken}'
{
  "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"
}

Get parts information listing for a large data

The user can download information listing of the uploaded parts. It includes detailed information and a status of each part which are known to HERE Tracking at the time of the query.

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

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"
    }
  ]
}

results matching ""

    No results matching ""