Introduction
The export tasks are used to retrieve data from the backend servers. Therefore some values in the Export Task data fields (e.g. Asset Odometers, Analog values) may differ on the UI to the raw value. For example the odometer value in the export task may be from the device (odometer), or a counter value (odo_counter), not the asset value. This, plus any other value in the Export Task, should be compensated with offsets/calculations for the Export Task raw data.
When a GET is performed, the data is removed automatically from the queue. However, if a DEL is not sent, the data will be sent again after a couple of minutes.
When a DEL is performed, the data is permanently removed from the queue.
If data is not available, or the incorrect reference/ID is used, a “500” error will be returned. The task uses a long poll process, and if there is no data in the queue, will wait up to 45 seconds before responding. If data is added to the queue during the delay, this will be sent out before the end of the 45 seconds. If there is no data within 45 seconds, then a “500” error is returned.
V1 versus V2 (Configured on the UI Export Task)
The V2 documentation has recently been added. There are two sets of documents available, for V1 and for V2. Either of these will work, but there are a few differences, and the correct documentation in relation to the version needs to be used and referenced.
V1 will continue working, but it is recommended that any new Exports Tasks are configured on the UI to V2 documentation. The differences are as follows:
For export tasks that have been configured using the Key Telematics software, there are two possible output formats. The legacy format matches the data from our V1 API, and the latest V2 format matches the output from our V2 Fleet API.
V1 (Legacy)
The legacy data format has the following common conventions:
- All dates and times are GMT+0 in the format "YYYY/MM/dd HH:MM:SS", i.e. "2019/09/26 07:58:30"
- All measurements are in metric unless otherwise noted
- Longitude and Latitude are in milliarcseconds
- Links to API entities (i.e. clients, devices or assets) are simple UUIDs
Telemetry
The telemetry record is created for every positional message received from a device. It contains the GPS locational information along with the states of all inputs.
Documentation for V1 Legacy can be found here:
Please see examples in attachment: "Export Data Formats"
V2 (Latest)
The latest data format has the following common conventions:
- All dates and times are GMT+0 in ISO format, i.e. "2019-09-26T07:58:30.996Z"
- All measurements are in metric format unless otherwise noted
- Longitude and Latitude are in decimal degrees
- Links to API entities (i.e. clients, devices or assets) are usually a IdName type containing the entities ID and name, i.e. { id: "d4d5627b-f436-4d87-a26d-057d56d23695", name: "Example" }
The V2 formats match those of the Fleet API routes. Documentation for that can be found in the Fleet API Documentation here:
Fleet API Specification | API Reference (keytelematics.com)
For Examples and Samples, please refer to the following document:
https://github.com/keytelematics/fleet-api-sample/blob/main/src/push.ts#L31-L48
Documentation
As above, documentation for V1 and V2 Export Tasks can be viewed here:
V2: Fleet API Specification | API Reference (keytelematics.com)
Authentication
The API key must be sent with every request as either a query parameter or an HTTP header.
Query Parameter (token)
A query parameter called token must be added containing the API Key.
Text
Please confirm with your User Interface Administrators whether eu1, us1 or uk1 is to be used in the query above.
HTTP Header (x-access-token)
A header must be added called x-access-token containing the API Key.
Text
Retrieving Data
The first step in retrieving data from the API is to perform the GET operation. If there is data available in the queue of the HTTP Export Task, it will be returned in the response. The ID that accompanies the GET response should be used with the DEL operation in order to remove the processed data from the queue.
If the DEL operation is not used within 2 minutes of the corresponding GET, the data will be added back to the queue and will be available for subsequent GET operations. One has to GET and DEL constantly to work through the queue.
Additional Options
Compression
The HTTP Export Task supports gzip compression of its responses. This can be enabled by adding the “accept-encoding” header to the request.
Text
Keep Alive
The HTTP Export Task supports HTTP Keep-alive allowing for subsequent queries to be significantly faster, as existing connections are reused. This can be enabled by adding the ‘connection’ header to the request. This must be used in conjunction with a client that supports the reuse of HTTP connections.
HTML
Examples
The following are examples of using and deleting data with curl:
Was this article helpful?
That’s Great!
Thank you for your feedback
Sorry! We couldn't be helpful
Thank you for your feedback
Feedback sent
We appreciate your effort and will try to fix the article