Sentiance Graphql V4

An intro to Sentiance's version 4 Graphql API.

Contact

Support

support@sentiance.com

Terms of Service

https://sentiance.com/terms

API Endpoints
# Endpoint:
https://api.sentiance.com/v4/gql
Headers
Authorization: Bearer <YOUR_API_KEY_HERE>

Intro

Our API primarily speaks GraphQL (GQL, for short). While explaining how GraphQL works is beyond the scope of this guide, there are excellent resources available on the interwebs. Here we will introduce the basic request-response structure of the Sentiance GraphQL API.

Endpoint and Authorization

Our default GraphQL endpoint lives at POST https://api.sentiance.com/v4/gql and accepts the same bearer token based authorization. We adhere to the GraphQL specification but do not support multiple operation types. Since it is possible for a single HTTP request to encompass multiple GraphQL queries with some of them succeeding and some of them failing, the endpoint always returns a 200 OK, unless something severe enough happens on the server-side to guarantee failure of the entire response (such as a 500 status code). After checking for the 200 status code, please also check the body of the response for data and error properties.

Queries

engagement

Description

Engagement data.

Response

Returns an Engagement

Example

Query
query Engagement {
  engagement {
    group {
      created_at
      feed {
        ...UserEngagementGroupFeedFragment
      }
      group_id
      leaderboard {
        ...UserEngagementGroupLeaderboardFragment
      }
      members {
        ...UserEngagementGroupMembersFragment
      }
      name
      reg_code
      user_id
    }
  }
}
Response
{"data": {"engagement": {"group": UserEngagementGroup}}}

offloads

Response

Returns [Offload]

Arguments
Name Description
from - String
to - String

Example

Query
query Offloads(
  $from: String,
  $to: String
) {
  offloads(
    from: $from,
    to: $to
  ) {
    day
    files {
      format
      link {
        ...LinkFragment
      }
      name
      size
    }
    type
  }
}
Variables
{
  "from": "xyz789",
  "to": "abc123"
}
Response
{
  "data": {
    "offloads": [
      {
        "day": "2023-03-04",
        "files": [OffloadFile],
        "type": "OFFLOAD_TYPE_DRIVER_PASSENGER"
      }
    ]
  }
}

transport

Response

Returns a Transport

Arguments
Name Description
transport_id - String

Example

Query
query Transport($transport_id: String) {
  transport(transport_id: $transport_id) {
    additional_mobility_details {
      raw_data_points {
        ...RawDataPointsFragment
      }
    }
    crash_events {
      crash_event {
        ...CrashEventFragment
      }
    }
    driving_events {
      accelerating {
        ...AcceleratingEventFragment
      }
      braking {
        ...BrakingEventFragment
      }
      calls {
        ...CallEventFragment
      }
      mounted {
        ...MountedEventFragment
      }
      phone_handling {
        ...PhoneHandlingEventFragment
      }
      screens {
        ...ScreenEventFragment
      }
      speeding {
        ...SpeedingEventFragment
      }
      turning {
        ...TurningEventFragment
      }
    }
    duration
    end_at
    metadata
    mode
    occupant_role
    scores {
      safety {
        ...TransportScoresSafetyFragment
      }
    }
    start_at
    top_speed
    trajectory {
      distance
      end_location {
        ...LocationInformationFragment
      }
      map_matched_waypoints {
        ...MapMatchedWaypointFragment
      }
      polyline
      start_location {
        ...LocationInformationFragment
      }
      top_speed
    }
    transport_id
    weather_data {
      weather_at_destination {
        ...WeatherDataFragment
      }
      weather_at_origin {
        ...WeatherDataFragment
      }
    }
  }
}
Variables
{"transport_id": "abc123"}
Response
{
  "data": {
    "transport": {
      "additional_mobility_details": AdditionalMobilityDetails,
      "crash_events": CrashEventsForTransport,
      "driving_events": TransportDrivingEvents,
      "duration": 123,
      "end_at": "abc123",
      "metadata": "xyz789",
      "mode": "abc123",
      "occupant_role": "abc123",
      "scores": TransportScores,
      "start_at": "abc123",
      "top_speed": 123.45,
      "trajectory": TransportTrajectory,
      "transport_id": "xyz789",
      "weather_data": TransportWeatherData
    }
  }
}

user

Response

Returns a User

Arguments
Name Description
user_id - String Sentiance ID of the user. This is the ID of the user in the Sentiance platform. If both user_id and external_id are provided, user_id will be used.
external_id - String External ID of the user. This is the ID of the user in your system. External ID based queries are only supported for API Keys. If both user_id and external_id are provided, user_id will be used.

Example

Query
query User(
  $user_id: String,
  $external_id: String
) {
  user(
    user_id: $user_id,
    external_id: $external_id
  ) {
    app_id
    created_at
    diagnostics {
      off_the_grids {
        ...OffTheGridFragment
      }
    }
    engagement {
      aggregations {
        ...UserEngagementAggregationsFragment
      }
      badges {
        ...UserEngagementBadgesFragment
      }
      challenges {
        ...UserEngagementChallengesFragment
      }
      communications {
        ...UserEngagementCommunicationsFragment
      }
      groups {
        ...UserEngagementGroupsFragment
      }
      library {
        ...UserEngagementLibraryFragment
      }
      scores {
        ...UserEngagementScoresFragment
      }
      streaks {
        ...UserEngagementStreaksFragment
      }
      transport {
        ...UserEngagementTransportFragment
      }
      transports {
        ...UserEngagementTransportsFragment
      }
    }
    external_id
    scores {
      driving {
        ...UserScoresDrivingFragment
      }
    }
    transports {
      additional_mobility_details {
        ...AdditionalMobilityDetailsFragment
      }
      crash_events {
        ...CrashEventsForTransportFragment
      }
      driving_events {
        ...TransportDrivingEventsFragment
      }
      duration
      end_at
      metadata
      mode
      occupant_role
      scores {
        ...TransportScoresFragment
      }
      start_at
      top_speed
      trajectory {
        ...TransportTrajectoryFragment
      }
      transport_id
      weather_data {
        ...TransportWeatherDataFragment
      }
    }
    user_id
  }
}
Variables
{
  "user_id": "xyz789",
  "external_id": "abc123"
}
Response
{
  "data": {
    "user": {
      "app_id": "abc123",
      "created_at": "xyz789",
      "diagnostics": Diagnostics,
      "engagement": UserEngagement,
      "external_id": "abc123",
      "scores": UserScores,
      "transports": [Transport],
      "user_id": "xyz789"
    }
  }
}

Mutations

abandon_challenge

Description

Mutation for abandoning a challenge.

Response

Returns an AbandonUserEngagementChallenge

Arguments
Name Description
challenge_id - String ID of the challenge to be abandoned.

Example

Query
mutation Abandon_challenge($challenge_id: String) {
  abandon_challenge(challenge_id: $challenge_id) {
    status
  }
}
Variables
{"challenge_id": "abc123"}
Response
{"data": {"abandon_challenge": {"status": true}}}

accept_challenge

Description

Mutation for accepting a challenge.

Response

Returns an AcceptUserEngagementChallenge

Arguments
Name Description
challenge_id - String ID of the challenge to be accepted.

Example

Query
mutation Accept_challenge($challenge_id: String) {
  accept_challenge(challenge_id: $challenge_id) {
    status
  }
}
Variables
{"challenge_id": "abc123"}
Response
{"data": {"accept_challenge": {"status": false}}}

create_group

Description

Mutation for creating a new group.

Response

Returns a CreateUserEngagementGroup

Arguments
Name Description
origin - String A String representing the origin of the group. Ex: 'client_app', 'web_platform', etc
name - String Name of the new group.
group_type - String Type of the new group. Supported types: SOCIAL.

Example

Query
mutation Create_group(
  $origin: String,
  $name: String,
  $group_type: String
) {
  create_group(
    origin: $origin,
    name: $name,
    group_type: $group_type
  ) {
    group {
      created_at
      feed {
        ...UserEngagementGroupFeedFragment
      }
      group_id
      leaderboard {
        ...UserEngagementGroupLeaderboardFragment
      }
      members {
        ...UserEngagementGroupMembersFragment
      }
      name
      reg_code
      user_id
    }
    status
  }
}
Variables
{
  "origin": "xyz789",
  "name": "abc123",
  "group_type": "xyz789"
}
Response
{
  "data": {
    "create_group": {
      "group": UserEngagementGroup,
      "status": false
    }
  }
}

delete_user

Response

Returns a DeleteUserById

Arguments
Name Description
id - String

Example

Query
mutation Delete_user($id: String) {
  delete_user(id: $id) {
    request_id
  }
}
Variables
{"id": "xyz789"}
Response
{
  "data": {
    "delete_user": {"request_id": "abc123"}
  }
}

generate_auth_code

Response

Returns a GenerateAuthCode

Arguments
Name Description
external_id - String

Example

