REST API Reference

This document refers to deprecated parts of the platform and has been left intact to help customers with legacy integrations. In order to access the latest platform features and documentation, please go to https://docs.sentiance.com.

All endpoints speak JSON. A Content-Type header with value application/json is expected to always be present.

The base url is https://api.sentiance.com/<version>/ for all REST endpoints, where the currently supported versions are v2 and v3. v1 has been fully deprecated. Note that not all APIs are common between v2 and v3 versions.

Note: The user deletion API is the only exception to the versioned endpoints rule. It stands on its own as DELETE /users/:user_id

For details on how to authenticate requests, have a look at the Authentication and Authorization page.

For other environments, please ask your sales representative or [email protected] for the custom endpoint linked to your environment.

V2 Endpoints

Segment Definitions

GET /v2/segment_definitions

Fetches all Segment Definitions available on the platform.

Does not require authentication.

[
    {
        "type": "SegmentDefinition",
        "id": "lifestyle.culture_buff",
        "display_name": "Culture buff",
        "description": "Person who like to visit musea, operas, arts centres, etc."
    },
    {
        "type": "SegmentDefinition",
        "id": "lifestyle.resto_lover",
        "display_name": "Resto-lover",
        "description": "Someone who likes eating out"
    },
    {
        "type": "SegmentDefinition",
        "id": "lifestyle.sportive",
        "display_name": "Sportive",
        "description": "Someone who sports regularly."
    }
]

Moment Definitions

GET /v2/moment_definitions

Fetches all Moment Definitions available on the platform.

Does not require authentication.

[
    {
        "type": "MomentDefinition",
        "id": "commute_from_work",
        "display_name": "Commute to home",
        "description": "This moment will be active when the user leaves his work and the prediction is that he is going home."
    },
    {
        "type": "MomentDefinition",
        "id": "commute_from_home",
        "display_name": "Commute to work",
        "description": "This moment will be active when the user leaves his home and the prediction is that he is going to work."
    },
    {
        "type": "MomentDefinition",
        "id": "working_at_work",
        "display_name": "Working at work",
        "description": "This moment will be active when the user is working at his work location. If the prediction is that he is working and he goes away for a short time the moment will stay active."
    }
]

User

GET /v2/users/me

When called with a User Token, returns the user's own data. It fails if an API Key is used.

Headers

Name

Type

Description

Authorization

string

{
    "type": "ControlUser",
    "id": "5c9417700000000000000000",
    "can_login": true,
    "created_at": "2016-11-29T23:00:49.621+00:00",
    "sdk": {
        "type": "UserSdkSettings",
        "flavor": "offline_driving",
        "killswitch_action": "enable_sdk",
        "debug_logging": null
    },
    "application_id": "5c9417700000000000000000",
    "email": "[email protected]",
    "account_roles": [
        {
            "type": "UserAccountRole",
            "user_id": "5c9417700000000000000000",
            "account_id": "5c9417700000000000000000",
            "role": "basic",
            "account": {
                "id": "5c9417700000000000000000",
                "display_name": "Example",
                "created_at": "2015-04-02T14:22:24.936+00:00"
            }
        }
    ]
}

Profile by User ID

GET /v2/users/:user_id

Can be used with both User Token and API Key to retrieve profile data of a user identified by their ID.

If a User Token is used, the calling user must have permission to view the called user's data.

If an API Key is used, the user whose data is being fetched must belong to the App to which the API Key belongs to.

Path Parameters

Name

Type

Description

user_id

string

ID of the user whose profile is being retrieved.

Headers

Name

Type

Description

Authorization

string

{
    "type": "ControlUser",
    "id": "5c9417700000000000000000",
    "can_login": true,
    "created_at": "2016-11-29T23:00:49.621+00:00",
    "sdk": {
        "type": "UserSdkSettings",
        "flavor": "offline_driving",
        "killswitch_action": "enable_sdk",
        "debug_logging": null
    },
    "application_id": "5c9417700000000000000000",
    "email": "[email protected]",
    "account_roles": [
        {
            "type": "UserAccountRole",
            "user_id": "5c9417700000000000000000",
            "account_id": "5c9417700000000000000000",
            "role": "basic",
            "account": {
                "id": "5c9417700000000000000000",
                "display_name": "Example",
                "created_at": "2015-04-02T14:22:24.936+00:00"
            }
        }
    ]
}

Timeline Events

GET /v2/users/:user_id/events?from=:from&to=:to

Returns all events on the timeline for a user from a specified start date to a specified end date.

Path Parameters

Name

Type

Description

user_id

string

ID of the user whose timeline is being retrieved.

Query Parameters

Name

Type

Description

from

string

Include results from this date.

Format

: YYYY-MM-DD

Example

: 2019-01-01

string

Include results up to this date.

Format

: YYYY-MM-DD

Example

: 2019-01-02

Headers

Name

Type

Description

Authorization

string

[
    {
        "type": "Transport",
        "start": "2019-03-22T08:37:45.000+01:00",
        "end": "2019-03-22T09:39:00.000+01:00",
        "analysis_type": "indepth",
        "event_id": "b699235f9e1e0b140b3d531466f0b79811044bb22925ed0e4d420e3fa44d65d6",
        "mode": "car",
        "distance": 51918,
        "behavior_features": {
            "phone_handling": 396000,
            "distance_during_annotations": 46426
        }
    },
    {
        "type": "Stationary",
        "start": "2019-03-21T20:08:00.000+01:00",
        "end": "2019-03-22T08:37:45.000+01:00",
        "analysis_type": "indepth",
        "event_id": "37954206-7468-407f-bfa6-33c9ddaab785",
        "latitude": 51.78561,
        "longitude": 41.49692,
        "duration": 44985000,
        "location": {
            "type": "StationaryLocation",
            "significance": "home",
            "place": {
                "type": "LocationPlaceCandidate",
                "name": "Wonder Palace",
                "categories": [
                    "building",
                    "residential"
                ]
            }
        },
        "address": {
            "type": "Address",
            "country": "België / Belgique / Belgien",
            "city": "Ostend",
            "city_type": "TOWN"
        }
    }
]

Timeline Event by Start Time

GET /v2/users/:user_id/events/:start

Note: This has been deprecated in favour of EventID based retrieval.

