The Datamotion Developer Hub

Welcome to the Datamotion developer hub. You'll find comprehensive guides and documentation to help you start working with our embedded services as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    API Reference

Data workflow and categories of data

We describe how different categories of data are processed on the platform and how they can be accessed.

For a basic use case, you will access our platform through the SDK and the APIs, as described in Available Methods and API

Additionally, you can access data in a variety of ways that fit different architectures and use cases. Below we describe how to do this:

Principal schematic of data flows

Three main categories of data: Sensor/GPS, Device Status, and In-Vehicle data

  • GPS and sensor data is the core telematics information processed by our platform and the most important part. All physical and geographic data (location, speed, cornering speed, acceleration) are included in this category.
  • Device Status (Former Heartbeats) is a very basic status updates. They are transmitted about every two hours, and provide information like phone and app status, if tracking enables, how many trips are waiting to be uploaded, etc.
  • In-vehicle Data (not to confuse with sensor data) is data obtained directly from the car's onboard computer via OBD (Add-on Service with Bluetooth OBD). (For most typical applications, this is not required, but it can be a very powerful integration for fleet management solutions that also want to monitor the maintenance information of the vehicle like engine fault codes or time since the last oil change.

Gathered data

  • GPS (1hz) :point-right: Raw Telematics Data Format
  • Data from a gyroscope, magnetometer, and accelerometer (60hz)
  • Data on whether the device is locked and the screen is on

General description of data flow

On the most basic level, telematics data flows from user devices to the Datamotion platform and from there to your own back-end (if you have your own back-end, which is optional). Additionally, you may choose to show data again on the user devices, which is accomplished by accessing the API from your app (not shown above). You can choose to not do that at all (e.g. in fleet apps, where you just collect data), or you can choose to only do that (if you don't have a back-end). This all depends on the architecture of your solution.
Furthermore, you can choose to access raw telematics data directly (Items 1 and 2 above), or you can choose to utilize our processed and enriched data (items 3, 4 and 5 above). This also depends on your setup.
Few solutions will use all options, so some of the details below may not apply to use.

GPS and sensor data: The core datasets of our solution. [Move to own page]

Items 1, 2, and 4 above

In most cases, the raw telematics dataset is not useful, and most applications will take advantage of our ready-to-use processing services that are easily accessible through the various APIs. However, some use cases (basic forensics, advanced behavior scoring, etc.) may benefit from having access to raw telematics datasets to store, process, and analyze the data on your own platform.

Data Processing Workflow for GPS and Sensor data

The SDK continually collects data from the sensors (GPS locations and acceleration events). Out of that data, our SDK creates raw "tracks": A series of locations and events from when the user started driving until they stop and exit the vehicle. This can be trickier than it sounds: For example, did the driver stop at a red light, or did the driver park in a parking spot next to a red light? Did they actually start driving, or did the GPS signal jump locations and it just looked like they are moving at driving speed? Such considerations may result in some invalid tracks, which are removed. Additionally, some tracks can be actively excluded - when a driver is off the clock, outside a certain geofence, or riding as a passenger. These are excluded tracks. Everything that is not invalid or excluded results in raw trips data on our platform. Once these trips are filtered, processed, and enriched, they become processed trips data.

Data samples

For your convenience, we've attached the data from a sample trip (recorded in March 2021 outside Cambridge, UK)

  • Raw Telematics data (notification IncomingTrackReceived) Download JSON file, 1.2 MB
    note that an IncomingTrackRemoved notification technically also links to an object similar to this one, but it will contain little or no useful information, but may be used for troubleshooting if you get many invalid tracks.
  • Processed Trip Data (notification TrackEnrichementFinished) Download JSON file, 341 kB

Data Format Reference

:point-right: Raw Telematics Data Format
:point-right: Processed telematics data format

Data processing workflow for vehicle data

Item 5 in the schematic at the top

Note that this is an advanced and rare use case. For most driver behavior and fleet management use cases, you will not need to use this.

[In-vehicle data collection]](doc:bluetooth-obd) is an advanced feature that is available as an add-on, and it works as follows: The SDK connects through Bluetooth to a so-called OBD (On-Board Diagnostics) device that talks directly to the car's onboard computer to get data like engine failure codes, maintenance status, etc. One example would be to generate a notification when the "Check Engine" light is on.
This feature requires additional hardware :point-right: Bluetooth OBD and communication via Bluetooth, and requires specific knowledge of the make and model of the car. It is most commonly used by fleet apps that actively manage the vehicles and their maintenance.
:point-right: In-vehicle data