Query
mutation Generate_auth_code($external_id: String) {
  generate_auth_code(external_id: $external_id) {
    authentication_code
    expires_at
  }
}
Variables
{"external_id": "xyz789"}
Response
{
  "data": {
    "generate_auth_code": {
      "authentication_code": "xyz789",
      "expires_at": "xyz789"
    }
  }
}

generate_offload_url

Response

Returns a GenerateUrl

Arguments
Name Description
day - String
offload_type - OffloadTypeEnum

Example

Query
mutation Generate_offload_url(
  $day: String,
  $offload_type: OffloadTypeEnum
) {
  generate_offload_url(
    day: $day,
    offload_type: $offload_type
  ) {
    offload {
      day
      files {
        ...OffloadFileFragment
      }
      type
    }
  }
}
Variables
{
  "day": "abc123",
  "offload_type": "OFFLOAD_TYPE_DRIVER_PASSENGER"
}
Response
{"data": {"generate_offload_url": {"offload": Offload}}}

join_group

Description

Mutation for joining an existing group.

Response

Returns a JoinUserEngagementGroup

Arguments
Name Description
reg_code - String Registration code of the group.

Example

Query
mutation Join_group($reg_code: String) {
  join_group(reg_code: $reg_code) {
    status
  }
}
Variables
{"reg_code": "xyz789"}
Response
{"data": {"join_group": {"status": true}}}

leave_group

Description

Mutation for leaving a group the user is part of.

Response

Returns a LeaveUserEngagementGroup

Arguments
Name Description
group_id - String ID of the group.

Example

Query
mutation Leave_group($group_id: String) {
  leave_group(group_id: $group_id) {
    status
  }
}
Variables
{"group_id": "abc123"}
Response
{"data": {"leave_group": {"status": false}}}

submit_log_event

Description

Mutation for submitting log events.

Response

Returns a SubmitLogEvent

Arguments
Name Description
event_name - String Name of the event.
event_params - [SubmitLogEventRequest_EventParamsEntryInput] Map of parameters for the event.

Example

Query
mutation Submit_log_event(
  $event_name: String,
  $event_params: [SubmitLogEventRequest_EventParamsEntryInput]
) {
  submit_log_event(
    event_name: $event_name,
    event_params: $event_params
  ) {
    message
    status
  }
}
Variables
{
  "event_name": "xyz789",
  "event_params": [
    SubmitLogEventRequest_EventParamsEntryInput
  ]
}
Response
{
  "data": {
    "submit_log_event": {
      "message": "abc123",
      "status": true
    }
  }
}

submit_transport_feedback

Description

Mutation for submitting transport feedback.

Response

Returns a TransportFeedback

Arguments
Name Description
grace - Boolean Flag for type of feedback. Adjusting a trip (true) or deleting a trip (false)
origin - String Where the feedback originated from. Ex: Trips_page, Challenges_page, etc.
entity_id - String ID of the entity feedback is provided for.
entity_type - String Type of entity. Available options: TRIP, CHALLENGE.
reason - String Reason feedback is provided. Available options: GENERIC, WAS_PASSENGER, WAS_DRIVER, WAS_FOCUSED, NOT_CAR_TRIP, VALID
context - [TransportFeedbackRequest_ContextEntryInput] Map of attributes describing the context feedback was provided.

Example

Query
mutation Submit_transport_feedback(
  $grace: Boolean,
  $origin: String,
  $entity_id: String,
  $entity_type: String,
  $reason: String,
  $context: [TransportFeedbackRequest_ContextEntryInput]
) {
  submit_transport_feedback(
    grace: $grace,
    origin: $origin,
    entity_id: $entity_id,
    entity_type: $entity_type,
    reason: $reason,
    context: $context
  ) {
    status
  }
}
Variables
{
  "grace": true,
  "origin": "abc123",
  "entity_id": "abc123",
  "entity_type": "abc123",
  "reason": "xyz789",
  "context": [TransportFeedbackRequest_ContextEntryInput]
}
Response
{"data": {"submit_transport_feedback": {"status": false}}}

submit_user_engagement_preferences

Description

Mutation for submitting user preferences.

Response

Returns a SubmitUserEngagementPreferences

Arguments
Name Description
grace_config - SubmitUserEngagementPreferencesRequest_GraceConfigInput Option for enabling/disabling grace period for a user.
language_config - SubmitUserEngagementPreferencesRequest_LanguageConfigInput Option for choosing preferred language for a user.

Example

Query
mutation Submit_user_engagement_preferences(
  $grace_config: SubmitUserEngagementPreferencesRequest_GraceConfigInput,
  $language_config: SubmitUserEngagementPreferencesRequest_LanguageConfigInput
) {
  submit_user_engagement_preferences(
    grace_config: $grace_config,
    language_config: $language_config
  ) {
    message
    status
  }
}
Variables
{
  "grace_config": SubmitUserEngagementPreferencesRequest_GraceConfigInput,
  "language_config": SubmitUserEngagementPreferencesRequest_LanguageConfigInput
}
Response
{
  "data": {
    "submit_user_engagement_preferences": {
      "message": "xyz789",
      "status": true
    }
  }
}

Types

AbandonUserEngagementChallenge

Fields
Field Name Description
status - Boolean Success/Failure status.
Example
{"status": true}

AcceleratingEvent

Fields
Field Name Description
category - String The main category of the acceleration event (e.g. acceleration).
duration - Float Duration of the acceleration event in seconds.
end_at - String The end time of the acceleration event in ISO 8601 format (e.g. 2022-06-26T11:26:48.351+01:00).
magnitude - Float Max magnitude of the acceleration, measured in m/s².
mean - Float The mean of the acceleration event (e.g. acceleration).
path - [PathElement] Path (waypoints) of the acceleration event while it lasted.
start_at - String The start time of the acceleration event in ISO 8601 format (e.g. 2022-06-26T11:26:48.351+01:00).
type - String The sub type of the acceleration event (e.g. brake, acceleration).
Example
{
  "category": "abc123",
  "duration": 123.45,
  "end_at": "xyz789",
  "magnitude": 123.45,
  "mean": 987.65,
  "path": [PathElement],
  "start_at": "abc123",
  "type": "abc123"
}

AcceptUserEngagementChallenge

Fields
Field Name Description
status - Boolean Success/Failure status.
Example
{"status": false}

AdditionalMobilityDetails

Fields
Field Name Description
raw_data_points - RawDataPoints
Example
{"raw_data_points": RawDataPoints}

AggregationFunctionEnum

Values
Enum Value Description

AVG

MIN

MAX

SUM

COUNT

Example
"AVG"

Boolean

Description

The Boolean scalar type represents true or false.

BrakingEvent

Fields
Field Name Description
category - String The main category of the braking event.
duration - Float Duration of the braking event in seconds.
end_at - String The end time of the braking event in ISO 8601 format (e.g. 2022-06-26T11:26:48.351+01:00).
magnitude - Float Max magnitude of the braking, measured in m/s².
mean - Float The mean of the braking event (e.g. braking).
path - [PathElement] Path (waypoints) of the braking event while it lasted.
start_at - String The start time of the braking event in ISO 8601 format (e.g. 2022-06-26T11:26:48.351+01:00).
type - String The sub type of the braking event.
Example
{
  "category": "abc123",
  "duration": 123.45,
  "end_at": "xyz789",
  "magnitude": 123.45,
  "mean": 987.65,
  "path": [PathElement],
  "start_at": "abc123",
  "type": "xyz789"
}

CallEvent

Fields
Field Name Description
category - String The main category of the call event.
duration - Float Duration of the call event in seconds.
end_at - String The end time of the call event in ISO 8601 format (e.g. 2022-06-26T11:26:48.351+01:00).
speed - PhoneEventSpeed The speed during the call event.
start_at - String The start time of the call event in ISO 8601 format (e.g. 2022-06-26T11:26:48.351+01:00).
type - String The sub type of the call event.
Example
{
  "category": "xyz789",
  "duration": 987.65,
  "end_at": "abc123",
  "speed": PhoneEventSpeed,
  "start_at": "xyz789",
  "type": "xyz789"
}

ComparisonOperatorEnum

Values
Enum Value Description

GT

GTE

EQ

NEQ

IN

LT

LTE

Example
"GT"

CrashEvent

Fields
Field Name Description
confidence - Float confidence
delta_v - Float delta v
event_time - String exact moment of the crash event
max_magnitude - Float max magnitude
origin - String origin of the crash event
speed_at_impact - Float speed at impact
waypoint_direction - Float direction of the last waypoint
waypoint_elevation - Float elevation of the last waypoint
waypoint_horizontal_accuracy - Float horizontal accuracy of the last waypoint
waypoint_latitude - Float latitude of the last waypoint
waypoint_longitude - Float longitude of the last waypoint
waypoint_speed - Float speed of the last waypoint
waypoint_time - String time of the last waypoint
waypoint_vertical_accuracy - Float vertical accuracy of the last waypoint
Example
{
  "confidence": 987.65,
  "delta_v": 123.45,
  "event_time": "abc123",
  "max_magnitude": 123.45,
  "origin": "xyz789",
  "speed_at_impact": 987.65,
  "waypoint_direction": 987.65,
  "waypoint_elevation": 123.45,
  "waypoint_horizontal_accuracy": 123.45,
  "waypoint_latitude": 987.65,
  "waypoint_longitude": 987.65,
  "waypoint_speed": 987.65,
  "waypoint_time": "xyz789",
  "waypoint_vertical_accuracy": 987.65
}