Returns a single Event corresponding to the start time of the event.

Path Parameters

Name

Type

Description

user_id

string

ID of the user whose event is being retrieved.

Query Parameters

Name

Type

Description

start

string

ISO Formatted Date String. Event fetched is the one that matches this timestamp.

Example

: 2019-03-21T20:08:00.000+01:00

Headers

Name

Type

Description

Authorization

string

[
    {
        "type": "Stationary",
        "start": "2019-03-21T20:08:00.000+01:00",
        "end": "2019-03-22T08:37:45.000+01:00",
        "analysis_type": "indepth",
        "event_id": "37954206-7468-407f-bfa6-33c9ddaab785",
        "latitude": 51.78561,
        "longitude": 41.49692,
        "duration": 44985000,
        "location": {
            "type": "StationaryLocation",
            "significance": "home",
            "place": {
                "type": "LocationPlaceCandidate",
                "name": "Wonder Palace",
                "categories": [
                    "building",
                    "residential"
                ]
            }
        },
        "address": {
            "type": "Address",
            "country": "België / Belgique / Belgien",
            "city": "Ostend",
            "city_type": "TOWN"
        }
    }
]

Trajectories by Start Time

GET /v2/users/:user_id/events/:start/trajectory

Note: This has been deprecated in favour of EventID based retrieval. Check below.

Path Parameters

Name

Type

Description

user_id

string

ID of the user whose data is being retrieved.

start

string

ISO Formatted Date String. Transport whose Trajectories are fetched is the one that matches this timestamp.

Example

: 2019-02-22T08:37:45.000+01:00

Headers

Name

Type

Description

Authorization

string

{
    "waypoints": [
        {
            "type": "TrajectoryWaypoint",
            "latitude": 50.78568,
            "longitude": 4.49673,
            "timestamp": "2019-03-22T08:37:45.000+01:00",
            "road_type": "residential",
            "speed": 23,
            "distance": 65.5,
            "speed_limit": 50
        },
        {
            "type": "TrajectoryWaypoint",
            "latitude": 50.78618,
            "longitude": 4.49722,
            "timestamp": "2019-03-22T08:37:54.714+01:00",
            "road_type": "residential",
            "speed": 21.2,
            "distance": 9.2,
            "speed_limit": 50
        },
        {
            "type": "TrajectoryWaypoint",
            "latitude": 50.78624,
            "longitude": 4.49731,
            "timestamp": "2019-03-22T08:37:56.080+01:00",
            "road_type": "residential",
            "speed": 20.8,
            "distance": 7.9,
            "speed_limit": 50
        }
    ],
    "encoded": "oa~tHqgmZcBaBKQIOCOAO@_Bc@C{@EYGAFGPs@zB{BnHy@|BUr@Qh@Y|@Wz@oA|DsAhEEJCLcBhFs@zBs@xBKZk@fBy@fCELEJk@jBa@nAu@zBq@zBCDUr@uBvGY`AITIX?BI`@]tBMt@GXIRMRa@`AOPk@|A]`AITk@fBkCrIYbAUv@yAzE_CtFi@fAKRkBhE?@Ul@wAfEsAfEiCdIs@zBOf@m@`AQZUv@]bAkAxDu@~Ba@jAa@lAi@~@g@bAQROHM?KAGAWMMIsAs@}A{@]QmDmBs@a@s@_@kAo@OEo@Q}DwByI}EwBiA}CeBgH{D{CaBwMgHWMmJgFkBcAaOgIeBaAmKiGgCkAoAe@eBq@eCg@gAImCKeEMeAGkAMu@QYK]MmAg@_C{A{YoPk@[aFuBoE{@_EOqF@uKVcBDsO\\}CVuCf@cBf@uChAiBbAGB}A~@cHxEeJrGcDxB{CvB}AfAq@b@q@d@kAv@kE|Ba@RkBt@eA\\s@VgE~@cBX}ARsAJaABy@DuAD{BF}@F_AFwAN{@Lg@JoCx@mAb@{Ap@kAl@mEfC}AbA}A`AwCdBoAt@mAr@YR_I|EoFhDiDvBaDpBiCbBsAx@eDjBeAj@WTe@Vc@V_FzCeHdEc@VkCzAqBnAwA|@{CjBcAn@mDtBqHnEcC|@{B^S@wAJoBFqBBsBLsCl@}BhA_CbByDrDgBbBeB`BaB|A_BpA_FtE}I|HQNaElEcDtE{BfE_AtBoAlDaBvEiGpQsBhG{BrGcChHeApB{@zB}@hBu@fAk@l@_@Xm@d@w@Xq@PcAHy@?A?g@Gi@Mc@Ms@]o@c@e@a@e@m@m@k@e@iAy@oCw@{C}@oDo@mC[gAsDyNoAmEiB{FEO}BuGmBeEcA{BwE{I[g@eAkBiE{FsCgDoCiC}A}A}@w@c@_@aBsAwAgAmCoBgBqAUQqByAcCgBwFaEAA}@s@cBmAkDeCyG}EaMaJwAcAqAaA_[_UuMqJ{DyCuBsAmBwAiBqAqAaA{BeBkGkEcTwOcAu@wImGcAq@yGaFiLeIiBoAsQqJ{LsEyAi@uPwFaPoFeEuAaPcF}GgByDm@kFy@qDc@qDOiFSoF@uEPkAFwALiFh@mB\\qDt@kIrBgJlDE@wEvBsEfCaAp@[R}DnCiBtAuCdCsCjC}B`CgBlBmGtHmFvHS\\_@h@uExHkEhIcDlGaCzEuFfJmCtDsDzEwB|BiBtBgG`HwHzIoB~BuDdEoAtAcEpEuEdFyArAyH~GeC|BkB|AsC~BoBbB{@p@wDvCQLWPqBtAyAbAwJrF_CpAcCtA}BpAk@ZOH}BpAcExBaAh@aBv@kCzAk@Ze@VoAp@uAr@mCrAeBz@]NmHzCaF|AYH_GtAcHjAk@J}N~@gFEW?eCEyEWaKcAYIsEcAkBa@c@Kk@SkAa@wDqAyEsBk@WsG_DmCsAeAk@aDcBa@S_@SsAq@}EcCYQmAk@kAg@e@S}@_@eAc@wAg@s@UkCs@gDi@gAGwCOkDCeADoAB}C^k@Jw@NwAXaAXUFiA\\_Bj@eBj@cDtAsAl@c@TwKzEaQxHyIzDoEnBaBt@_FhBeKxDwA`@yCz@sA`@y@VcE~@uBd@qIvAaC^yFp@yF`@G?oG\\aCF_EDyDD}PIK?qDAg@SaAGeAA}EA[AmD?aLCSGICEAKEA?ICMw@UuAIs@Is@KkAImBMwE?]Ao@EqAE{AQ\\KFU`@BpANN@@RNBbA?pAFdCJfCPhB?BBLBZBLVfBA^?V?b@GZQ^_@LwBv@qCbAwGjDD\\kBr@wHtCsBx@_C`AyM~EkC`AgFlBgJlDeXdKq@ViG|BwTlIwAh@iGtBaEdAiFvAuEx@oCf@gFx@eCVcFp@uHf@O@}DBwCDqBBeCBkCD}CBU?Y?qA@aZLeA@s@DI?M?gA@oNH{FD{@@_ADoGDcBBsDFkHDuCHoCHoA@yA@eCLsCVsBZSD{Bp@eA^eAb@iBz@iDnBiBdAeAp@_Al@sJzFy@d@aKjGsNpI}FnDsLhHeIbFmAv@kHhEq@`@}NbJsElCmCzAoB`AgDpAC@uBj@yA^UDeCZ}ALuCCS?cCKeAGkBOcAIwD_@gGm@}@KuEc@kHmAcGyByHsFwFmDs@]k@Ww@UoAWcCU}CCiDT_Dn@aC|@_IxCaHrCU\\]NkDpAoEbB}HtCkAb@{ElBqCdAc@PmAf@IBKFQHk@RMDy@XAr@BbBDVLl@Lf@Rr@Nb@HZJl@D^Jx@?bBIhBAVEXKt@Ql@a@KGAyB_AQImCcAQGWKgBi@OUIEOEWMQZELAJMf@Mb@WFw@Z_@RKLc@R??"
}