In general, vehicle data is handled in a similar fashion to GPS and Sensor data; data is filtered and enriched, and notifications are sent when a new dataset is available.

Device status (former Heartbeats)

Item 3 in the schematic at the top

The SDK also captures permissions & phone status data to support background operation. We call this heartbeats - system information from the mobile device that contains permissions status, device information, and so on.
:point-right: Device Status

Accessing these datasets

Now that we've discussed the main categories of data and how they are processed, let's see how you can access that data. This consists in principle of two steps:
Option API:

  • Get a notification that a new dataset has been processed
  • Access the API to download the data referenced in the notification
    Option Third-party storage
  • Data gets copied by us to your preferred storage provider
  • Get a notification that a new dataset has been copied

Data category

Amazon SNS

Azure (Service Bus or Event Grid)

Offline reporting

Raw sensors data



Raw trips data






Processed trips data




Vehicle data





When a dataset moves from one stage to the next on the Datamotion platform, it creates an event. You can subscribe to those events to then access the relevant data



Notification message doesn't contain any track’s data, such as events or waypoints. To get these details, you have to query the track’s data using the Web API service, using credentials received from SNS Message.

We support several well-known notification services, including Amazon and Azure. Each notification contains URLs, identifiers, and credentials for the respective dataset.



Your back-end or application had to be prepared to receive several notifications related to a single trip. It means the previous version of the track has been updated, and you need to retrieve an updated version from our API again.

An Example where this happens would be that the track was merged with another trip segment. the updated trip will have new trip details (time, distance, etc)

Setting up notifications through Amazon SNS

to set up Amazon SNS, please go to Datahub -> Management -> Platform integration
:point-right: More about Amazon S3
:point-right: How to register AWS SNS

The following AWS information is required to complete the setup:

  • AccessKey
  • Secret
  • AWS Region
  • TopicArn of the SNS queue

Setting up notifications through Azure Service Bus

to set up Amazon SNS, please go to Datahub -> Management -> Platform integration
:point-right: More about Azure service bus

The following Azure information has to be entered to complete the setup:

  • Endpoint=sb://;
  • SharedAccessKeyName=SampleAccessPolicy;
  • SharedAccessKey=s4-0/Lkj4gsmFfro1/s08+E/0DtjtGG7y5q1Pxm4G2Q=

Setting up notifications through Azure Event grid

:point-right: More about Azure event grid

The following Azure information has to be entered to complete the setup:

Copy data to third-party storage

As discussed above, the primary way to access data is to subscribe to notifications and then access the data through our API. Full list of reports

Yet another option is that we periodically copy data to a third-party storage provider of your choice (for example, Amazon S3 bucke), and notify you when new data is available.

When does third-party storage make sense?

Offline Reporting should be used when you are planning to do an elaborate analysis of aggregate data yourself. To avoid excessive repetitive API calls, we offer a download of the entire database to your S3 Bucket. From there, you can either directly read it or further process it into your own data stores.

Notifications and dataset delivery

to set up Amazon SNS or Azure notification services, please go to Datahub -> Management -> Back-end notifications
:point-right: more about Data Export

The following AWS information has to be entered to complete the setup:

  • S3 bucket arn:
  • S3 bucket region:
  • access key id:
  • secret access key:
  • Folder:

Updated 10 days ago

Data workflow and categories of data

We describe how different categories of data are processed on the platform and how they can be accessed.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.