CrashEventsForTransport

Fields
Field Name Description
crash_event - CrashEvent List of crash events in this transport.
Example
{"crash_event": CrashEvent}

CreateUserEngagementGroup

Fields
Field Name Description
group - UserEngagementGroup Details of the newly created group.
status - Boolean Success/Failure status.
Example
{"group": UserEngagementGroup, "status": false}

DeleteUserById

Fields
Field Name Description
request_id - String Id of the unique user deletion request generated on our backend. Exists for debugging purposes. If you face any issues with user deletion, you can include this requestID in the support email to support@sentiance.com
Example
{"request_id": "xyz789"}

Diagnostics

Fields
Field Name Description
off_the_grids - [OffTheGrid]
Arguments
to - String

The starting date for the search query in YYYY-MM-DD format (inclusive).

from - String

The starting date for the search query in YYYY-MM-DD format (inclusive).

Example
{"off_the_grids": [OffTheGrid]}

Engagement

Fields
Field Name Description
group - UserEngagementGroup Group details.
Arguments
group_id - String

ID of the group.

reg_code - String

Registration code of the group.

Example
{"group": UserEngagementGroup}

EngagementComparisonAttributeEnum

Values
Enum Value Description

DISTANCE

RIDING_CALL_WHILE_MOVING_SCORE

OCCUPANT_ROLE

DRIVING_FOCUSED_SCORE

DRIVING_SMOOTH_SCORE

PHONE_HANDLING_EVENTS_DURATION

RIDING_OVERALL_SCORE

RIDING_LEGAL_SCORE

RIDING_HARSH_SCORE

TRANSPORT_MODE

CALL_EVENTS_COUNT

DURATION

DRIVING_OVERALL_SCORE

DRIVING_NO_SPEEDING_SCORE

CALL_EVENTS_DURATION

PHONE_HANDLING_EVENTS_COUNT

Example
"DISTANCE"

FilterInput

Fields
Input Field Description
attribute - EngagementComparisonAttributeEnum
operator - ComparisonOperatorEnum
value - String
Example
{
  "attribute": "DISTANCE",
  "operator": "GT",
  "value": "xyz789"
}

Float

Description

The Float scalar type represents signed double-precision fractional values as specified by IEEE 754.

Example
987.65

GenerateAuthCode

Fields
Field Name Description
authentication_code - String
expires_at - String Time in ISO-8601 format at which the authentication code expires.
Example
{
  "authentication_code": "abc123",
  "expires_at": "abc123"
}

GenerateUrl

Fields
Field Name Description
offload - Offload
Example
{"offload": Offload}

Int

Description

The Int scalar type represents non-fractional signed whole numeric values. Int can represent values between -(2^31) and 2^31 - 1.

Example
987

JoinUserEngagementGroup

Fields
Field Name Description
status - Boolean Success/Failure status.
Example
{"status": true}

LeaveUserEngagementGroup

Fields
Field Name Description
status - Boolean Success/Failure status.
Example
{"status": true}

LocationInformation

Fields
Field Name Description
city - String The city to which the location belongs.
country - String The country to which the location belongs.
district - String The district to which the location belongs.
region - String The region to which the location belongs.
street - String The street to which the location belongs.
Example
{
  "city": "abc123",
  "country": "abc123",
  "district": "abc123",
  "region": "abc123",
  "street": "xyz789"
}

MapMatchedWaypoint

Fields
Field Name Description
distance - Float The distance in meters between the current waypoint and the previous waypoint.
latitude - Float Waypoint latitude in degrees with accuracy of 5 decimals.
longitude - Float Waypoint longitude in degrees with accuracy of 5 decimals.
road_type - String The type of road in which the waypoint was mapped (e.g. motorway, pedestrian, highway, etc.).
speed - Float The speed in km/h at the moment the waypoint was mapped.
speed_limit - Float The speed limit in km/h of the road where the waypoint was mapped.
timestamp - String Waypoint timestamp in ISO 8601 format (e.g. 2022-06-26T11:26:48.351+01:00).
Example
{
  "distance": 123.45,
  "latitude": 123.45,
  "longitude": 987.65,
  "road_type": "abc123",
  "speed": 987.65,
  "speed_limit": 987.65,
  "timestamp": "xyz789"
}

MountedEvent

Fields
Field Name Description
category - String The main category of the mounted phone event.
duration - Float Duration of the mounted phone event in seconds.
end_at - String The end time of the mounted phone event in ISO 8601 format (e.g. 2022-06-26T11:26:48.351+01:00).
start_at - String The start time of the mounted phone event in ISO 8601 format (e.g. 2022-06-26T11:26:48.351+01:00).
type - String The sub type of the mounted phone event.
Example
{
  "category": "abc123",
  "duration": 987.65,
  "end_at": "xyz789",
  "start_at": "abc123",
  "type": "xyz789"
}

OffTheGrid

Fields
Field Name Description
end_at - String The end time of the off-the-grid in ISO 8601 format (e.g. 2022-06-27T11:26:48.351+01:00).
off_the_grid_id - String Unique ID of the off-the-grid event.
reason - OffTheGrid_OffTheGridReasonEnum The reason why the off-the-grid started (e.g. OFF_THE_GRID_LOCATION_PERMISSION).
start_at - String The start time of the off-the-grid in ISO 8601 format (e.g. 2022-06-26T11:26:48.351+01:00).
Example
{
  "end_at": "abc123",
  "off_the_grid_id": "xyz789",
  "reason": "OFF_THE_GRID_LOCATION_ACCESS_ALWAYS",
  "start_at": "xyz789"
}

OffTheGrid_OffTheGridReasonEnum

Values
Enum Value Description

OFF_THE_GRID_LOCATION_ACCESS_ALWAYS

OFF_THE_GRID_LOCATION_MODE_OFF

OFF_THE_GRID_SDK_NOT_RUNNING

OFF_THE_GRID_BG_DETECTIONS_NOT_ALLOWED

OFF_THE_GRID_LOCATION_ACCURACY_REDUCED

OFF_THE_GRID_AIRPLANE_MODE

OFF_THE_GRID_MOTION_ACTIVITY_PERMISSION

OFF_THE_GRID_BGACCESS_PERMISSION

OFF_THE_GRID_LOCATION_MODE_DEVICE_ONLY

OFF_THE_GRID_OTHER

OFF_THE_GRID_OUTAGE

OFF_THE_GRID_LOCATION_PERMISSION

OFF_THE_GRID_LOCATION_MODE_BATTERY_SAVING

OFF_THE_GRID_KILLSWITCH

OFF_THE_GRID_GEOFENCE_TRANSITION_TIMEOUT

OFF_THE_GRID_DISK_QUOTA_EXCEEDED

OFF_THE_GRID_BG_EXECUTION_RESTRICTED

OFF_THE_GRID_NETWORK_PERMISSION

OFF_THE_GRID_EXTERNAL_EVENT

OFF_THE_GRID_PLAY_SERVICES

OFF_THE_GRID_NO_LOCATION_FIXES

OFF_THE_GRID_DISKUSAGE_PERMISSION

Example
"OFF_THE_GRID_LOCATION_ACCESS_ALWAYS"

Offload

Fields
Field Name Description
day - String Day must be in YYYY-MM-DD format.
files - [OffloadFile]
type - OffloadTypeEnum
Example
{
  "day": "2023-03-04",
  "files": [OffloadFile],
  "type": "OFFLOAD_TYPE_DRIVER_PASSENGER"
}

OffloadFile

Fields
Field Name Description
format - String File format of the offload file.
link - Link
name - String
size - Int Size of the offload file in bytes.
Example
{
  "format": "csv.gz",
  "link": Link,
  "name": "xyz789",
  "size": 987
}

OffloadTypeEnum

Values
Enum Value Description

OFFLOAD_TYPE_DRIVER_PASSENGER

OFFLOAD_TYPE_GROUPS

OFFLOAD_TYPE_GROUP_MEMBERS

OFFLOAD_TYPE_TRAJECTORIES

OFFLOAD_TYPE_FEEDBACK

OFFLOAD_TYPE_CUSTOM_SCORES

OFFLOAD_TYPE_APP_EVENTS

OFFLOAD_TYPE_STREAKS

OFFLOAD_TYPE_OFF_THE_GRIDS

OFFLOAD_TYPE_DRIVING_EVENTS_ALL

OFFLOAD_TYPE_DRIVING_EVENTS_SIGNIFICANT

OFFLOAD_TYPE_BADGES

OFFLOAD_TYPE_SECONDARY_SAFETY_SCORES_TRANSPORT

OFFLOAD_TYPE_TRANSPORTS

OFFLOAD_TYPE_PRIMARY_SAFETY_SCORES_USER