Behavior Scores by Start Time

GET /v2/users/:user_id/events/:start/behavior_scores

Note: This has been deprecated in favour of EventID based retrieval. Check below.

Path Parameters

Name

Type

Description

user_id

string

ID of the user whose data is being retrieved.

start

string

ISO Formatted Date String. Transport whose Behavior Scores are fetched is the one that matches this timestamp.

Example:

2019-02-22T08:37:45.000+01:00

Headers

Name

Type

Description

Authorization

string

{
    "type": "CarBehaviorScores",
    "overall": 0.79,
    "smooth": 0.79,
    "legal": 0.72,
    "anticipative": 0.86,
    "hard_accel": 0.9,
    "hard_brake": 0.65,
    "hard_events": 0.85,
    "hard_turn": 0.95,
    "legal_v2": 0.79,
    "smooth_v2": 0.78,
    "anticipative_v2": 0.85
}

Behavior Annotations by Start Time

GET /v2/users/:user_id/events/:start/behavior_annotations

Note: This has been deprecated in favor of EventID based retrieval. Check below.

Path Parameters

Name

Type

Description

user_id

string

ID of the user whose data is being retrieved.

start

string

ISO Formatted Date String. Transport whose Behavior Annotations are fetched is the one that matches this timestamp.

Example

: 2019-02-22T08:37:45.000+01:00

Headers

Name

Type

Description

Authorization

string

[
    {
        "type": "BoundaryBehaviorAnnotation",
        "start": "2019-03-22T08:37:48.303000+01:00",
        "end": "2019-03-22T08:40:35.303000+01:00",
        "quality": "valid"
    },
    {
        "type": "AccelerationBehaviorAnnotation",
        "start": "2019-03-22T08:38:10.781456+01:00",
        "end": "2019-03-22T08:38:16.102097+01:00",
        "acceleration": "accelerate",
        "duration": 5321,
        "magnitude": 0.189,
        "path": [
            {
                "type": "BehaviorAnnotationPathWaypoint",
                "latitude": 50.78664,
                "longitude": 4.49807
            },
            {
                "type": "BehaviorAnnotationPathWaypoint",
                "latitude": 50.78679,
                "longitude": 4.49808
            },
            {
                "type": "BehaviorAnnotationPathWaypoint",
                "latitude": 50.78685,
                "longitude": 4.4981
            }
        ]
    },
    {
        "type": "TurnBehaviorAnnotation",
        "start": "2019-03-22T08:38:16.866289+01:00",
        "end": "2019-03-22T08:38:21.479824+01:00",
        "duration": 4614,
        "maneuver": "left_turn",
        "magnitude": 0.467,
        "path": [
            {
                "type": "BehaviorAnnotationPathWaypoint",
                "latitude": 50.78688,
                "longitude": 4.49811
            },
            {
                "type": "BehaviorAnnotationPathWaypoint",
                "latitude": 50.78692,
                "longitude": 4.49812
            },
            {
                "type": "BehaviorAnnotationPathWaypoint",
                "latitude": 50.78693,
                "longitude": 4.49808
            },
            {
                "type": "BehaviorAnnotationPathWaypoint",
                "latitude": 50.78697,
                "longitude": 4.49799
            },
            {
                "type": "BehaviorAnnotationPathWaypoint",
                "latitude": 50.78703,
                "longitude": 4.49785
            }
        ]
    }
]

User

GET /v2/users/:user_id/segments

Path Parameters

Name

Type

Description

user_id

string

ID of the user whose data is being retrieved.

Headers

Name

Type

Description

Authorization

string

[
    {
        "type": "GenericSegment",
        "segment_definition_id": "lifestyle.brand_loyalty.supermarket",
        "explanation_you": "Because you usually shop at colruyt overijse"
    },
    {
        "type": "GenericSegment",
        "segment_definition_id": "mobility.long_commuter",
        "explanation_you": "Because your commute distance from Overijse to Antwerpen is about 52.0 km"
    },
]

Moment History

GET /v2/users/:user_id/moments?from=:from&to=:to

Path Parameters

Name

Type

Description

user_id

string

