DriveMotionAnalytics
Common API Objects
Common Response
| Attribute |
Type |
Default |
Required |
Description |
| status |
ResponseStatus |
|
Yes |
Response Status Enum |
| message |
String |
|
No |
|
| t |
T |
|
No |
Data Object |
ResponseStatus
| Code |
Name |
| 32200 |
SUCCESS |
| 32400 |
INVALID_REQUEST |
| 32500 |
INTERNAL_SERVER_ERROR |
Get aggregated safety score by time range
AggregatedSafetyScoreRequest
| Attribute |
Type |
Default |
Required |
Description |
| startDate |
Date |
|
Yes |
iso format (date + timezone) - date level or hr/minute |
| endDate |
Date |
|
Yes |
iso format (date + timezone) |
| assetId |
String |
null |
No |
Vehicle ID (VIN or channel client id) |
| assetContext |
Enum(CAR,GLOBAL) |
|
No |
Context for assetId |
| timeZoneId |
String |
null |
No |
Time Zone ID, Example: America/Denver |
| intervalType |
SafetyIntervalType |
null |
No |
Return multiple scores by different level of intervals. E.g. if interval is week, return weekly driving score. |
| intervalFilter |
IntervalFilter |
ALL |
No |
Effective when intervalType is not null. |
| scoreCreatedTime |
Date |
|
No |
UTC timestamp which score created. Passing to Omni by score_created_time field. |
| scoreVersion |
String |
|
No |
The version of safety score algorithm. |
SafetyIntervalType
IntervalFilter
| Name |
| EVENT_ONLY |
| SCORE_ONLY |
| ALL |
AggregatedSafetyScoreResponse
| Attribute |
Type |
Default |
Required |
Description |
| aggregatedSafetyScore |
AggregatedSafetyScore |
|
No |
Aggregated safety score |
AggregatedSafetyScore
| Attribute |
Type |
Default |
Required |
Description |
| score |
DriveScore |
|
No |
Aggregated safety score |
| tripsInfo |
TripsInfo |
|
No |
Aggregated trips info |
| vehicleInfo |
VehicleInfo |
|
No |
Vehicle's odometer readings |
| tripsEventStatistics |
List<EventStatistic> |
|
No |
Number of events by event type for all trips. |
| safetyIntervalScores |
List<SafetyIntervalScore> |
|
No |
Aggregated safety score by interval |
| tripsRating |
Rating |
|
No |
Aggregated trips rating by interval |
DriveScore
| Attribute |
Type |
Default |
Required |
Description |
| score |
Integer |
|
Yes |
Range: [0 - 100] |
| scoreVersion |
String |
|
No |
Score Version String |
| scoreType |
ScoreType |
|
No |
Identify this score type |
| scoreDetail |
ScoreDetail |
|
No |
Coaching score will not have this detail object. |
| scoreFactors |
List<ScoreFactor> |
|
No |
|
| ... |
|
|
|
Can be extended in future. e.g ecoDrivingScore |
VehicleInfo
| Attribute |
Type |
Default |
Required |
Description |
| startOdometer |
Double |
|
Yes |
Start of the first trip (in kilometers) |
| startOdometerTime |
Integer |
|
Yes |
Start time of the first trip (in millisecond) |
| endOdometer |
Double |
|
Yes |
End of the last trip (in kilometers) |
| endOdometerTime |
Integer |
|
Yes |
End time of the first trip (in millisecond) |
ScoreDetail
| Attribute |
Type |
Default |
Required |
Description |
| scoreStartDate |
Date |
|
No |
start date base on aggregatedSafetyScoreInterval setting |
| scoreEndDate |
Date |
|
No |
|
| scoreQualified |
Boolean |
|
No |
true - qualified safety score, false - unqualified safety score. |
| scoreUnqualifiedReason |
String |
|
No |
|
| scoreQualifiedCriteria |
String |
|
No |
|
| scoreCreatedTime |
Date |
|
No |
score_created_time timestamp from Omni in UTC. |
| scoreQualificationCriteria |
Condition |
|
No |
|
Condition
| Attribute |
Type |
Default |
Required |
Description |
| operation |
OperationType |
|
No |
|
| conditions |
List |
|
No |
|
| criteriaType |
CriteriaType |
|
No |
|
| criteriaValue |
String |
|
No |
|
OperationType
CriteriaType
| Name |
| MINIMUM_TRIP_COUNT |
| MINIMUM_MILEAGE |
SafetyIntervalScore
| Attribute |
Type |
Default |
Required |
Description |
| intervalType |
SafetyIntervalType |
|
No |
Required interval Type Enum |
| startDate |
Date |
|
No |
First day of each interval |
| tripsInfo |
TripsInfo |
|
No |
Aggregated trips info each interval |
| tripsEventStatistics |
List<EventStatistic> |
|
No |
number of events by event type for all trips. |
| score |
DriveScore |
|
No |
Aggregated score each interval |
Get cumulative safety score by time range
CumulativeSafetyScoreRequest
| Attribute |
Type |
Default |
Required |
Description |
| startDate |
Date |
|
Yes |
iso format (date + timezone) - date level or hr/minute |
| endDate |
Date |
|
Yes |
iso format (date + timezone) |
| assetId |
String |
null |
No |
Vehicle ID (VIN or channel client id) |
| assetContext |
Enum(CAR,GLOBAL) |
|
No |
Context for assetId |
| timeZoneId |
String |
null |
No |
Time Zone ID, Example: America/Denver |
| intervalType |
CumulativeSafetyScoreIntervalType |
null |
No |
interval level from start date to current date |
| scoreCreatedTime |
Date |
|
No |
UTC timestamp which score created. Passing to Omni by score_created_time field. |
| scoreVersion |
String |
|
No |
The version of safety score algorithm. |
| scoreBaseTime |
Date |
|
No |
the calculation of the CumulativeSafetyScore based on the start period of trip |
CumulativeSafetyScoreIntervalType
CumulativeSafetyScoreResponse
| Attribute |
Type |
Default |
Required |
Description |
| cumulativeSafetyScore |
CumulativeSafetyScore |
|
Yes |
|
CumulativeSafetyScore
| Attribute |
Type |
Default |
Required |
Description |
| intervalType |
CumulativeSafetyScoreIntervalType |
|
Yes |
cumulative safety score by score interval |
| historicalSafetyScores |
List<HistoricalSafetyScore> |
|
No |
historic cumulative safety score by historic range |
HistoricalSafetyScore
| Attribute |
Type |
Default |
Required |
Description |
| endDate |
Date |
|
No |
Last day of each interval |
| tripsInfo |
TripsInfo |
|
No |
Cumulative trips info each interval |
| tripsEventStatistics |
List<EventStatistic> |
|
No |
number of events by event type for all trips. |
| score |
DriveScore |
|
No |
Cumulative score each interval |
Get score factor descriptions
GetConfigDescriptionsRequest
| Attribute |
Type |
Default |
Required |
Description |
| type |
GetConfigDescriptionsRequest.Type |
|
Yes |
|
GetConfigDescriptionsRequest.Type
| Name |
| SCORE_FACTOR_DESCRIPTION |
GetConfigDescriptionsResponse
| Attribute |
Type |
Default |
Required |
Description |
| descriptions |
List<DescriptionItem> |
|
Yes |
|
DescriptionItem
| Attribute |
Type |
Default |
Required |
Description |
| type |
String |
|
Yes |
Same with factor's type |
| label |
String |
|
Yes |
The display label for this factor |
| detail |
String |
|
Yes |
The detail description for this factor |
Get trips by time range
GetTripsRequest
| Attribute |
Type |
Default |
Required |
Description |
| startDate |
Date |
|
Yes |
|
| endDate |
Date |
|
Yes |
|
| limit |
Integer |
20 |
No |
Limit on the number of trips to be returned, Default value 20 and max limit is 100. |
| offset |
Integer |
0 |
No |
Offset is the index of object that defines your place in the list, starting with 0, only take effect when limit is not 0. |
| sortBy |
TripSortType |
TRIP_START_TIME_DESC |
No |
Trips sort order. Enum: TRIP_START_TIME_ASC/TRIP_START_TIME_DESC |
| transportationModes |
Array[TransportationMode] |
null |
No |
Trips transportation modes which request such as: \<DRIVER, PASSENGER>, Default value is null for all type of trips. |
| assetId |
String |
null |
No |
Vehicle ID (VIN or channel client id) |
| assetContext |
Enum(CAR,GLOBAL) |
|
No |
Context for assetId |
| tripSelectionStatus |
TripSelectionStatus |
|
No |
The value indicate matching different set of trips |
TripSortType
| Name |
| TRIP_START_TIME_ASC |
| TRIP_START_TIME_DESC |
TripSelectionStatus
| Name |
| SELECTED |
| DUPLICATE |
| UNKNOWN |
GetTripsResponse
| Attribute |
Type |
Default |
Required |
Description |
| hasMore |
boolean |
|
Yes |
Indicates if has more results in next page. |
| trips |
List<BasicTrip> |
|
Yes |
The trips that hit the request query condition |
BasicTrip
| Attribute |
Type |
Default |
Required |
Description |
| tripInfo |
TripInfo |
|
Yes |
Trip summary info |
| score |
DriveScore |
|
Yes |
Trip score |
| tripEventStatistics |
List<EventStatistic> |
|
Yes |
Trip event statistics |
| tripEvents |
List<Event> |
|
No |
Trip events |
| tripRating |
Rating |
|
No |
Trip rating |
Rating
| Attribute |
Type |
Default |
Required |
Description |
| ratingScaled |
Int |
|
Yes |
The scaled rating value belongs to the requested lower bound and upper bound. Value is [1, 10]. |
| ratingFactors |
List |
|
No |
factors of rating. |
| ratingVersion |
String |
|
No |
|
RatingFactor
| Attribute |
Type |
Default |
Required |
Description |
| ratingScaled |
Int |
|
Yes |
The scaled rating value belongs to the requested lower bound and upper bound. |
| type |
String |
|
No |
Same as ScoreFactor type, only has Acceleration, Brake, Speeding. |
TripInfo
| Attribute |
Type |
Default |
Required |
Description |
| tripId |
String |
|
Yes |
Trip id |
| startTime |
Date |
|
Yes |
Trip start time |
| endTime |
Date |
|
Yes |
Trip end time |
| startLocation |
Location |
|
Yes |
Trip start location |
| endLocation |
Location |
|
Yes |
Trip end location |
| duration |
Integer |
|
Yes |
Trip duration time in seconds |
| distance |
Double |
|
Yes |
Trip distance in meters |
| maxSpeed |
Double |
|
No |
Trip max speed in meters per seconds |
| transportationMode |
TransportationMode |
|
No |
Trip transportation mode or label |
| movingDuration |
Integer |
|
No |
Trip moving duration (gps speed is larger than 0) in seconds |
| nightDuration |
Integer |
|
No |
Trip night duration in seconds (local time 10pm - 4am) |
| nightMovingDuration |
Integer |
|
No |
Trip night moving duration (gps speed is larger than 0) in seconds (local time 10pm - 4am) |
| nightDistance |
Double |
|
No |
Trip night distance in meters (local time 10pm - 4am) |
| isAnonymized |
boolean |
|
Yes |
Whether the data is truncated. |
| isUploaded |
boolean |
|
Yes |
Whether the trip has been uploaded. |
| isMatch |
boolean |
|
No |
Whether the trip matches the selection criteria. |
| tripSelectionStatus |
TripSelectionStatus |
|
No |
The status of the trip selection, which can be either valid or duplicate |
TripSelectionStatus
| Name |
| SELECTED |
| DUPLICATE |
| UNKNOWN |
Update trip transportation mode labeling by trip id
UpdateTripTransportationModeRequest
| Attribute |
Type |
Default |
Required |
Description |
| tripId |
String |
|
Yes |
The trip id which need to update |
| transportationMode |
TransportationMode |
|
Yes |
The trip's transportation mode which manually specified by user. |
TransportationMode
| Name |
| DRIVER |
| PASSENGER |
| TRAIN |
| AIRPLANE |
| BIKE |
| BOAT |
| BUS |
| MOTORCYCLE |
| FOOT |
| OTHER |
UpdateTripTransportationModeResponse
| Attribute |
Type |
Default |
Required |
Description |
| trip |
Trip |
|
No |
The trip info with updated transportation mode. |
Get trip detail by trip id
GetTripDetailRequest
| Attribute |
Type |
Default |
Required |
Description |
| tripId |
String |
|
Yes |
Trip id |
| assetId |
String |
|
No |
Vehicle ID (VIN or channel client id) |
| assetContext |
Enum (car, global) |
|
No |
Context for assetId |
GetTripDetailResponse
| Attribute |
Type |
Default |
Required |
Description |
| trip |
Trip |
|
No |
|
Trip
| Attribute |
Type |
Default |
Required |
Description |
| tripInfo |
TripInfo |
|
Yes |
Trip information |
| tripEventStatistics |
List<EventStatistic> |
|
Yes |
Event statistic information |
| tripEvents |
List<Event> |
|
No |
Trip events |
| tripRating |
Rating |
|
No |
Trip rating |
| tripRoute |
List<Location> |
|
Yes |
Trip route points for the whole trip |
EventStatistic
| Attribute |
Type |
Default |
Required |
Description |
| eventType |
EventType |
|
Yes |
Event Type Enum |
| count |
Integer |
|
Yes |
The total count of this event type. |
| distance |
Double |
|
No |
The distance (meters) of event. |
| duration |
Double |
|
No |
The duration (seconds) of event. |
EventType
| label |
Name |
| HardBrake |
HARD_BRAKE |
| HardAcceleration |
HARD_ACCELERATION |
| SharpTurn |
SHARP_TURN |
| Speeding |
SPEEDING |
| DriverDistraction |
DRIVER_DISTRACTION |
Event
| Attribute |
Type |
Default |
Required |
Description |
| eventTime |
Date |
|
Yes |
Event time |
| eventType |
EventType |
|
Yes |
Event Type Enum |
| eventLocation |
Location |
|
Yes |
Event location |
| eventLevel |
EventLevel |
|
No |
Level: LOW/MEDIUM/HIGH |
| eventDetails |
List<EventItem> |
|
No |
|
EventItem
| Attribute |
Type |
Default |
Required |
Description |
| itemType |
EventItemType |
|
Yes |
event item type |
| itemLevel |
enum |
|
No |
Different levels of event item. |
| itemStartTime |
Date |
|
Yes |
event item start time. |
| itemStartLocation |
Location |
|
Yes |
event item start location. |
| itemEndTime |
Date |
|
No |
event item end time. |
| itemEndLocation |
Location |
|
No |
event item end location. |
Location
| Attribute |
Type |
Default |
Required |
Description |
| lat |
double |
|
Yes |
Location Latitude |
| lon |
double |
|
Yes |
Location Longitude |
| label |
String |
|
No |
Location label |
| time |
Date |
|
No |
location timestamp in milliseconds |
| isPredict |
boolean |
|
Yes |
Is this location predicted by routing. |
Get latest trip detail
GetLatestTripDetailRequest
| Attribute |
Type |
Default |
Required |
Description |
| assetId |
String |
|
No |
Vehicle ID (VIN or channel client id) |
| assetContext |
Enum(CAR,GLOBAL) |
|
No |
Context for assetId |
GetLatestTripDetailResponse
| Attribute |
Type |
Default |
Required |
Description |
| trip |
Trip |
|
Yes |
|
Get trip detail for live trip
GetLiveTripDetailResponse
| Attribute |
Type |
Default |
Required |
Description |
| liveTrip |
LiveTrip |
|
No |
|
LiveTrip
| Attribute |
Type |
Default |
Required |
Description |
| liveTripInfo |
LiveTripInfo |
|
Yes |
Live trip information |
| tripEventStatistics |
List<EventStatistic> |
|
Yes |
Event statistic information |
| tripEvents |
List<Event> |
|
No |
Trip events |
LiveTripInfo
| Attribute |
Type |
Default |
Required |
Description |
| tripId |
String |
|
Yes |
Trip id |
| startTime |
Date |
|
Yes |
Trip start time |
| startLocation |
Location |
|
Yes |
Trip start location |
| lastUpdateTime |
Date |
|
Yes |
Last update time |
| lastUpdateLocation |
Location |
|
Yes |
Last update location |
| distance |
double |
|
Yes |
Trip distance in meters |
Get Streaks
GetStreaksRequest
| Attribute |
Type |
Default |
Required |
Description |
| assetId |
String |
|
No |
Vehicle ID (VIN or channel client id) |
| assetContext |
Enum(CAR,GLOBAL) |
|
No |
Context for assetId |
GetStreaksResponse
| Attribute |
Type |
Default |
Required |
Description |
| streaks |
List<Streak> |
|
Yes |
|
Streak
| Attribute |
Type |
Default |
Required |
Description |
| eventType |
EventType |
|
Yes |
Same with EventStatistic event_type |
| current |
StreakStatistic |
|
Yes |
Streak statistics for current |
| best |
StreakStatistic |
|
Yes |
Streak statistics for best |
StreakStatistic
| Attribute |
Type |
Default |
Required |
Description |
| startTime |
Date |
|
No |
|
| endTime |
Date |
|
No |
|
| tripCount |
Integer |
|
No |
|
| distance |
Double |
|
No |
trip distance in meters |
| duration |
Integer |
|
No |
trip duration in seconds |
Get simulated safety score
GetSimulatedSafetyScoreRequest
| Attribute |
Type |
Default |
Required |
Description |
| tripsInfo |
BasicTripsInfo |
|
Yes |
total trip distance in meters |
| tripsEventStatistics |
List<EventStatistic> |
|
Yes |
|
| state |
String |
|
No |
|
| score_version |
String |
|
No |
Should be same as getAggregatedSafetyScore.score.scoreVersion |
BasicTripsInfo
| Attribute |
Type |
Default |
Required |
Description |
| totalTripCount |
Int |
|
Yes |
total trip count |
| totalDistance |
number |
|
Yes |
total trip distance in meters |
GetSimulatedSafetyScoreResponse
| Attribute |
Type |
Default |
Required |
Description |
| aggregatedSafetyScore |
AggregatedSafetyScore |
|
No |
|
| status |
ResponseStatus |
|
Yes |
32200 - Success 32400 - Invalid Request 32500 - Internal Service Error |
Get event percentile table
GetEventPercentileTableRequest
| Attribute |
Type |
Default |
Required |
Description |
| state |
Enum |
|
Yes |
such as: "AZ" |
| scoreVersion |
String |
|
No |
|
State
GetEventPercentileTableResponse
| Attribute |
Type |
Default |
Required |
Description |
| eventPercentileTable |
EventPercentileTable |
|
No |
all event percentile value(count = 100) |
| status |
ResponseStatus |
|
Yes |
32200 - Success 32400 - Invalid Request 32500 - Internal Service Error |
EventPercentileTable
| Attribute |
Type |
Default |
Required |
Description |
| haCountPerMile |
List |
|
Yes |
hard acceleration count per mile |
| hbCountPerMile |
List |
|
Yes |
hard braking count per mile |
| spDistanceOverSpeedLimitPerMile |
List |
|
Yes |
speed distance over the speed limit per mile |
Get contextual coaching statistics
GetContextualCoachingStatisticsRequest
| Attribute |
Type |
Default |
Required |
Description |
| currentPeriod |
Pair |
|
Yes |
The current period date range for which the statistics are calculated. |
| previousPeriod |
Pair |
null |
No |
The previous period date range for comparison. |
| assetId |
String |
null |
No |
Vehicle ID (VIN or channel client id). If null, the API retrieves the statistics for the current user. |
| assetContext |
Enum(CAR,GLOBAL) |
|
No |
Context for assetId, if is "CAR", assetId value should be VIN, otherwise assetId should be Channel client id. |
| timezone |
String |
null |
No |
Time Zone ID, Example: America/Denver. Required for Safety Score and Insurance. Usually, it's policy timezone. |
| scoreVersion |
String |
null |
No |
The version of the score algorithm. If not set, the latest version will be used. |
| groupBy |
Set |
null |
No |
Group factors for the statistics. If null, calculate all the factors. |
| rankBy |
Set |
null |
No |
Rank metrics for the statistics. If null, calculate all the metrics. |
ContextualCoachingGroupFactor
| Name |
| TimeOfDay |
| DayOfMonth |
| DayOfWeek |
| TripLength |
TimeOfDay
| Name |
| Morning |
| Noon |
| LateAfternoon |
| EarlyNight |
| LateNight |
DayOfMonth
| Attribute |
Type |
Description |
| year |
Integer |
Calendar.YEAR |
| month |
Integer |
Calendar.MONTH + 1 |
| day |
Integer |
Calendar.DAY_OF_MONTH |
DayOfWeek
| Name |
| Sunday |
| Monday |
| Tuesday |
| Wednesday |
| Thursday |
| Friday |
| Saturday |
TripLength
ContextualCoachingRankMetrics
| Name |
| Score |
| HardAccelerationPerMile |
| HardBrakingPerMile |
| SpeedingPerMile |
GetContextualCoachingStatisticsResponse
| Attribute |
Type |
Default |
Required |
Description |
| status |
ResponseStatus |
|
Yes |
Provides the response status |
| message |
String |
null |
No |
Response message |
| previousStatistics |
ContextualCoachingStatisticsBundle |
null |
No |
Previous period statistics detail |
| currentStatistics |
ContextualCoachingStatisticsBundle |
null |
No |
Current period statistics detail |
| standouts |
Map<ContextualCoachingGroupFactor, Map<ContextualCoachingRankMetrics, ContextualCoachingStandouts>> |
null |
No |
Standouts detail |
ContextualCoachingStatisticsBundle
| Attribute |
Type |
Description |
| aggregatedMetrics |
ContextualCoachingStatisticsMetrics |
Aggregated metrics for the period |
| statistics |
Map |
Statistics grouped by factor |
ContextualCoachingStatistics
| Attribute |
Type |
Description |
| buckets |
Map |
Statistics metrics for each factor bucket |
ContextualCoachingStatisticsMetrics
| Attribute |
Type |
Description |
| trips |
List |
List of trips in this metrics |
| score |
DriveScore |
Drive score for this metrics |
| valueByMetrics |
Map |
Values for each rank metric |
| totalTrips |
Integer |
Total number of trips |
| totalMiles |
Double |
Total distance in miles |
ContextualCoachingStandouts
| Attribute |
Type |
Description |
| upper |
ContextualCoachingStandoutsMetrics |
Upper bound standouts metrics |
| lower |
ContextualCoachingStandoutsMetrics |
Lower bound standouts metrics |
ContextualCoachingStandoutsMetrics
| Attribute |
Type |
Description |
| trips |
Map<ContextualCoachingFactorBucket, List<BasicTrip>> |
Trips for each factor bucket |
| aggregateScoreImpacted |
Integer |
Aggregate score impact |