OFFLOAD_TYPE_PRIMARY_SAFETY_SCORES_TRANSPORT

OFFLOAD_TYPE_SECONDARY_SAFETY_SCORES_USER

OFFLOAD_TYPE_COMMUNICATIONS

OFFLOAD_TYPE_UNKNOWN

Example
"OFFLOAD_TYPE_DRIVER_PASSENGER"

PathElement

Fields
Field Name Description
latitude - Float Location-fix latitude in degrees with accuracy of 5 decimals.
longitude - Float Location-fix longitude in degrees with accuracy of 5 decimals.
Example
{"latitude": 987.65, "longitude": 123.45}

PhoneEventSpeed

Fields
Field Name Description
max - Float
min - Float
Example
{"max": 123.45, "min": 123.45}

PhoneHandlingEvent

Fields
Field Name Description
category - String The main category of the phone handling event.
duration - Float Duration of the phone handling event in seconds.
end_at - String The end time of the phone handling event in ISO 8601 format (e.g. 2022-06-26T11:26:48.351+01:00).
path - [PathElement] Path (waypoints) of the phone handling event while it lasted.
speed - PhoneEventSpeed The speed during the phone handling event.
start_at - String The start time of the phone handling event in ISO 8601 format (e.g. 2022-06-26T11:26:48.351+01:00).
type - String The sub type of the phone handling event.
Example
{
  "category": "abc123",
  "duration": 123.45,
  "end_at": "abc123",
  "path": [PathElement],
  "speed": PhoneEventSpeed,
  "start_at": "abc123",
  "type": "xyz789"
}

PrimarySafetyScores

Fields
Field Name Description
attention - Float A combined score of handheld calling, hands-free calling and handling without calling. Range: 0..1. If we did not obtain sufficient data, the value will be -1.
legal - Float The legal driving score measures how well you adhere to speed limits. The higher your score, the more you respect the speed limits. Range: 0..1. If we did not obtain sufficient data, the value will be -1.
overall - Float A combined score of the legal, smooth, and attention scores. Range: 0..1. If we did not obtain sufficient data, the value will be -1.
smooth - Float The smooth driving score measures how smooth you drive. High accelerations, heavy braking and heavy turning result in a lower score. The use of coasting results in a higher score. Scores are normalized with respect to a wide population. The higher your score, the smoother you drive. Range: 0..1. If we did not obtain sufficient data, the value will be -1.
Example
{"attention": 123.45, "legal": 123.45, "overall": 987.65, "smooth": 987.65}

RawDataPoints

Fields
Field Name Description
distance - Float The total distance travelled in meters. Based on the Haversine distance
raw_waypoints - [RawWaypoint] List of raw waypoints.
top_speed - Float Top speed reached in the transport in km/h.
Example
{
  "distance": 987.65,
  "raw_waypoints": [RawWaypoint],
  "top_speed": 987.65
}

RawWaypoint

Fields
Field Name Description
accuracy - Int Waypoint accuracy in meters.
latitude - Float Waypoint latitude in degrees with accuracy of 5 decimals.
longitude - Float Waypoint longitude in degrees with accuracy of 5 decimals.
speed - Float The speed in m/s
timestamp - String Waypoint timestamp in ISO 8601 format (e.g. 2022-06-26T11:26:48.351+01:00).
Example
{
  "accuracy": 987,
  "latitude": 987.65,
  "longitude": 123.45,
  "speed": 987.65,
  "timestamp": "xyz789"
}

ScreenEvent

Fields
Field Name Description
category - String The main category of the phone screen event.
duration - Float Duration of the phone screen event in seconds.
end_at - String The end time of the phone screen event in ISO 8601 format (e.g. 2022-06-26T11:26:48.351+01:00).
speed - PhoneEventSpeed The speed during the phone screen event.
start_at - String The start time of the phone screen event in ISO 8601 format (e.g. 2022-06-26T11:26:48.351+01:00).
type - String The sub type of the phone screen event.
Example
{
  "category": "xyz789",
  "duration": 987.65,
  "end_at": "abc123",
  "speed": PhoneEventSpeed,
  "start_at": "xyz789",
  "type": "xyz789"
}

SecondarySafetyScores

Fields
Field Name Description
anticipation - Float The anticipative driving score measures how well you anticipate turns. Hard accelerations before or hard braking during a turn result in a lower score. The use of coasting results in a higher score. The higher your score, the more anticipative you drive. Range: 0..1. If we did not obtain sufficient data, the value will be -1.
focus - Float The proportion of time (percentage) the user is focused while driving, being focused means: not using the phone, which is detected through phone handling. Range: 0..1. If we did not obtain sufficient data, the value will be -1.
harsh_acceleration - Float Measures how often you accelerate hard. Every hard acceleration will be penalised by subtracting a percentage of your score. Range: 0..1. If we did not obtain sufficient data, the value will be -1.
harsh_braking - Float Measures how often you need to brake hard. Every hard brake will be penalised by subtracting a percentage of your score. Range: 0..1. If we did not obtain sufficient data, the value will be -1.
harsh_events - Float This is a combination of hard_accel and hard_brake score. The hard brakes and accelerations are also normalized by the total number of events. When we do not have sufficient data this value will be -1.
harsh_turning - Float Measures how often you turn hard. Every hard turn will be penalised by subtracting a percentage of your score. Range: 0..1. If we did not obtain sufficient data, the value will be -1.
mounted - Float The proportion of time (percentage) the phone is mounted while driving. Range: 0..1. If we did not obtain sufficient data, the value will be -1.
Example
{
  "anticipation": 123.45,
  "focus": 123.45,
  "harsh_acceleration": 987.65,
  "harsh_braking": 987.65,
  "harsh_events": 987.65,
  "harsh_turning": 987.65,
  "mounted": 987.65
}

SliceByEnum

Values
Enum Value Description

MONTH

YEAR

DAY

WEEK

Example
"MONTH"

SpeedingEvent

Fields
Field Name Description
category - String The main category of the speeding event.
duration - Float Duration of the speeding event in seconds.
end_at - String The end time of the speeding event in ISO 8601 format (e.g. 2022-06-26T11:26:48.350+01:00).
path - [PathElement] Path (waypoints) of the speeding event while it lasted.
speed_limits - [Int] List of speed limits in km/h corresponding to the waypoints in the path.
speeds - [Float] List of speeds in km/h corresponding to the waypoints in the path.
start_at - String The start time of the speeding event in ISO 8601 format (e.g. 2022-06-26T11:26:48.350+01:00).
type - String The sub type of the speeding event.
Example
{
  "category": "xyz789",
  "duration": 123.45,
  "end_at": "xyz789",
  "path": [PathElement],
  "speed_limits": [987],
  "speeds": [123.45],
  "start_at": "abc123",
  "type": "abc123"
}

String

Description

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Example
"xyz789"

SubmitLogEvent

Fields
Field Name Description
message - String Success/Failure message.
status - Boolean Success/Failure status.
Example
{"message": "xyz789", "status": true}

SubmitLogEventRequest_EventParamsEntryInput

Fields
Input Field Description
value - String!
key - String!
Example
{
  "value": "xyz789",
  "key": "xyz789"
}

SubmitUserEngagementPreferences

Fields
Field Name Description
message - String Success/Failure message.
status - Boolean Success/Failure status.
Example
{"message": "abc123", "status": true}

SubmitUserEngagementPreferencesRequest_GraceConfigInput

Fields
Input Field Description
enabled - Boolean
Example
{"enabled": false}

SubmitUserEngagementPreferencesRequest_LanguageConfigInput

Fields
Input Field Description
code - String
name - String
Example
{
  "code": "xyz789",
  "name": "abc123"
}

TimeFrame

Fields
Field Name Description
from - String Start of the time frame in yyyy-MM-dd'T'HH:mm:ss format (e.g. 2024-03-31T23:59:59).
timezone - String Timezone of the time frame in IANA timezone format (e.g. Europe/Brussels). Default is Etc/UTC
to - String End of the time frame in yyyy-MM-dd'T'HH:mm:ss format (e.g. 2024-03-31T23:59:59).
Example
{
  "from": "abc123",
  "timezone": "xyz789",
  "to": "xyz789"
}

TimeFrameInput

Fields
Input Field Description
from - String
to - String
timezone - String
Example
{
  "from": "abc123",
  "to": "xyz789",
  "timezone": "xyz789"
}

Transport

Fields
Field Name Description
additional_mobility_details - AdditionalMobilityDetails Additional mobility insights of the transport.
crash_events - CrashEventsForTransport Crash events for the transport
driving_events - TransportDrivingEvents The driving events detected in the transport (CAR only).
Arguments
show - TransportDrivingEventsRequest_DrivingEventsFilterEnum

Accepted values are ALL (obtain significant and non-significant driving events) or SIGNIFICANT (obtain only significant driving events).