ID of the user whose data is being retrieved.

Query Parameters

Name

Type

Description

from

string

Include results from this date.

Format

: YYYY-MM-DD

Example

: 2019-03-21

string

Include results up to this date.

Format

: YYYY-MM-DD

Example

: 2019-03-22

Headers

Name

Type

Description

Authorization

string

[
    {
        "type": "GenericMoment",
        "start": "2019-03-22T14:26:00.000+01:00",
        "end": null,
        "moment_definition_id": "afternoon",
        "analysis_type": "preliminary"
    },
    {
        "type": "GenericMoment",
        "start": "2019-03-22T12:31:00.000+01:00",
        "end": "2019-03-22T14:26:00.000+01:00",
        "moment_definition_id": "lunch",
        "analysis_type": "preliminary"
    }
]

Active Moments

GET /v2/users/:user_id/active_moments

Path Parameters

Name

Type

Description

user_id

string

ID of the user whose data is being retrieved.

Headers

Name

Type

Description

Authorization

string

[
    {
        "type": "GenericMoment",
        "start": "2019-03-22T14:26:00.000+01:00",
        "end": null,
        "analysis_type": "preliminary",
        "moment_definition_id": "afternoon"
    },
    {
        "type": "GenericMoment",
        "start": "2019-03-22T09:39:00.000+01:00",
        "end": null,
        "analysis_type": "preliminary",
        "moment_definition_id": "working_at_work"
    },
    {
        "type": "CityMoment",
        "start": "2019-03-22T09:39:00.000+01:00",
        "end": null,
        "analysis_type": "preliminary",
        "moment_definition_id": "city_name",
        "city_name": "Antwerpen"
    },
    {
        "type": "CountryMoment",
        "start": "2019-03-18T20:08:00.000+01:00",
        "end": null,
        "analysis_type": "preliminary",
        "moment_definition_id": "country",
        "country_name": "België / Belgique / Belgien"
    }
]

Location Clusters

GET /v2/users/:user_id/location_clusters

Path Parameters

Name

Type

Description

user_id

string

ID of the user whose data is being retrieved.

Headers

Name

Type

Description

Authorization

string

[
    {
        "type": "LocationCluster",
        "last_visit": "2019-03-21T08:51:00+01:00",
        "latitude": 50.78561,
        "longitude": 4.49692,
        "radius": 39,
        "is_poi": true,
        "significance": "home",
        "address": {
            "type": "Address",
            "country": "België / Belgique / Belgien",
            "city": "Overijse",
            "city_type": null
        },
        "place": {
            "type": "LocationPlaceCandidate",
            "name": null,
            "categories": [
                "building",
                "residential"
            ]
        }
    },
    {
        "type": "LocationCluster",
        "last_visit": "2019-03-21T12:59:00+01:00",
        "latitude": 51.19655,
        "longitude": 4.40808,
        "radius": 98,
        "is_poi": true,
        "significance": "work",
        "address": {
            "type": "Address",
            "country": "België / Belgique / Belgien",
            "city": "Antwerpen",
            "city_type": null
        },
        "place": {
            "type": "LocationPlaceCandidate",
            "name": "Sentiance HQ",
            "categories": [
                "office",
                "company"
            ]
        }
    }
]

Location

GET /v2/users/:user_id/location

Path Parameters

Name

Type

Description

user_id

string

ID of the user whose data is being retrieved.

Headers

Name

Type

Description

Authorization

string

{
    "type": "Waypoint",
    "latitude": 51.19766,
    "longitude": 4.41042,
    "timestamp": "2019-03-22T14:04:31.929+01:00"
}

Aggregated Behavior Scores

GET /v2/users/:user_id/car_behavior

Path Parameters

Name

Type

Description

user_id

string

ID of the user whose data is being retrieved.

Headers

Name

Type

Description

Authorization

string

