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 coaching score by time range

AggregatedScoreRequest

Attribute	Type	Default	Required	Description
startDate	Date		Yes	iso format (date + timezone) - date level or hr/minute
endDate	Date		Yes	iso format (date + timezone)
intervalType	IntervalType	null	No	Return multiple scores by different level of intervals. E.g. if interval is week, return weekly driving score.
assetId	String	null	No	Vehicle ID (VIN or channel client id)
assetContext	Enum(CAR,GLOBAL)		No	Context for assetId

IntervalType

Name
DAY
WEEK
MONTH

AggregatedScoreResponse

Attribute	Type	Default	Required	Description
aggregatedScore	AggregatedScore		Yes	Aggregated score

AggregatedScore

Attribute	Type	Default	Required	Description
score	DriveScore		Yes	Aggregated score
tripsInfo	TripsInfo		Yes	Aggregated trips info
tripsEventStatistics	List<EventStatistic>		Yes	number of events by event type for all trips.
intervalScores	List<IntervalScore>		No	Aggregated score by interval

TripsInfo

Attribute	Type	Default	Required	Description
totalTripCount	Integer	0	Yes	The total number of trips
totalDuration	Integer	0	Yes	The total duration of all trips in seconds
totalDistance	Double	0.0	Yes	The total distance of all trips in meters
totalMovingDuration	Integer		No	Total trip moving duration (gps speed is larger than 0) in seconds
totalNightDuration	Integer		No	Total trip night duration in seconds (local time 10pm - 4am)
totalNightMovingDuration	Integer		No	Total trip night moving duration (gps speed is larger than 0) in seconds (local time 10pm - 4am)
totalNightDistance	Double		No	Total trip night distance in meters (local time 10pm - 4am)
firstTripStartTime	Date		No	first trip start time of aggregated trips info
lastTripStarttime	Date		No	last trip start time of aggregated trips info

IntervalScore

Attribute	Type	Default	Required	Description
intervalType	IntervalType		Yes	Required interval Type Enum
startDate	Date		Yes	First day of each interval
score	DriveScore		Yes	Aggregated score each interval
tripsInfo	TripsInfo		Yes	Aggregated trips info each interval
tripsEventStatistics	List<EventStatistic>		Yes	number of events by event type for all trips.

DriveScore

Attribute	Type	Default	Required	Description
safetyScore	Integer		Yes(Deprecated)	Range: [0 - 100], using score instead.
score	Integer		Yes	Range: [0 - 100]
scoreVersion	String		No	Score Version String
scoreType	ScoreType		No	Identify this score type
scoreFactors	List<ScoreFactor>		No
...				Can be extended in future. e.g ecoDrivingScore

ScoreType

Name
COACHING
SAFETY

ScoreFactor

Attribute	Type	Default	Required	Description
score	Integer		Yes	range: 0 - 100
type	String		Yes	subScoreType: Acceleration, Braking, Cornering, Speeding, Distraction, Weather, TimeOfDay

ScoreFactorType

Name
ACCELERATION("Acceleration")
BRAKING("Braking")
CORNERING("Cornering")
DISTRACTION("Distraction")
SPEEDING("Speeding")
WEATHER("Weather")
TIME_OF_DAY("TimeOfDay")
MILES_DRIVEN("MilesDriven")

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	ScoreVersion		No	The version of safety score algorithm.

SafetyIntervalType

Name
DAY
WEEK

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
safetyScore	Integer		Yes(Deprecated)	Range: [0 - 100], using score instead.
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

Name
AND
OR

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	ScoreVersion		No	The version of safety score algorithm.
scoreBaseTime	Date		No	the calculation of the CumulativeSafetyScore based on the start period of trip

CumulativeSafetyScoreIntervalType

Name
INCREMENTAL

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 cumulative score by fixed time window

GetCumulativeScoreRequest

Attribute	Type	Default	Required	Description
lastNumOfDays	Integer	0	No	Return historic score and sub scores. Greater than 0 and less than 30 days.
assetId	String	null	No	Vehicle Identification
assetContext	Enum(CAR,GLOBAL)		No	Context for assetId

GetCumulativeScoreResponse

Attribute	Type	Default	Required	Description
cumulativeScore	CumulativeScore		Yes

CumulativeScore

Attribute	Type	Default	Required	Description
currentScore	DriveScore		Yes	cumulative score by score interval
interval	Integer		Yes	Week → 7, FortNIGHT → 14, Month → 30
tripsInfo	TripsInfo		Yes
historicalScores	List<HistoricalScore>		No	historic cumulative score by historic range

HistoricalScore

Attribute	Type	Default	Required	Description
date	Date		Yes	date of historical cumulative score.
score	DriveScore		Yes	overall score

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
score	DriveScore		Yes	Trip drive score
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
score	DriveScore		Yes	Trip score
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	Enum		No

State

Name
AZ
AK
... 51 State

ScoreVersion

Name
V1_0_3
V1_0_4
V1_0_5

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

Name
Short
Medium
Long

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