duration - Int Total duration of the transport in seconds.
end_at - String End time of the transport in ISO 8601 format (e.g. 2022-06-26T15:21:21.351+01:00).
metadata - String JSON array of of key-value pairs with metadata sent by the client.
mode - String The transport mode. Possible values are: [biking, bus, car, ferry, idle, insufficient_data, running, train, tram, unsupported_mode, walking].
occupant_role - String The occupant role information of the transport.
scores - TransportScores The driving scores assigned to the transport.
start_at - String Start time of the transport in ISO 8601 format (e.g. 2022-06-26T11:26:48.351+01:00).
top_speed - Float Top speed reached in the transport in km/h.
trajectory - TransportTrajectory The trajectory details of the transport.
transport_id - String The unique ID of the transport.
weather_data - TransportWeatherData The weather data at the origin and destination of the transport
Example
{
  "additional_mobility_details": AdditionalMobilityDetails,
  "crash_events": CrashEventsForTransport,
  "driving_events": TransportDrivingEvents,
  "duration": 987,
  "end_at": "abc123",
  "metadata": "abc123",
  "mode": "xyz789",
  "occupant_role": "xyz789",
  "scores": TransportScores,
  "start_at": "abc123",
  "top_speed": 123.45,
  "trajectory": TransportTrajectory,
  "transport_id": "xyz789",
  "weather_data": TransportWeatherData
}

TransportDrivingEvents

Fields
Field Name Description
accelerating - [AcceleratingEvent] List of accelerating events.
braking - [BrakingEvent] List of braking events.
calls - [CallEvent] List of call events.
mounted - [MountedEvent] List of mounted events.
phone_handling - [PhoneHandlingEvent] List of phone-handling events.
screens - [ScreenEvent] List of screen events.
speeding - [SpeedingEvent] List of speeding events.
turning - [TurningEvent] List of turning events.
Example
{
  "accelerating": [AcceleratingEvent],
  "braking": [BrakingEvent],
  "calls": [CallEvent],
  "mounted": [MountedEvent],
  "phone_handling": [PhoneHandlingEvent],
  "screens": [ScreenEvent],
  "speeding": [SpeedingEvent],
  "turning": [TurningEvent]
}

TransportDrivingEventsRequest_DrivingEventsFilterEnum

Values
Enum Value Description

SIGNIFICANT

ALL

Example
"SIGNIFICANT"

TransportFeedback

Fields
Field Name Description
status - Boolean Success/Failure status.
Example
{"status": false}

TransportFeedbackRequest_ContextEntryInput

Fields
Input Field Description
key - String!
value - String!
Example
{
  "key": "xyz789",
  "value": "abc123"
}

TransportScores

Fields
Field Name Description
safety - TransportScoresSafety
Example
{"safety": TransportScoresSafety}

TransportScoresSafety

Fields
Field Name Description
primary - PrimarySafetyScores Primary driving safety scores assigned to the transport.
secondary - SecondarySafetyScores Secondary driving safety scores assigned to the transport.
Example
{
  "primary": PrimarySafetyScores,
  "secondary": SecondarySafetyScores
}

TransportTrajectory

Fields
Field Name Description
distance - Float The total distance travelled in meters.
end_location - LocationInformation Information about the ending location of the trajectory.
map_matched_waypoints - [MapMatchedWaypoint] The map-matched waypoints of the trajectory.
polyline - String The encoded path using Google's Encoded Polyline Algorithm format.
start_location - LocationInformation Information about the starting location of the trajectory.
top_speed - Float Top speed reached in the transport in km/h.
Example
{
  "distance": 123.45,
  "end_location": LocationInformation,
  "map_matched_waypoints": [MapMatchedWaypoint],
  "polyline": "abc123",
  "start_location": LocationInformation,
  "top_speed": 987.65
}

TransportWeatherData

Fields
Field Name Description
weather_at_destination - WeatherData The weather data at the destination of the transport
weather_at_origin - WeatherData The weather data at the origin of the transport
Example
{
  "weather_at_destination": WeatherData,
  "weather_at_origin": WeatherData
}

TurningEvent

Fields
Field Name Description
category - String The main category of the turning event (e.g. turning).
duration - Float Duration of the turning event in seconds.
end_at - String The end time of the turning event in ISO 8601 format (e.g. 2022-06-26T11:26:48.351+01:00).
magnitude - Float Max magnitude of the turning, measured in m/s².
path - [PathElement] Path (waypoints) of the turning event while it lasted.
start_at - String The start time of the turning event in ISO 8601 format (e.g. 2022-06-26T11:26:48.351+01:00).
type - String The sub type of the turning event (e.g. left turn, right turn).
Example
{
  "category": "xyz789",
  "duration": 987.65,
  "end_at": "abc123",
  "magnitude": 987.65,
  "path": [PathElement],
  "start_at": "abc123",
  "type": "abc123"
}

User

Fields
Field Name Description
app_id - String App ID to which the user belongs.
created_at - String Date and time of user creation in the Sentiance platform in ISO 8601 format (e.g. 2022-06-26T11:26:48.000+00:00).
diagnostics - Diagnostics Diagnostics API for user-related events and information.
engagement - UserEngagement Engagement information e.g driver coaching score, streaks, challenges, etc.
external_id - String ID of the user given by the client application (if present).
scores - UserScores Time-aggregated driving scores of the user.
Arguments
by - String

Aggregate user scores by either DAY, WEEK, MONTH or QUARTER.

date - String

The date for which to aggregate scores in YYYY-MM-DD format. If DAY is used, the exact given date is used. If WEEK is used, the given date is backtracked to Monday. If MONTH is used, the given date is backtracked to the first day of the month. If QUARTER is used, the given date is backtracked to the first day of the quarter.

transports - [Transport] List of transports belonging to the user.
Arguments
to - String

The starting date for the search query in YYYY-MM-DD format (inclusive).

from - String

The starting date for the search query in YYYY-MM-DD format (inclusive).

user_id - String Sentiance ID of the user.
Example
{
  "app_id": "xyz789",
  "created_at": "abc123",
  "diagnostics": Diagnostics,
  "engagement": UserEngagement,
  "external_id": "xyz789",
  "scores": UserScores,
  "transports": [Transport],
  "user_id": "xyz789"
}

UserEngagement

Fields
Field Name Description
aggregations - UserEngagementAggregations Aggregations of a user.
Arguments
time_frame - TimeFrameInput

Time frame for the aggregation.

function - AggregationFunctionEnum

Type of aggregation to perform. Default is AVG

slice_by - SliceByEnum

Slice the aggregation by DAY, WEEK, MONTH or YEAR. If no option is provided, the aggregation will not be sliced and the aggregation for the entire period will pe returned.

badges - UserEngagementBadges Engagement user badges.
challenges - UserEngagementChallenges Engagement user challenges.
communications - UserEngagementCommunications Communications of a user.
groups - UserEngagementGroups Engagement user groups.
library - UserEngagementLibrary Engagement Content Library.
scores - UserEngagementScores Engagement user scores.
Arguments
transport_mode - UserEngagementScoresRequest_TransportModeEnum

Filter for transport mode. Available options: BIKING, BUS, CAR, FERRY, IDLE, RUNNING, TRAIN, TRAM, WALKING. Default: CAR.

streaks - UserEngagementStreaks Engagement user streaks.
transport - UserEngagementTransport Transport of a user by ID.
Arguments
transport_id - String

ID of the transport.

transports - UserEngagementTransports Transports of the user.
Arguments
pagination_token - String

Pagination token.

occupant_role - UserEngagementTransportsRequest_OccupantRoleEnum

Filter for occupant role of transports. Available options: ANY, DRIVER, PASSENGER, DRIVER_AND_PASSENGER and UNKNOWN. Default: ANY

in_grace_period - UserEngagementTransportsRequest_InGracePeriodEnum

Filter for transports in grace period. Available options: ALL, TRUE, FALSE. Default: ALL.

mode - UserEngagementTransportsRequest_TransportModeEnum

Filter for transport mode. Available options: ANY_MODE, BIKING, BUS, CAR, FERRY, IDLE, RUNNING, TRAIN, TRAM, WALKING, INSUFFICIENT_DATA, UNSUPPORTED_MODE. Default: CAR.

limit - Int

Number of transports to return.

Example
{
  "aggregations": UserEngagementAggregations,
  "badges": UserEngagementBadges,
  "challenges": UserEngagementChallenges,
  "communications": UserEngagementCommunications,
  "groups": UserEngagementGroups,
  "library": UserEngagementLibrary,
  "scores": UserEngagementScores,
  "streaks": UserEngagementStreaks,
  "transport": UserEngagementTransport,
  "transports": UserEngagementTransports
}

UserEngagementAggregations

Fields
Field Name Description
transports - UserEngagementTransportAggregationsSlice Engagement user aggregated data for transports.
Arguments
filters - [FilterInput]

Filters to apply before the aggregation is computed

user_id - String Sentiance ID of the user.
Example
{
  "transports": UserEngagementTransportAggregationsSlice,
  "user_id": "abc123"
}

UserEngagementBadge