{
    "type": "UserCarBehavior",
    "scores": {
        "l7d": {
            "type": "ZoneCarBehaviorScores",
            "all": {
                "type": "CarBehaviorScores",
                "overall": 0.743,
                "smooth": 0.75,
                "legal": 0.68,
                "anticipative": 0.8,
                "focus": 0.95,
                "mounted": 0.05,
                "hard_accel": 0.85,
                "hard_brake": 0.84,
                "hard_events": 0.74,
                "hard_turn": 0.89,
                "legal_v2": 0.67,
                "smooth_v2": 0.74,
                "anticipative_v2": 0.77
            },
            "motorway": {
                "type": "CarBehaviorScores",
                "overall": 0.44,
                "smooth": -1,
                "legal": 0.44,
                "anticipative": -1,
                "hard_accel": 0.93,
                "hard_brake": 0.9,
                "hard_events": 0.79,
                "hard_turn": 0.95,
                "legal_v2": 0.31,
                "smooth_v2": 0.84,
                "anticipative_v2": 0.92
            },
            "city": {
                "type": "CarBehaviorScores",
                "overall": 0.97,
                "smooth": -1,
                "legal": 0.97,
                "anticipative": -1,
                "hard_accel": 0.93,
                "hard_brake": 0.99,
                "hard_events": 0.68,
                "hard_turn": 0.97,
                "legal_v2": 0.98,
                "smooth_v2": 0.59,
                "anticipative_v2": 0.71
            },
            "non_city": {
                "type": "CarBehaviorScores",
                "overall": 0.99,
                "smooth": -1,
                "legal": 0.99,
                "anticipative": -1,
                "hard_accel": 0.91,
                "hard_brake": 0.89,
                "hard_events": 0.65,
                "hard_turn": 0.93,
                "legal_v2": 0.98,
                "smooth_v2": 0.58,
                "anticipative_v2": 0.74
            },
            "total": {
                "type": "CarBehaviorScores",
                "overall": 0.783,
                "smooth": 0.75,
                "legal": 0.8,
                "anticipative": 0.8,
                "hard_accel": 0.92,
                "hard_brake": 0.93,
                "hard_events": 0.71,
                "hard_turn": 0.95,
                "legal_v2": 0.76,
                "smooth_v2": 0.67,
                "anticipative_v2": 0.79
            }
        },
        "past": {
            "type": "ZoneCarBehaviorScores",
            "all": {
                "type": "CarBehaviorScores",
                "overall": 0.747,
                "smooth": 0.8,
                "legal": 0.65,
                "anticipative": 0.79,
                "focus": 0.96,
                "mounted": 0.33,
                "hard_accel": 0.87,
                "hard_brake": 0.88,
                "hard_events": 0.78,
                "hard_turn": 0.91,
                "legal_v2": 0.57,
                "smooth_v2": 0.79,
                "anticipative_v2": 0.78
            },
            "motorway": {
                "type": "CarBehaviorScores",
                "overall": 0.38,
                "smooth": -1,
                "legal": 0.38,
                "anticipative": -1,
                "hard_accel": 0.95,
                "hard_brake": 0.9,
                "hard_events": 0.83,
                "hard_turn": 0.96,
                "legal_v2": 0.28,
                "smooth_v2": 0.85,
                "anticipative_v2": 0.91
            },
            "city": {
                "type": "CarBehaviorScores",
                "overall": 0.93,
                "smooth": -1,
                "legal": 0.93,
                "anticipative": -1,
                "hard_accel": 0.94,
                "hard_brake": 0.97,
                "hard_events": 0.62,
                "hard_turn": 0.97,
                "legal_v2": 0.98,
                "smooth_v2": 0.61,
                "anticipative_v2": 0.7
            },
            "non_city": {
                "type": "CarBehaviorScores",
                "overall": 0.96,
                "smooth": -1,
                "legal": 0.96,
                "anticipative": -1,
                "hard_accel": 0.92,
                "hard_brake": 0.95,
                "hard_events": 0.69,
                "hard_turn": 0.93,
                "legal_v2": 0.97,
                "smooth_v2": 0.67,
                "anticipative_v2": 0.73
            },
            "total": {
                "type": "CarBehaviorScores",
                "overall": 0.783,
                "smooth": 0.8,
                "legal": 0.76,
                "anticipative": 0.79,
                "hard_accel": 0.94,
                "hard_brake": 0.94,
                "hard_events": 0.71,
                "hard_turn": 0.95,
                "legal_v2": 0.74,
                "smooth_v2": 0.71,
                "anticipative_v2": 0.78
            }
        }
    },
    "features": {
        "type": "UserCarBehaviorFeatures",
        "l7d": {
            "type": "TimeWindowUserCarBehaviorFeatures",
            "phone_handling": 181200,
            "distance": 557301
        },
        "past": {
            "type": "TimeWindowUserCarBehaviorFeatures",
            "phone_handling": 137400,
            "distance": 5079771
        }
    }
}

Anomaly History

GET /v2/users/:user_id/anomalies?from=:from&to=:to

Path Parameters

Name

Type

Description

user_id

string

ID of the user whose data is being retrieved.

Query Parameters

Name

Type

Description

from

string

Include results from this date.

Format

: YYYY-MM-DD

Example

: 2019-03-21

string

Include results up to this date.

Format

: YYYY-MM-DD

Example

: 2019-03-21

Headers

Name

Type

Description

Authorization

string

[
    {
        "type": "AggregatedDurationAnomaly",
        "start": "2019-03-21T00:00:00+00:00",
        "end": "2019-03-21T23:59:59.999999+00:00",
        "analysis_type": "processed",
        "sigma": 597.098,
        "probability": 1,
        "anomaly": "stationary_location_significance_day_part_duration",
        "observed_duration": null,
        "expected_duration": 7675,
        "period": "day",
        "day_part": "evening",
        "place_category": null,
        "location_significance": "work",
        "transport_mode": null,
        "transport_mode_category": null,
        "moment_definition_id": null
    },
    {
        "type": "AggregatedDurationAnomaly",
        "start": "2019-03-21T00:00:00+00:00",
        "end": "2019-03-21T23:59:59.999999+00:00",
        "analysis_type": "processed",
        "sigma": null,
        "probability": 1,
        "anomaly": "stationary_location_significance_day_part_duration",
        "observed_duration": null,
        "expected_duration": 14340,
        "period": "day",
        "day_part": "noon",
        "place_category": null,
        "location_significance": "work",
        "transport_mode": null,
        "transport_mode_category": null,
        "moment_definition_id": null
    },
    {
        "type": "AggregatedDurationAnomaly",
        "start": "2019-03-21T00:00:00+00:00",
        "end": "2019-03-21T23:59:59.999999+00:00",
        "analysis_type": "processed",
        "sigma": 1224.012,
        "probability": 1,
        "anomaly": "stationary_location_significance_duration",
        "observed_duration": null,
        "expected_duration": 34446,
        "period": "day",
        "day_part": null,
        "place_category": null,
        "location_significance": "work",
        "transport_mode": null,
        "transport_mode_category": null,
        "moment_definition_id": null
    }
]

User Link

POST /v2/users/:install_id/link

Used to link an Install ID to your system's UserID. The JSON body should contain a single parameter as described below.

Check out the guide for further details on how User Linking work and how it can benefit you.

Path Parameters

Name

Type

Description

install_id

string

The ID of the user returned by the SDK into the Linker's callback function.

Headers

Name

Type

Description

Authorization

string

Unlike other endpoints, which can be called with both a user token and an API Key, this endpoint can ONLY be called with an API Key with

user.link

scope. User tokens will be rejected.

Request Body

Name

Type

Description

external_id

string

This is the unique ID of the user in your system.

{
  "id": "5a18fc4b0962209e0000000d"
}

{
  "message": "Install does not belong to this application.",
  "errorCode": "INSTALL_DOES_NOT_BELONG_TO_APP",
  "ref": "403b03b1-35ea-4ae4-af0a-7ebb65211543"
}

{
  "message": "Install is disabled.",
  "errorCode": "INSTALL_DISABLED",
  "ref": "403b03b1-35ea-4ae4-af0a-7ebb65211543"
}

{
  "message": "Install is deleted.",
  "errorCode": "INSTALL_DELETED",
  "ref": "403b03b1-35ea-4ae4-af0a-7ebb65211543"
}

{
  "message": "This install is already in use, linking to another install is not possible.",
  "errorCode": "CANNOT_LINK_EXISTING_PERSON_TO_OTHER_PERSON",
  "ref": "403b03b1-35ea-4ae4-af0a-7ebb65211543"
}

