MOVE Timeline

MOVE Backend APIs
The Base URL of Move SDK is:
The back-end uses REST API a Swagger documentation and is here available.



Move SDK uses Basic Authentication. Username is your project Id and password is your API Token.
Authorization: Basic cHJvamVjdElkOmFwaUtleQ==
cHJvamVjdElkOmFwaUtleQ== is Base64 encode of projectId:apiKey.
API Keys can be found in the Move Dashboard, it is also possible to create new ones there.
Register User
Link to Swagger documentation here

Access Management

Block or unblock a Move User. Move Back-end returns HTTP Error 403 for every blocked user request.
Block or unblock Move SDK user

Delete User

This request deletes all user data of specific user ID. Data is lost permanently.
Delete User

Retrieving Timeline Items

For all Timeline API calls, the projectId needs to be specified as a query parameter.

What is a Timeline Item?

A timeline item represents an activity of a given user, it consists of a projectId, a userId, a start timestamp, an end timestamp, a type and a set of features.
Each timeline item is uniquely identified by the combination of projectId, userId and start time.
Example Timeline Item
"projectId": 1000, // an integer
"userId": "123456789", // a string
"startTs": "2020-10-16T10:13:00Z", // time formatted according to RFC 3339, e.g. "2020-07-10T06:59:44.377Z"
"endTs": "2020-10-16T10:20:00Z", // time formatted according to RFC 3339, e.g. "2020-07-10T06:59:44.377Z"
"features": [
New feature types may be added in the future, a client should be able to deal with additional/unknown types of features.
The GPS coordinates where the item started. Included with DRIVING and CYCLING trips.
"startLocation": {
"lat": 48.1234, // latitude
"lon": 48.1234 // longitude
The GPS coordinates where the item ended. Included with DRIVING and CYCLING trips.
"endLocation": {
"lat": 48.1234, // latitude
"lon": 48.1234 // longitude
The kind of transport that was used for the given trip. The Mode of Transport recognition is multi-stage and is mostly based on GPS coordinates and data about the position taken from OpenStreetMap data (e.g. speed, proximity to streets and public transport stations). In general, the algorithms are tuned towards distinguishing trips in car-like vehicles (including buses and taxi cabs) from non-car vehicles (e.g. bicycles, trains, metro). Note: Quality metrics reported in the following have a maximum variability of +- 3%-points.
  • FAKETRIP - GPS sensors in mobile phones are not always accurate. Jumps of GPS data around the actual "real-world" position of the device may occur at all times; particularly in dense cities with bad visibility of the GPS satellites, when the phone is stacked e.g. beneath a laptop computer in the backpack, or even sometimes when weather conditions are bad. In rare situations, such GPS jumps may follow a pattern that makes our first stage SDK modules in the SDK frontends believe that the device is in an actual trip. Later stages in the SDK backend will label these trips as FAKETRIP.
  • CAR - users of our apps usually have a preference for using cars in their day-to-day activities. In this (slightly biased) population, the detection of car trips (including car-like vehicles such as taxi cabs and buses) has a true positive rate of about 98% and a false positive rate of less than 5%.
  • PUBLIC_TRANSPORT - The recognition of public transport has multiple vectors: e.g. we may detect a tram trip through GPS like a CAR trip, or we may see a person moving from subway station to subway station and infer (since there are no GPS signals underground) that the person must have taken the subway. Since this contains an element of inference and heuristics, the detection/classification of public transport cannot be 100% perfect. Our tests show a true positive rate for railroad-based vehicles of more than 90%. However, bad GPS may further reduce the overall detection of public transport trips. Note that currently we are unable to include buses or taxi into this category; although we can achieve this through hardware (e.g. cheap Bluetooth beacons) in the user's private car. Please get in touch for a more detailed discussion.
  • BICYCLE - Cycling detection is based not only on GPS data but relies heavily on the activities recognized by the OS of the mobile device. Its quality may vary depending on the hardware of the mobile device, as well as the OS version used (e.g. Google Pixel and Huawei Android phones differ quite substantially in their sensitivity and update frequency of activity recognition).
  • UNKNOWN - Whenever the user moves in ways that we cannot categorize, this will be UNKNOWN. For example, users on a boat trip on the sea, which is too far from the road network; or skiing in the mountains - these activities are fast and stable enough to be recorded as a trip, but cannot be verified/classified as a trip.
We are constantly working on improving these algorithms. Therefore, please be advised to use the "probabilities" merely as a rough indicator, but never base any filtering mechanisms on these data, as our machine learning algorithms may improve/change these numbers at any time.
"transport": {
"type": "TRAIN", // possible types are CAR, METRO, TRAIN, TRAM, BICYCLE, FAKETRIP
"probabilities": { // how probable each transport type is
"TRAIN": 0,
"TRAM": 0.064,
"CAR": 0.832,
"METRO": 0.002,
"FAKETRIP": 0.08
Times where the user used their phone. Included with DRIVING and CYCLING trips.
"phoneDistractions": {
"distractions": [
"type": "PHONE_CALL_HANDS_FREE", // the type of distractions, possible distractions are SWIPE_AND_TYPE (the user touched their phone), PHONE_CALL (the user made a phone call without any hands free equipment), PHONE_CALL_HANDS_FREE (the user made a phone call with hands free equipment)
"start": "2021-05-27T12:57:10.234Z", // time formatted according to RFC 3339, e.g. "2020-07-10T06:59:44.377Z"
"end": "2021-05-27T12:57:10.234Z" // time formatted according to RFC 3339, e.g. "2020-07-10T06:59:44.377Z"
"secondsPerType": {


Returns a list of driving behavior events. Valid types of events are: CORNERING, ACCELERATION, BRAKING
"drivingBehaviorEvents": {
"events": [
"time": 0, // UNIX timestamp of event
"type": "CORNERING",
"strength": 0, value between 1 (soft) to 3 (hard)
"lat": 0, latitude of event
"lon": 0, long event of vent
"rawAccel": 0 // raw acceleration of event
"validTime": 0 // how many seconds of the trip could be analyse


GPS stats of trip, such as distance, maximum speed and average speed.
"gpsStats": {
"distance": 0,
"maxSpeed": 0,
"averageSpeed": 0


It is possible to add custom metadata to every trip. Max length for key 255 characters the max length of the value is 1000.
"metas": {
"additionalProp1": "string",
"additionalProp2": "string",
"additionalProp3": "string"


The dangerous areas this timeline item has moved through. Inside a dangerous area speeding is punished more severely. Every project defines his own Dangerous Areas in the Move Dashboard.
Dangerous Area Id is also found in the points request.
"dangerous_areas": {
"areas": [
"id": "d0bd9509-20b1-43d8-8b19-1c56b2db1fdb"
"name": "name"
"lat": 48.1770551 // longitude of the dangerous area position
"lon": 16.3752482 // latitude of the dangerous area position
"radius": 200 // radius of the danngerous area
The individual features above give you the raw data for characterizing and scoring your trip. For example. Based on this, you can calculate scores for your users.
  • distraction-free driving (DFD): score is reduced for usage of phone or swipe-and-type during trip as specified in the feature phone_distractions (in minutes)
  • speed: the score is diminished when driving faster than the the speed limit, based on the speed and the maximum allowed speed in the separate API for GPS points
  • driving behavior events (DBE): sensors will identify events where driving was not smooth for Acceleration, Braking or Cornering (in 3 levels of severity)
  • eco-sensors: awards a better score for an eco-friendly driving-style, and assumes that a driver who constantly brakes and accelerates uses more fuel than a driver who manages to drive very smoothly; similar to an aggregation of DBE, but more sensitive. Note, that this insufficient to define a comprehensive Eco-score, which also addresses type of car/fuel, overall transport mix, distance/minutes driven on a daily basis, or other factors you may want to include
  • you can come up with your own scoring mechanisms, such as:
    • Trip duration (short): users should ideally only take the car for trips longer than x minutes, since short trips are very prone to accidents
    • Trip duration (long): drivers will get tired on long-trips, so take a rest of at least e.g. 10 minutes or more after every 2 hours of driving
    • Eco-score: calculate your own eco-score, based on Eco-sensors (see above, the mix of transport-types and/or based on the type of car/fuel the user defined in your app
We also make score suggestions for scores 0-100, that are based on data analyses of our current user base. We geared the scores to see a Gaussian distribution of aggregated scores (total score per user) with a mean somewhere around 80 or 90. After all, we want to positively encourage people to improve their driving style (which is hard if we gave them bad scores for decent driving style). Please note that this is a global generic scoring distribution. However, age, culture and other factors may influence the driving style. So you may want to adjust your scoring mechanism to suit your user base.
Note that scores may not be there in case they cannot be calculated; e.g. DFD scores are not calculated in case Android phones do not grant the PHONE permission; DBE scores are not calculated in case the phone is used or is located at an unstable place in the car.
Delete timeline Item
Label trip
Open API Specification is available here.

Getting notified about new timeline items

Notification about new timeline items happens via webhooks that can be defined in the MOVE Dashboard > Configuration > Timeline Notifier.
The webhook will be called with a POST request that contains a JSON body with a list of new TimelineItems. Updates are sent every 1000 items or every 5 seconds (whatever comes first). The information transmitted to the webhook is limited, you may request additional information via timeline API, preferably batched.


"items": [
"projectId": <yourProjectId>, // integer
"userId": <userId>, // string
"startTime": <startTime>, // time formatted according to RFC 3339, e.g. "2020-07-10T06:59:44.377Z"
"endTime": <endTime>, // time formatted according to RFC 3339, e.g. "2020-07-10T06:59:44.377Z"
"type": <type> // string, one of IDLE, CYCLING, WALKING, DRIVING
}, ...
If the webhook receiver is not available or does not respond with an HTTP 200 Status the request will be retried, until an HTTP 200 Status is received.


With every request, a signature is being sent in the "X-Dolphin-Signature" Header. The signature is calculated as an HMAC with SHA-256 of the request body, with the secret you gave us during the webhook setup. The format of the header is "sha256=<base64-encoded-hash>".