Fields
Field Name Description
category - String Category of the badge.
completed_at - String Completed time in ISO 8601 format (e.g. 2022-06-26T11:26:48.351+01:00).
description - String Description of the badge.
id - String ID of the badge.
image_url - String Image URL of the badge.
level - Int Level of the badge.
name - String Name of the badge.
progress - Int Progress of the badge.
reward_text - String Reward text of the badge.
started_at - String Start time in ISO 8601 format (e.g. 2022-06-26T11:26:48.351+01:00).
status - String Status of the badge.
updated_at - String Updated time in ISO 8601 format (e.g. 2022-06-26T11:26:48.351+01:00).
Example
{
  "category": "abc123",
  "completed_at": "abc123",
  "description": "abc123",
  "id": "abc123",
  "image_url": "abc123",
  "level": 123,
  "name": "xyz789",
  "progress": 987,
  "reward_text": "xyz789",
  "started_at": "xyz789",
  "status": "abc123",
  "updated_at": "abc123"
}

UserEngagementBadges

Fields
Field Name Description
slice - [UserEngagementBadge] List of badges.
Example
{"slice": [UserEngagementBadge]}

UserEngagementChallenge

Fields
Field Name Description
accepted_at - String Accepted time in ISO 8601 format (e.g. 2022-06-26T11:26:48.351+01:00).
can_receive_feedback - Boolean Flag that marks the challenge as eligible for feedback.
category - String Category of the challenge.
challenge_id - String ID of the challenge.
count - Int Order of the challenge by difficulty.
description - String Description of the challenge.
difficulty - String Difficulty of the challenge.
ended_at - String Ended time in ISO 8601 format (e.g. 2022-06-26T11:26:48.351+01:00).
id - String Use challenge_id instead.
image_url - String Image URL of the challenge.
new - String String that has value 'new' if this challenge has never been accepted by the user. Null otherwise.
ordering - Int Order of the challenge by subcategory.
progress - Int Progress of the challenge.
status - String Status of the challenge.
subcategory - String Subcategory of the challenge.
updated_at - String Updated time in ISO 8601 format (e.g. 2022-06-26T11:26:48.351+01:00).
Example
{
  "accepted_at": "xyz789",
  "can_receive_feedback": true,
  "category": "xyz789",
  "challenge_id": "abc123",
  "count": 123,
  "description": "xyz789",
  "difficulty": "xyz789",
  "ended_at": "abc123",
  "id": "xyz789",
  "image_url": "xyz789",
  "new": "abc123",
  "ordering": 123,
  "progress": 987,
  "status": "abc123",
  "subcategory": "abc123",
  "updated_at": "abc123"
}

UserEngagementChallenges

Fields
Field Name Description
active - UserEngagementChallengesSlice Active Challenges of the user
available - UserEngagementChallengesSlice Available Challenges of the user
completed - UserEngagementChallengesSlice Completed Challenges of the user.
Example
{
  "active": UserEngagementChallengesSlice,
  "available": UserEngagementChallengesSlice,
  "completed": UserEngagementChallengesSlice
}

UserEngagementChallengesSlice

Fields
Field Name Description
slice - [UserEngagementChallenge] List of challenges.
Example
{"slice": [UserEngagementChallenge]}

UserEngagementCommunication

Fields
Field Name Description
button_label - String Button label text for communications that have a button.
button_url - String Redirect url for communications that have a button.
category - String Category of the communication.
communication_id - String ID of the communication.
context - [UserEngagementCommunicationResponse_ContextEntry] Map containing the context in which the communication was generated.
evaluation_id - String Evaluation ID of the communication.
expires_at - String Expire time in ISO 8601 format (e.g. 2022-06-26T11:26:48.351+01:00).
generated_at - String Generated time in ISO 8601 format (e.g. 2022-06-26T11:26:48.351+01:00).
message - String Message of the communication.
priority - Int Priority of the communication.
status - String Status of the communication.
title - String Title of the communication.
type - String Type of the communication.
updated_at - String Updated time in ISO 8601 format (e.g. 2022-06-26T11:26:48.351+01:00).
Example
{
  "button_label": "abc123",
  "button_url": "abc123",
  "category": "abc123",
  "communication_id": "xyz789",
  "context": [
    UserEngagementCommunicationResponse_ContextEntry
  ],
  "evaluation_id": "xyz789",
  "expires_at": "xyz789",
  "generated_at": "xyz789",
  "message": "xyz789",
  "priority": 987,
  "status": "abc123",
  "title": "xyz789",
  "type": "abc123",
  "updated_at": "xyz789"
}

UserEngagementCommunicationResponse_ContextEntry

Fields
Field Name Description
key - String
value - String
Example
{
  "key": "xyz789",
  "value": "abc123"
}

UserEngagementCommunications

Fields
Field Name Description
all - UserEngagementCommunicationsSlice All Communications of the user
Arguments
limit - Int

Number of communications to return.

category - UserEngagementCommunicationsRequest_CategoryEnum

Category of the communication. Available options: ALL, CHALLENGES, BADGES, STREAKS, SCORES, LEADERBOARD, TRIPS, PROFILE, SCHEDULED.

type - UserEngagementCommunicationsRequest_TypeEnum

Type of the communication. Available options: IN_APP_MESSAGE, REACTIVE_MESSAGE.

closed - UserEngagementCommunicationsSlice Closed Communications of the user
Arguments
limit - Int

Number of communications to return.

category - UserEngagementCommunicationsRequest_CategoryEnum

Category of the communication. Available options: ALL, CHALLENGES, BADGES, STREAKS, SCORES, LEADERBOARD, TRIPS, PROFILE, SCHEDULED.

type - UserEngagementCommunicationsRequest_TypeEnum

Type of the communication. Available options: IN_APP_MESSAGE, REACTIVE_MESSAGE.

expired - UserEngagementCommunicationsSlice Expired Communications of the user
Arguments
limit - Int

Number of communications to return.

category - UserEngagementCommunicationsRequest_CategoryEnum

Category of the communication. Available options: ALL, CHALLENGES, BADGES, STREAKS, SCORES, LEADERBOARD, TRIPS, PROFILE, SCHEDULED.

type - UserEngagementCommunicationsRequest_TypeEnum

Type of the communication. Available options: IN_APP_MESSAGE, REACTIVE_MESSAGE.

new - UserEngagementCommunicationsSlice New Communications of the user
Arguments
type - UserEngagementCommunicationsRequest_TypeEnum

Type of the communication. Available options: IN_APP_MESSAGE, REACTIVE_MESSAGE.

limit - Int

Number of communications to return.

category - UserEngagementCommunicationsRequest_CategoryEnum

Category of the communication. Available options: ALL, CHALLENGES, BADGES, STREAKS, SCORES, LEADERBOARD, TRIPS, PROFILE, SCHEDULED.

Example
{
  "all": UserEngagementCommunicationsSlice,
  "closed": UserEngagementCommunicationsSlice,
  "expired": UserEngagementCommunicationsSlice,
  "new": UserEngagementCommunicationsSlice
}

UserEngagementCommunicationsRequest_CategoryEnum

Values
Enum Value Description

SCORES

TRIPS

STREAKS

LEADERBOARD

PROFILE

SCHEDULED

ALL

CHALLENGES

BADGES

Example
"SCORES"

UserEngagementCommunicationsRequest_TypeEnum

Values
Enum Value Description

IN_APP_MESSAGE

REACTIVE_MESSAGE

Example
"IN_APP_MESSAGE"

UserEngagementCommunicationsSlice

Fields
Field Name Description
slice - [UserEngagementCommunication] List of communications.
Example
{"slice": [UserEngagementCommunication]}

UserEngagementGroup

Fields
Field Name Description
created_at - String Group creation time in ISO 8601 format (e.g. 2022-06-26T11:26:48.351+01:00).
feed - UserEngagementGroupFeed Events feed of the group.
Arguments
ranking_attr - String

Ranking attribute to populate the group feed by. Available options: bae-driver-coaching-score, bae-harsh-movement-score, bae-mffs-score, bae-adaptive-attention-score. Options applicable depending on how the group was created.

group_id - String ID of the group.
leaderboard - UserEngagementGroupLeaderboard Leaderboard of the group.
Arguments
order_by - String

Ranking attribute to order the leaderboard by. Available options: bae-driver-coaching-score, bae-harsh-movement-score, bae-mffs-score, bae-adaptive-attention-score. Options applicable depending on how the group was created.

members - UserEngagementGroupMembers Members of the group.
Arguments
order_by - String
name - String Name of the group.
reg_code - String Registration code of the group.
user_id - String Sentiance ID of the user who created the group.
Example
{
  "created_at": "xyz789",
  "feed": UserEngagementGroupFeed,
  "group_id": "abc123",
  "leaderboard": UserEngagementGroupLeaderboard,
  "members": UserEngagementGroupMembers,
  "name": "xyz789",
  "reg_code": "abc123",
  "user_id": "xyz789"
}

UserEngagementGroupFeed

Fields
Field Name Description
group_id - String ID of the group.
slice - [UserEngagementGroupFeedMessage] List of feed messages.
Example
{
  "group_id": "xyz789",
  "slice": [UserEngagementGroupFeedMessage]
}