{
  "message": "Install linked to another user.",
  "errorCode": "INSTALL_LINKED_TO_OTHER_USER",
  "ref": "403b03b1-35ea-4ae4-af0a-7ebb65211543"
}

V3 Endpoints

Timeline Event by EventId

GET /v3/users/:user_id/events/:event_id

Returns a single Event based on the type and ID provided.

Path Parameters

Name

Type

Description

user_id

string

ID of the user whose event is being retrieved.

event_id

string

ID of the event being retrieved. This will be present in the

event_id

field of the

Headers

Name

Type

Description

Authorization

string

[
    {
        "type": "Stationary",
        "start": "2019-03-21T20:08:00.000+01:00",
        "end": "2019-03-22T08:37:45.000+01:00",
        "analysis_type": "indepth",
        "event_id": "37954206-7468-407f-bfa6-33c9ddaab785",
        "latitude": 51.78561,
        "longitude": 41.49692,
        "duration": 44985000,
        "location": {
            "type": "StationaryLocation",
            "significance": "home",
            "place": {
                "type": "LocationPlaceCandidate",
                "name": "Wonder Palace",
                "categories": [
                    "building",
                    "residential"
                ]
            }
        },
        "address": {
            "type": "Address",
            "country": "België / Belgique / Belgien",
            "city": "Ostend",
            "city_type": "TOWN"
        }
    }
]

Trajectories by EventID

GET /v3/users/:user_id/events/:event_id/trajectory

Retrieve Trajectories of a Transport by its EventID.

Path Parameters

Name

Type

Description

user_id

string

ID of the user whose data is being retrieved.

event_id

string

ID of the Transport whose Trajectories are being retrieved.

Headers

Name

Type

Description

Authorization

string

{
    "waypoints": [
        {
            "type": "TrajectoryWaypoint",
            "latitude": 50.78568,
            "longitude": 4.49673,
            "timestamp": "2019-03-22T08:37:45.000+01:00",
            "road_type": "residential",
            "speed": 23,
            "distance": 65.5,
            "speed_limit": 50
        },
        {
            "type": "TrajectoryWaypoint",
            "latitude": 50.78618,
            "longitude": 4.49722,
            "timestamp": "2019-03-22T08:37:54.714+01:00",
            "road_type": "residential",
            "speed": 21.2,
            "distance": 9.2,
            "speed_limit": 50
        },
        {
            "type": "TrajectoryWaypoint",
            "latitude": 50.78624,
            "longitude": 4.49731,
            "timestamp": "2019-03-22T08:37:56.080+01:00",
            "road_type": "residential",
            "speed": 20.8,
            "distance": 7.9,
            "speed_limit": 50
        }
    ],
    "encoded": "oa~tHqgmZcBaBKQIOCOAO@_Bc@C{@EYGAFGPs@zB{BnHy@|BUr@Qh@Y|@Wz@oA|DsAhEEJCLcBhFs@zBs@xBKZk@fBy@fCELEJk@jBa@nAu@zBq@zBCDUr@uBvGY`AITIX?BI`@]tBMt@GXIRMRa@`AOPk@|A]`AITk@fBkCrIYbAUv@yAzE_CtFi@fAKRkBhE?@Ul@wAfEsAfEiCdIs@zBOf@m@`AQZUv@]bAkAxDu@~Ba@jAa@lAi@~@g@bAQROHM?KAGAWMMIsAs@}A{@]QmDmBs@a@s@_@kAo@OEo@Q}DwByI}EwBiA}CeBgH{D{CaBwMgHWMmJgFkBcAaOgIeBaAmKiGgCkAoAe@eBq@eCg@gAImCKeEMeAGkAMu@QYK]MmAg@_C{A{YoPk@[aFuBoE{@_EOqF@uKVcBDsO\\}CVuCf@cBf@uChAiBbAGB}A~@cHxEeJrGcDxB{CvB}AfAq@b@q@d@kAv@kE|Ba@RkBt@eA\\s@VgE~@cBX}ARsAJaABy@DuAD{BF}@F_AFwAN{@Lg@JoCx@mAb@{Ap@kAl@mEfC}AbA}A`AwCdBoAt@mAr@YR_I|EoFhDiDvBaDpBiCbBsAx@eDjBeAj@WTe@Vc@V_FzCeHdEc@VkCzAqBnAwA|@{CjBcAn@mDtBqHnEcC|@{B^S@wAJoBFqBBsBLsCl@}BhA_CbByDrDgBbBeB`BaB|A_BpA_FtE}I|HQNaElEcDtE{BfE_AtBoAlDaBvEiGpQsBhG{BrGcChHeApB{@zB}@hBu@fAk@l@_@Xm@d@w@Xq@PcAHy@?A?g@Gi@Mc@Ms@]o@c@e@a@e@m@m@k@e@iAy@oCw@{C}@oDo@mC[gAsDyNoAmEiB{FEO}BuGmBeEcA{BwE{I[g@eAkBiE{FsCgDoCiC}A}A}@w@c@_@aBsAwAgAmCoBgBqAUQqByAcCgBwFaEAA}@s@cBmAkDeCyG}EaMaJwAcAqAaA_[_UuMqJ{DyCuBsAmBwAiBqAqAaA{BeBkGkEcTwOcAu@wImGcAq@yGaFiLeIiBoAsQqJ{LsEyAi@uPwFaPoFeEuAaPcF}GgByDm@kFy@qDc@qDOiFSoF@uEPkAFwALiFh@mB\\qDt@kIrBgJlDE@wEvBsEfCaAp@[R}DnCiBtAuCdCsCjC}B`CgBlBmGtHmFvHS\\_@h@uExHkEhIcDlGaCzEuFfJmCtDsDzEwB|BiBtBgG`HwHzIoB~BuDdEoAtAcEpEuEdFyArAyH~GeC|BkB|AsC~BoBbB{@p@wDvCQLWPqBtAyAbAwJrF_CpAcCtA}BpAk@ZOH}BpAcExBaAh@aBv@kCzAk@Ze@VoAp@uAr@mCrAeBz@]NmHzCaF|AYH_GtAcHjAk@J}N~@gFEW?eCEyEWaKcAYIsEcAkBa@c@Kk@SkAa@wDqAyEsBk@WsG_DmCsAeAk@aDcBa@S_@SsAq@}EcCYQmAk@kAg@e@S}@_@eAc@wAg@s@UkCs@gDi@gAGwCOkDCeADoAB}C^k@Jw@NwAXaAXUFiA\\_Bj@eBj@cDtAsAl@c@TwKzEaQxHyIzDoEnBaBt@_FhBeKxDwA`@yCz@sA`@y@VcE~@uBd@qIvAaC^yFp@yF`@G?oG\\aCF_EDyDD}PIK?qDAg@SaAGeAA}EA[AmD?aLCSGICEAKEA?ICMw@UuAIs@Is@KkAImBMwE?]Ao@EqAE{AQ\\KFU`@BpANN@@RNBbA?pAFdCJfCPhB?BBLBZBLVfBA^?V?b@GZQ^_@LwBv@qCbAwGjDD\\kBr@wHtCsBx@_C`AyM~EkC`AgFlBgJlDeXdKq@ViG|BwTlIwAh@iGtBaEdAiFvAuEx@oCf@gFx@eCVcFp@uHf@O@}DBwCDqBBeCBkCD}CBU?Y?qA@aZLeA@s@DI?M?gA@oNH{FD{@@_ADoGDcBBsDFkHDuCHoCHoA@yA@eCLsCVsBZSD{Bp@eA^eAb@iBz@iDnBiBdAeAp@_Al@sJzFy@d@aKjGsNpI}FnDsLhHeIbFmAv@kHhEq@`@}NbJsElCmCzAoB`AgDpAC@uBj@yA^UDeCZ}ALuCCS?cCKeAGkBOcAIwD_@gGm@}@KuEc@kHmAcGyByHsFwFmDs@]k@Ww@UoAWcCU}CCiDT_Dn@aC|@_IxCaHrCU\\]NkDpAoEbB}HtCkAb@{ElBqCdAc@PmAf@IBKFQHk@RMDy@XAr@BbBDVLl@Lf@Rr@Nb@HZJl@D^Jx@?bBIhBAVEXKt@Ql@a@KGAyB_AQImCcAQGWKgBi@OUIEOEWMQZELAJMf@Mb@WFw@Z_@RKLc@R??"
}