UserEngagementGroupFeedMessage

Fields
Field Name Description
generated_at - String Time feed message was generated in ISO 8601 format (e.g. 2022-06-26T11:26:48.351+01:00).
message - String Parameterised feed message.
params - [String] List of parameters to be replaced in the feed message.
Example
{
  "generated_at": "abc123",
  "message": "abc123",
  "params": ["abc123"]
}

UserEngagementGroupLeaderboard

Fields
Field Name Description
group_id - String ID of the group.
slice - [UserEngagementGroupLeaderboardMember] List of leaderboard members.
Example
{
  "group_id": "xyz789",
  "slice": [UserEngagementGroupLeaderboardMember]
}

UserEngagementGroupLeaderboardMember

Fields
Field Name Description
rank - Int User's rank in the group's leaderboard.
ranking_attr - String Attribute by which the leaderboard was ranked.
ranking_score - Float User's score in the group's leaderboard.
user_id - String Sentiance ID of the user.
Example
{
  "rank": 987,
  "ranking_attr": "abc123",
  "ranking_score": 987.65,
  "user_id": "abc123"
}

UserEngagementGroupMember

Fields
Field Name Description
joined_at - String Join time in ISO 8601 format (e.g. 2022-06-26T11:26:48.351+01:00).
scores - UserEngagementScores User's Engagement scores.
Arguments
transport_mode - UserEngagementScoresRequest_TransportModeEnum

Filter for transport mode. Available options: BIKING, BUS, CAR, FERRY, IDLE, RUNNING, TRAIN, TRAM, WALKING. Default: CAR.

user_id - String Sentiance ID of the user.
Example
{
  "joined_at": "xyz789",
  "scores": UserEngagementScores,
  "user_id": "abc123"
}

UserEngagementGroupMembers

Fields
Field Name Description
slice - [UserEngagementGroupMember] List of group members.
Example
{"slice": [UserEngagementGroupMember]}

UserEngagementGroups

Fields
Field Name Description
slice - [UserEngagementGroup] Groups of a user,
user_id - String Sentiance ID of the user.
Example
{
  "slice": [UserEngagementGroup],
  "user_id": "xyz789"
}

UserEngagementLibrary

Fields
Field Name Description
knowledge_bites - UserEngagementLibraryKnowledgeBites Engagement knowledge bytes.
smart_tips - UserEngagementLibrarySmartTips Engagement smart tips.
Example
{
  "knowledge_bites": UserEngagementLibraryKnowledgeBites,
  "smart_tips": UserEngagementLibrarySmartTips
}

UserEngagementLibraryItem

Fields
Field Name Description
category - String Category of library item.
content - String Content of library item.
content_extra - String Extra content of library item.
created_at - String Created time in ISO 8601 format (e.g. 2022-06-26T11:26:48.351+01:00).
item_id - String ID of library item.
subcategory - String Subcategory of library item.
title - String Title of library item.
Example
{
  "category": "xyz789",
  "content": "abc123",
  "content_extra": "xyz789",
  "created_at": "xyz789",
  "item_id": "abc123",
  "subcategory": "xyz789",
  "title": "xyz789"
}

UserEngagementLibraryKnowledgeBites

Fields
Field Name Description
slice - [UserEngagementLibraryItem] List of knowledge bytes.
Example
{"slice": [UserEngagementLibraryItem]}

UserEngagementLibrarySmartTips

Fields
Field Name Description
slice - [UserEngagementLibraryItem] List of smart tips.
Example
{"slice": [UserEngagementLibraryItem]}

UserEngagementScores

Fields
Field Name Description
driving_focused - Float Driver attention score.
driving_no_speeding - Float Driver speeding score.
driving_overall - Float Driver overall score.
driving_smooth - Float Driver smooth score.
riding_call_while_moving - Float Rider cal while moving score.
riding_harsh - Float Rider harsh score.
riding_legal - Float Rider legal score.
riding_overall - Float Rider overall score.
Example
{
  "driving_focused": 123.45,
  "driving_no_speeding": 123.45,
  "driving_overall": 987.65,
  "driving_smooth": 987.65,
  "riding_call_while_moving": 123.45,
  "riding_harsh": 987.65,
  "riding_legal": 123.45,
  "riding_overall": 123.45
}

UserEngagementScoresRequest_TransportModeEnum

Values
Enum Value Description

FERRY

IDLE

TRAIN

BUS

CAR

TRAM

WALKING

BIKING

RUNNING

Example
"FERRY"

UserEngagementStreaks

Fields
Field Name Description
best - UserEngagementStreaksCount Best streaks of the user
current - UserEngagementStreaksCount Current streaks of the user.
user_id - String Sentiance ID of the user.
Example
{
  "best": UserEngagementStreaksCount,
  "current": UserEngagementStreaksCount,
  "user_id": "abc123"
}

UserEngagementStreaksCount

Fields
Field Name Description
driving_focused - Int Focused driver streak count.
driving_no_speeding - Int No speeding driver streak count.
driving_safe - Int Safe driver streak count.
driving_smooth - Int Smooth driver streak count.
riding_call_while_moving - Int Call while moving rider streak count.
riding_harsh - Int Harsh rider streak count.
riding_legal - Int Legal rider streak count.
riding_safe - Int Save rider streak count.
Example
{
  "driving_focused": 123,
  "driving_no_speeding": 123,
  "driving_safe": 987,
  "driving_smooth": 987,
  "riding_call_while_moving": 123,
  "riding_harsh": 987,
  "riding_legal": 987,
  "riding_safe": 123
}

UserEngagementTransport

Fields
Field Name Description
can_receive_feedback - Boolean Flag that marks the transport eligible to receive feedback.
created_at - String Create time in ISO 8601 format (e.g. 2022-06-26T11:26:48.351+01:00).
duration - Float Total duration in minutes.
end_at - String End time in ISO 8601 format (e.g. 2022-06-26T11:26:48.351+01:00).
in_grace_period - Boolean Flag that marks the transport as inside of the grace period or outside of grace period. Always false if grace period not enabled for user.
mode - String Mode of transport.
occupant_role - String Occupant role of the transport if mode is CAR.
scores - UserEngagementTransportScores Scores for the transport.
start_at - String Start time in ISO 8601 format (e.g. 2022-06-26T11:26:48.351+01:00).
trajectory - UserEngagementTransportTrajectory Trajectory of the transport.
transport_id - String ID of the transport.
Example
{
  "can_receive_feedback": true,
  "created_at": "abc123",
  "duration": 987.65,
  "end_at": "xyz789",
  "in_grace_period": true,
  "mode": "xyz789",
  "occupant_role": "abc123",
  "scores": UserEngagementTransportScores,
  "start_at": "abc123",
  "trajectory": UserEngagementTransportTrajectory,
  "transport_id": "abc123"
}

UserEngagementTransportAggregationsData

Fields
Field Name Description
distance - Float Value of chosen aggregation type for distance. Unit is meters.
duration - Float Value of chosen aggregation type for duration. Unit is minutes.
events - UserEngagementTransportAggregationsData_UserEngagementTransportEventsAggregations Events for the aggregation. Only applicable for CAR or BUS transport mode with occupant role DRIVER. For rest of transport modes/occupant roles this filed is ignored and null is returned.
scores - UserEngagementTransportAggregationsData_UserEngagementTransportScoresAggregations Scores for the aggregation. Only applicable for CAR or BUS transport mode with occupant role DRIVER. For rest of transport modes/occupant roles this filed is ignored and null is returned.
Example
{
  "distance": 987.65,
  "duration": 123.45,
  "events": UserEngagementTransportAggregationsData_UserEngagementTransportEventsAggregations,
  "scores": UserEngagementTransportAggregationsData_UserEngagementTransportScoresAggregations
}

UserEngagementTransportAggregationsData_UserEngagementTransportEventsAggregations

Fields
Field Name Description
call_events_count - Float Value of chosen aggregation function for call events. Ex: if aggregation type is AVG, then this field will contain the average number of call events for the given time frame.
call_events_duration - Float Value of chosen aggregation function for call events duration. Ex: if aggregation type is AVG, then this field will contain the average call events duration for the given time frame.
phone_handling_events_count - Float Value of chosen aggregation function for phone handling events. Ex: if aggregation type is AVG, then this field will contain the average phone handling events for the given time frame.
phone_handling_events_duration - Float Value of chosen aggregation function for phone handling events duration. Ex: if aggregation type is AVG, then this field will contain the average phone handling events duration for the given time frame.
Example
{
  "call_events_count": 987.65,
  "call_events_duration": 123.45,
  "phone_handling_events_count": 123.45,
  "phone_handling_events_duration": 123.45
}

UserEngagementTransportAggregationsData_UserEngagementTransportScoresAggregations

Fields
Field Name Description
driving_focused - Float Value of chosen aggregation function for driving focused score. Ex: if aggregation type is AVG, then this field will contain the average driving focused score for the given time frame.
driving_no_speeding - Float Value of chosen aggregation function for driving no speeding score. Ex: if aggregation type is AVG, then this field will contain the average driving no speeding score for the given time frame.
driving_overall - Float Value of chosen aggregation function for driving overall score. Ex: if aggregation type is AVG, then this field will contain the average driving overall score for the given time frame.
driving_smooth - Float Value of chosen aggregation function for driving smooth score. Ex: if aggregation type is AVG, then this field will contain the average driving smooth score for the given time frame.
riding_call_while_moving - Float Value of chosen aggregation function for riding call while moving score. Ex: if aggregation type is AVG, then this field will contain the average riding call while moving score for the given time frame.
riding_harsh - Float Value of chosen aggregation function for riding harsh score. Ex: if aggregation type is AVG, then this field will contain the average riding harsh score for the given time frame.
riding_legal - Float Value of chosen aggregation function for riding legal score. Ex: if aggregation type is AVG, then this field will contain the average riding legal score for the given time frame.
riding_overall - Float Value of chosen aggregation function for riding overall score. Ex: if aggregation type is AVG, then this field will contain the average riding overall score for the given time frame.
Example
{
  "driving_focused": 123.45,
  "driving_no_speeding": 123.45,
  "driving_overall": 987.65,
  "driving_smooth": 123.45,
  "riding_call_while_moving": 123.45,
  "riding_harsh": 123.45,
  "riding_legal": 123.45,
  "riding_overall": 987.65
}

UserEngagementTransportAggregationsDimensions

Fields
Field Name Description
occupant_role - String Occupant role for the aggregation. Note: only applicable for CAR or BUS transport mode. For rest of transport modes this filed is ignored and null is returned.
time_frame - TimeFrame Time frame for the aggregation.
transport_mode - String Transport mode for the aggregation.
Example
{
  "occupant_role": "xyz789",
  "time_frame": TimeFrame,
  "transport_mode": "xyz789"
}

UserEngagementTransportAggregationsMetadata

Fields
Field Name Description
function - AggregationFunctionEnum Type of aggregation performed.
slice_by - SliceByEnum How data was sliced. Can be missing if the request didn't contain a slice_by field.
Example
{"function": "AVG", "slice_by": "MONTH"}

UserEngagementTransportAggregationsSlice

Fields
Field Name Description
slice - [UserEngagementTransportsAggregations] Slice of aggregated data for the user.
Example
{"slice": [UserEngagementTransportsAggregations]}

UserEngagementTransportScores

Fields
Field Name Description
driving_focused - Float Driver trip attention score.
driving_focused_adaptive - Float Driver focused adaptive score.
driving_no_speeding - Float Driver trip speeding score.
driving_no_speeding_adaptive - Float Driver speeding adaptive score.
driving_overall - Float Driver trip overall score.
driving_overall_adaptive - Float Driver overall adaptive score.
driving_smooth - Float Driver trip smooth score.
driving_smooth_adaptive - Float Driver smooth adaptive score.
riding_call_while_moving - Float Rider trip call while moving score.
riding_call_while_moving_adaptive - Float Rider call while moving adaptive score.
riding_harsh - Float Rider trip harsh score.
riding_harsh_adaptive - Float Rider harsh adaptive score score.
riding_legal - Float Rider trip legal score.
riding_legal_adaptive - Float Rider legal adaptive score.
riding_overall - Float Rider trip overall score.
riding_overall_adaptive - Float Rider overall adaptive score.
Example
{
  "driving_focused": 123.45,
  "driving_focused_adaptive": 123.45,
  "driving_no_speeding": 123.45,
  "driving_no_speeding_adaptive": 987.65,
  "driving_overall": 123.45,
  "driving_overall_adaptive": 987.65,
  "driving_smooth": 987.65,
  "driving_smooth_adaptive": 987.65,
  "riding_call_while_moving": 987.65,
  "riding_call_while_moving_adaptive": 987.65,
  "riding_harsh": 987.65,
  "riding_harsh_adaptive": 987.65,
  "riding_legal": 987.65,
  "riding_legal_adaptive": 123.45,
  "riding_overall": 987.65,
  "riding_overall_adaptive": 123.45
}

UserEngagementTransportTrajectory

Fields
Field Name Description
distance - Float Total distance travelled in meters.
end_location - UserEngagementTransportTrajectoryLocation End location of the transport.
polyline - String The encoded path using Google's Encoded Polyline Algorithm format.
start_location - UserEngagementTransportTrajectoryLocation Start location of the transport.
Example
{
  "distance": 123.45,
  "end_location": UserEngagementTransportTrajectoryLocation,
  "polyline": "abc123",
  "start_location": UserEngagementTransportTrajectoryLocation
}

UserEngagementTransportTrajectoryLocation

Fields
Field Name Description
city - String City name.
country - String Country name.
district - String District name.
latitude - Float Latitude of the location.
longitude - Float Longitude of the location.
region - String Region name.
street - String Street name.
Example
{
  "city": "xyz789",
  "country": "xyz789",
  "district": "abc123",
  "latitude": 123.45,
  "longitude": 123.45,
  "region": "xyz789",
  "street": "xyz789"
}

UserEngagementTransports

Fields
Field Name Description
meta - UserEngagementTransportsMeta Metadata of the transport response.
slice - [UserEngagementTransport] List of transports.
Example
{
  "meta": UserEngagementTransportsMeta,
  "slice": [UserEngagementTransport]
}

UserEngagementTransportsAggregations

Fields
Field Name Description
data - UserEngagementTransportAggregationsData Data that was aggregated.
dimensions - UserEngagementTransportAggregationsDimensions Dimensions for the aggregation. All data is grouped by these dimensions except when it's not sliced, than is grouped only by transport mode and occupant role. The reason for this grouping is that this is how the Sentiance data makes sense and should be interpreted.
metadata - UserEngagementTransportAggregationsMetadata Metadata for the aggregation.
Example
{
  "data": UserEngagementTransportAggregationsData,
  "dimensions": UserEngagementTransportAggregationsDimensions,
  "metadata": UserEngagementTransportAggregationsMetadata
}

UserEngagementTransportsMeta

Fields
Field Name Description
next_token - String Pagination token to be used in the next transports request.
Example
{"next_token": "abc123"}

UserEngagementTransportsRequest_InGracePeriodEnum

Values
Enum Value Description

FALSE

ALL

TRUE

Example
"FALSE"

UserEngagementTransportsRequest_OccupantRoleEnum

Values
Enum Value Description

DRIVER_AND_PASSENGER

UNKNOWN

ANY

DRIVER

PASSENGER

Example
"DRIVER_AND_PASSENGER"

UserEngagementTransportsRequest_TransportModeEnum

Values
Enum Value Description

CAR

FERRY

RUNNING

WALKING

UNSUPPORTED_MODE

BIKING

BUS

TRAIN

TRAM

INSUFFICIENT_DATA

ANY_MODE

IDLE

Example
"CAR"

UserScores

Fields
Field Name Description
driving - UserScoresDriving
Example
{"driving": UserScoresDriving}

UserScoresDriving

Fields
Field Name Description
safety - UserScoresDrivingSafety
Example
{"safety": UserScoresDrivingSafety}

UserScoresDrivingSafety

Fields
Field Name Description
primary - PrimarySafetyScores Primary safety scores belonging to the user.
secondary - SecondarySafetyScores Secondary safety scores belonging to the user.
Example
{
  "primary": PrimarySafetyScores,
  "secondary": SecondarySafetyScores
}

WeatherData

Fields
Field Name Description
apparent_temperature - Float The apparent temperature is a measure for the human thermal comfort. On the basis of the air temperature, the apparent temperature is computed considering effects of relative humidity, wind speed and solar radiation.
cloud_cover - Float Cloud cover as a fraction between 0-1.
dew_point - Float Dew point in degrees celcius
humidity - Float Relative humidity as a fraction between 0-1.
icon - String URL of the icon representing the weather
ozone - Float deprecated; no longer available
precipitation_intensity - Float Precipitation accumulated over the past hour in millimeter
precipitation_probability - Float Probability of precipitation
pressure - Float Pressure in millibars
summary - String Textual description of the weather
sunrise - String time of sunrise
sunset - String time of sunset
temperature - Float Instantaneous temperature at 2m above ground in degrees Celsius
uv_index - Float UV Index
visibility - Float Visibility in km
wind_bearing - Float Wind direction in degrees due north
wind_gust - Float Wind gust in m/s
wind_speed - Float Wind speed in m/s
Example
{
  "apparent_temperature": 123.45,
  "cloud_cover": 123.45,
  "dew_point": 987.65,
  "humidity": 987.65,
  "icon": "abc123",
  "ozone": 123.45,
  "precipitation_intensity": 123.45,
  "precipitation_probability": 123.45,
  "pressure": 123.45,
  "summary": "xyz789",
  "sunrise": "xyz789",
  "sunset": "xyz789",
  "temperature": 987.65,
  "uv_index": 123.45,
  "visibility": 123.45,
  "wind_bearing": 987.65,
  "wind_gust": 987.65,
  "wind_speed": 123.45
}