Behavior Scores by EventID

GET /v3/users/:user_id/events/:event_id/behavior_scores

Retrieve Behavior Scores of a Transport by its EventID.

Path Parameters

Name

Type

Description

user_id

string

ID of the user whose data is being retrieved.

event_id

string

ID of the Transport whose Behavior Scores are being retrieved.

Headers

Name

Type

Description

Authorization

string

{
    "type": "CarBehaviorScores",
    "overall": 0.79,
    "smooth": 0.79,
    "legal": 0.72,
    "anticipative": 0.86,
    "hard_accel": 0.9,
    "hard_brake": 0.65,
    "hard_events": 0.85,
    "hard_turn": 0.95,
    "legal_v2": 0.79,
    "smooth_v2": 0.78,
    "anticipative_v2": 0.85
}

Behavior Annotations by EventID

GET /v3/users/:user_id/events/:event_id/behavior_annotations

Path Parameters

Name

Type

Description

user_id

string

ID of the user whose data is being retrieved.

event_id

string

ID of the Transport whose Behavior Annotations are being retrieved.

Headers

Name

Type

Description

Authorization

string

[
    {
        "type": "BoundaryBehaviorAnnotation",
        "start": "2019-03-22T08:37:48.303000+01:00",
        "end": "2019-03-22T08:40:35.303000+01:00",
        "quality": "valid"
    },
    {
        "type": "AccelerationBehaviorAnnotation",
        "start": "2019-03-22T08:38:10.781456+01:00",
        "end": "2019-03-22T08:38:16.102097+01:00",
        "acceleration": "accelerate",
        "duration": 5321,
        "magnitude": 0.189,
        "path": [
            {
                "type": "BehaviorAnnotationPathWaypoint",
                "latitude": 50.78664,
                "longitude": 4.49807
            },
            {
                "type": "BehaviorAnnotationPathWaypoint",
                "latitude": 50.78679,
                "longitude": 4.49808
            },
            {
                "type": "BehaviorAnnotationPathWaypoint",
                "latitude": 50.78685,
                "longitude": 4.4981
            }
        ]
    },
    {
        "type": "TurnBehaviorAnnotation",
        "start": "2019-03-22T08:38:16.866289+01:00",
        "end": "2019-03-22T08:38:21.479824+01:00",
        "duration": 4614,
        "maneuver": "left_turn",
        "magnitude": 0.467,
        "path": [
            {
                "type": "BehaviorAnnotationPathWaypoint",
                "latitude": 50.78688,
                "longitude": 4.49811
            },
            {
                "type": "BehaviorAnnotationPathWaypoint",
                "latitude": 50.78692,
                "longitude": 4.49812
            },
            {
                "type": "BehaviorAnnotationPathWaypoint",
                "latitude": 50.78693,
                "longitude": 4.49808
            },
            {
                "type": "BehaviorAnnotationPathWaypoint",
                "latitude": 50.78697,
                "longitude": 4.49799
            },
            {
                "type": "BehaviorAnnotationPathWaypoint",
                "latitude": 50.78703,
                "longitude": 4.49785
            }
        ]
    }
]

Time Aggregated Driving Scores

GET /v3/users/:user_id/aggregated_driving_scores

Retrieve the time aggregated scores of a user, i.e.

daily

weekly

monthly

all

aggregated scores. The API can be used with or without a date parameter. If no date parameter is given, the API will default to the last available (ongoing) day, week or month. The

all

score will aggregate all available scores (max. 9 weeks).

The date parameter accepts either the 1st day of the week (Monday) or the 1st day of the month for type: week and type: month respectively.

Note: this endpoint is available on the EU platform only.

Path Parameters

Name

Type

Description

type

string

Type of aggregated scores you want to retrieve.

Accepts:

day, week, month, all.

date

string

Optional: if you want to retrieve aggregated scores for a different period than the current one.

Format:

YYYY-MM-DD

Accepts:

any day, any monday, any 1st of month.

Headers

Name

Type

Description

Authorization

string

A user token or an API Key with scope 'user.read'.

{
    "day": {
        "smooth": 0.64,
        "legal": 1,
        "anticipative": 0.69,
        "focus": 1,
        "mounted": 0.17,
        "hard_accel": 0.95,
        "hard_brake": 0.9,
        "hard_events": 0.69,
        "legal_v2": 1,
        "hard_turn": 1,
        "smooth_v2": 0.68,
        "anticipative_v2": 0.68,
        "handheld_calling": 1,
        "handheld_calling_duration": -1,
        "handsfree_calling": 1,
        "handling_without_calling": 0.95,
        "handling_without_calling_duration": 10,
        "attention": 0.95
    }
}
{
    "week": {
        "smooth": 0.64,
        "legal": 1,
        "anticipative": 0.69,
        "focus": 1,
        "mounted": 0.17,
        "hard_accel": 0.95,
        "hard_brake": 0.9,
        "hard_events": 0.69,
        "legal_v2": 1,
        "hard_turn": 1,
        "smooth_v2": 0.68,
        "anticipative_v2": 0.68,
        "handheld_calling": 1,
        "handheld_calling_duration": -1,
        "handsfree_calling": 1,
        "handling_without_calling": 0.95,
        "handling_without_calling_duration": 10,
        "attention": 0.95
    }
}
{
    "month": {
        "smooth": 0.66,
        "legal": 0.72,
        "anticipative": 0.6,
        "focus": 1,
        "mounted": 0.96,
        "hard_accel": 0.93,
        "hard_brake": 0.9,
        "hard_events": 0.68,
        "legal_v2": 0.8,
        "hard_turn": 0.95,
        "smooth_v2": 0.61,
        "anticipative_v2": 0.61,
        "handheld_calling": 1,
        "handheld_calling_duration": -1,
        "handsfree_calling": 1,
        "handling_without_calling": 0.95,
        "handling_without_calling_duration": 705,
        "attention": 0.95
    }
}
{
    "all": {
        "smooth": 0.67,
        "legal": 0.6,
        "anticipative": 0.59,
        "focus": 0.99,
        "mounted": 0.85,
        "hard_accel": 0.9,
        "hard_brake": 0.92,
        "hard_events": 0.7,
        "legal_v2": 0.52,
        "hard_turn": 0.93,
        "smooth_v2": 0.63,
        "anticipative_v2": 0.84,
        "handheld_calling": 1,
        "handheld_calling_duration": 0,
        "handsfree_calling": 0.97,
        "handling_without_calling": 0,
        "handling_without_calling_duration": 2101,
        "attention": 0
    }
}

Unversioned Routes (no version prefix applied) [Deprecated]

Use this instead.

Delete User

DELETE /users/:user_id

Deletes the user data along with the history.

Path Parameters

Name

Type

Description

user_id

string

ID of the user whose data is to be deleted.

Headers

Name

Type

Description

Authorization

string

A user token or an API Key with

user.delete

scope

PreviousGraphQL NextError Codes (REST API)

Last updated 2 years ago

hashtagV2 Endpoints

hashtagSegment Definitions

hashtagMoment Definitions

hashtagUser

hashtagHeaders

hashtagProfile by User ID

hashtagPath Parameters

hashtagHeaders

hashtagTimeline Events

hashtagPath Parameters

hashtagQuery Parameters

hashtagHeaders

hashtagTimeline Event by Start Time

hashtagPath Parameters

hashtagQuery Parameters

hashtagHeaders

hashtagTrajectories by Start Time

hashtagPath Parameters

hashtagHeaders

hashtagBehavior Scores by Start Time

hashtagPath Parameters

hashtagHeaders

hashtagBehavior Annotations by Start Time

hashtagPath Parameters

hashtagHeaders

hashtagUser

hashtagPath Parameters

hashtagHeaders

hashtagMoment History

hashtagPath Parameters

hashtagQuery Parameters

hashtagHeaders

hashtagActive Moments

hashtagPath Parameters

hashtagHeaders

hashtagLocation Clusters

hashtagPath Parameters

hashtagHeaders

hashtagLocation

hashtagPath Parameters

hashtagHeaders

hashtagAggregated Behavior Scores

hashtagPath Parameters

hashtagHeaders

hashtagAnomaly History

hashtagPath Parameters

hashtagQuery Parameters

hashtagHeaders

hashtagUser Link

hashtagPath Parameters

hashtagHeaders

hashtagRequest Body

hashtagV3 Endpoints

hashtagTimeline Event by EventId

hashtagPath Parameters

hashtagHeaders

hashtagTrajectories by EventID

hashtagPath Parameters

hashtagHeaders

hashtagBehavior Scores by EventID

hashtagPath Parameters

hashtagHeaders

hashtagBehavior Annotations by EventID

hashtagPath Parameters

hashtagHeaders

hashtagTime Aggregated Driving Scores

hashtagPath Parameters

hashtagHeaders

hashtagUnversioned Routes (no version prefix applied) [Deprecated]

hashtagDelete User

hashtagPath Parameters

hashtagHeaders

V2 Endpoints

Segment Definitions

Moment Definitions

User

Headers

Profile by User ID

Path Parameters

Headers

Timeline Events

Path Parameters

Query Parameters

Headers

Timeline Event by Start Time

Path Parameters

Query Parameters

Headers

Trajectories by Start Time

Path Parameters

Headers

Behavior Scores by Start Time

Path Parameters

Headers

Behavior Annotations by Start Time

Path Parameters

Headers

User

Path Parameters

Headers

Moment History

Path Parameters

Query Parameters

Headers

Active Moments

Path Parameters

Headers

Location Clusters

Path Parameters

Headers

Location

Path Parameters

Headers

Aggregated Behavior Scores

Path Parameters

Headers

Anomaly History

Path Parameters

Query Parameters

Headers

User Link

Path Parameters

Headers

Request Body

V3 Endpoints

Timeline Event by EventId

Path Parameters

Headers

Trajectories by EventID

Path Parameters

Headers

Behavior Scores by EventID

Path Parameters

Headers

Behavior Annotations by EventID

Path Parameters

Headers

Time Aggregated Driving Scores

Path Parameters

Headers

Unversioned Routes (no version prefix applied) [Deprecated]

Delete User

Path Parameters

Headers