Skip to content

DriveMotionAnalyticsClient

DriveMotion provides some APIs to support statistical analysis of historical travel data, and each API supports synchronous and asynchronous calls. In order to use these APIs, DriveMotion provides DriveMotionAnalyticsClient.

Get DriveMotionAnalyticsClient

1
2
3
4
5
    try {
        DriveMotionAnalyticsClient driveMotionAnalyticsClient = DriveMotionService.getDriveMotionAnalyticsClient();
    } catch (DriveMotionException e) {
        // The SDK is not initialized
    }

1
2
3
4
5
    try {
        val driveMotionAnalyticsClient = DriveMotionService.getDriveMotionAnalyticsClient()
    } catch (e: DriveMotionException) {
        // The SDK is not initialized
    }

Use DriveMotionAnalyticsClient

DriveMotionAnalyticsClient supports aggregate statistics on trips and scores within a certain time range, queries on trip information within a certain time range, and queries for detailed information about a certain historical trip or current active trip.

For each API, DriveMotionAnalyticsClient provides the corresponding Request entity class and its builder, and agrees on the basic behavior of Callback. Therefore, for developers, they only need to construct the request object through the builder, and then use the execute method of the request object to complete the asynchronous call of the request.

Get trips by time range (since version 1.0.0)

Get Request Builder

1
    GetTripsRequest.Builder builder = driveMotionAnalyticsClient.getTripsRequest();

1
    val builder: GetTripsRequest.Builder = driveMotionAnalyticsClient.getTripsRequest()

Build Request

GetTripsRequest needs to set some parameters. Where the start date and the end date are required, but limit and offset are optional, they can further provide paging capabilities within the time range.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
    GetTripsRequest request = builder.withStartDate(#startDate#)
                                .withEndDate(#endDate#)
                                .withLimit(#limit#)
                                .withOffset(#offset#)
                                .withSortBy(#TripSortType#)
                                .withTransportationModes(#TransportationModes#)
                                .withExcludeTripEvents(#ExcludeTripEvents#)
                                .withAsset(#assetId#, #assetContext#)
                                .withTripSelectionStatus(#TripSelectionStatus#)
                                .build();

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
    val request = builder.withStartDate(#startDate#)
                                .withEndDate(#endDate#)
                                .withLimit(#limit#)
                                .withOffset(#offset#)
                                .withSortBy(#TripSortType#)
                                .withTransportationModes(#TransportationModes#)
                                .withExcludeTripEvents(#ExcludeTripEvents#)
                                .withAsset(#assetId#, #assetContext#)
                                .withTripSelectionStatus(#TripSelectionStatus#)
                                .build()

Parameters

  • startDate: Represents the starting date of the query range.
  • endDate: Represents the ending date of the query range.
  • limit: Represents the maximum number of trips to query. The default value is 20, with a range of 0 to 100. If there are more trips than the limit, the app needs to perform pagination queries.
  • offset: Enables pagination in conjunction with the limit parameter. The offset value must be greater than or equal to 0, and is incremented by the number of results returned in the previous query.
  • sortType: Enables custom query sorting. It represents the desired sorting method and defaults to TripSortType.TRIP_START_TIME_DESC. Setting it to TripSortType.TRIP_START_TIME_ASC allows querying from the start time.
  • transportationModes: Enables custom query filtering. It represents the desired trip types to query, with a default value of null to query all valid trip types.
  • excludeTripEvents: Indicates whether to include TripEvents details in the return value. The default value is true, indicating that it is not required.
  • tripSelectionStatus: when operating in cloud mode. This parameter allows filtering trips based on their selection status.

Implement Callback

Callback is an interface, and developers need to specify its response type. It provides two callback entries for success and failure.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
    Callback<GetTripsResponse> callback = new Callback<GetTripsResponse>() {

        @Override
        public void onSuccess(GetTripsResponse getTripsResponse) {
            // Do something
        }

        @Override
        public void onFailure(Throwable throwable) {
            // Do something
        }
    }

1
2
3
4
5
6
7
8
9
    val callback = object : Callback<GetTripsResponse> {
        override fun onSuccess(getTripsResponse: GetTripsResponse) {
            // Do something
        }

        override fun onFailure(throwable: Throwable) {
            // Do something
        }
    }

Get trip detail by trip id (since version 1.0.0)

Get Request Builder

1
    GetTripDetailRequest.Builder builder = driveMotionAnalyticsClient.getTripDetailRequest();

1
    val builder = driveMotionAnalyticsClient.getTripDetailRequest()

Build Request

GetTripDetailRequest needs to set trip id, assetId and assetContext. This API only supports the query of the trip that has finished.

1
    GetTripDetailRequest request = builder.withTripId(#tripId#).withAsset(#assetId#, #assetContext#).build();

1
    val request = builder.withTripId(#tripId#).withAsset(#assetId#, #assetContext#).build()

Implement Callback

Callback is an interface, and developers need to specify its response type. It provides two callback entries for success and failure.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
    Callback<GetTripDetailResponse> callback = new Callback<GetTripDetailResponse>() {

        @Override
        public void onSuccess(GetTripDetailResponse getTripDetailResponse) {
            // Do something
        }

        @Override
        public void onFailure(Throwable throwable) {
            // Do something
        }
    }

1
2
3
4
5
6
7
8
9
    val callback = object : Callback<GetTripDetailResponse> {
        override fun onSuccess(getTripDetailResponse: GetTripDetailResponse) {
            // Do something
        }

        override fun onFailure(throwable: Throwable) {
            // Do something
        }
    }

Get live trip detail (since version 1.0.0)

Get Request Builder

1
    GetLiveTripDetailRequest.Builder builder = driveMotionAnalyticsClient.getLiveTripDetailRequest();

1
    val builder = driveMotionAnalyticsClient.getLiveTripDetailRequest()

Build Request

GetLiveTripDetailRequest does not require any parameters. Because there can only be at most one live trip at any time.

1
    GetLiveTripDetailRequest request = builder.build();

1
    val request = builder.build()

Implement Callback

Callback is an interface, and developers need to specify its response type. It provides two callback entries for success and failure.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
    Callback<GetLiveTripDetailResponse> callback = new Callback<GetLiveTripDetailResponse>() {

        @Override
        public void onSuccess(GetLiveTripDetailResponse getLiveTripDetailResponse) {
            // Do something
        }

        @Override
        public void onFailure(Throwable throwable) {
            // Do something
        }
    }

1
2
3
4
5
6
7
8
9
    val callback = object : Callback<GetLiveTripDetailResponse> {
        override fun onSuccess(getLiveTripDetailResponse: GetLiveTripDetailResponse) {
            // Do something
        }

        override fun onFailure(throwable: Throwable) {
            // Do something
        }
    }

Get config descriptions by requested config type (since version 1.1.0)

Get Request Builder

1
    GetConfigDescriptionsRequest.Builder builder = driveMotionAnalyticsClient.getConfigDescriptionsRequest();

1
    val builder = driveMotionAnalyticsClient.getConfigDescriptionsRequest()

Build Request

GetConfigDescriptionsRequest require set type id to query the corresponding type description data. 

1
2
3
    GetConfigDescriptionsRequest request = builder
            .setType(GetConfigDescriptionsRequest.Type.SCORE_FACTOR_DESCRIPTION)
            .build();

1
2
3
    val request = builder
            .setType(GetConfigDescriptionsRequest.Type.SCORE_FACTOR_DESCRIPTION)
            .build()

Implement Callback

Callback is an interface, and developers need to specify its response type. It provides two callback entries for success and failure.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
    Callback<GetConfigDescriptionsResponse> callback = new Callback<GetConfigDescriptionsResponse>() {

        @Override
        public void onSuccess(GetConfigDescriptionsResponse getConfigDescriptionsResponse) {
            // Do something
        }

        @Override
        public void onFailure(Throwable throwable) {
            // Do something
        }
    }

1
2
3
4
5
6
7
8
9
    val callback = object : Callback<GetConfigDescriptionsResponse> {
        override fun onSuccess(getConfigDescriptionsResponse: GetConfigDescriptionsResponse) {
            // Do something
        }

        override fun onFailure(throwable: Throwable) {
            // Do something
        }
    }

Get the latest trip detail (since version 1.1.0)

Get Request Builder

1
    GetLatestTripDetailRequest.Builder builder = driveMotionAnalyticsClient.getLatestTripDetailRequest();

1
    val builder = driveMotionAnalyticsClient.getLatestTripDetailRequest()

Build Request

GetLatestTripDetailRequest requires assetId and assetContext to get the lastest trip detail. But this API only fetch the latest finished trip.

1
2
    GetLatestTripDetailRequest request = builder.withAsset(#assetId#, #assetContext#)
                                .build();

1
2
    val request = builder.withAsset(#assetId#, #assetContext#)
                                .build()

Implement Callback

Callback is an interface, and developers need to specify its response type. It provides two callback entries for success and failure.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
    Callback<GetLatestTripDetailResponse> callback = new Callback<GetLatestTripDetailResponse>() {

        @Override
        public void onSuccess(GetLatestTripDetailResponse getLatestTripDetailResponse) {
            // Do something
        }

        @Override
        public void onFailure(Throwable throwable) {
            // Do something
        }
    }

1
2
3
4
5
6
7
8
9
    val callback = object : Callback<GetLatestTripDetailResponse> {
        override fun onSuccess(getLatestTripDetailResponse: GetLatestTripDetailResponse) {
            // Do something
        }

        override fun onFailure(throwable: Throwable) {
            // Do something
        }
    }

Update trip transportation mode (since version 1.2.0)

Get Request Builder

1
    UpdateTripTransportationModeRequest.Builder builder = driveMotionAnalyticsClient.updateTripTransportationModeRequest();

1
    val builder = driveMotionAnalyticsClient.updateTripTransportationModeRequest()

Build Request

UpdateTripTransportationModeRequest needs to set required tripId and transportationMode.

1
2
3
    UpdateTripTransportationModeRequest request = builder.withTripId(#tripIdWhichNeedUpdate#)
                                        .withTransportationMode(#expectedTransportationMode#)
                                        .build();

1
2
3
    val request = builder.withTripId(#tripIdWhichNeedUpdate#)
                                        .withTransportationMode(#expectedTransportationMode#)
                                        .build()

Implement Callback

Callback is an interface, and developers need to specify its response type. It provides two callback entries for success and failure.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
    Callback<UpdateTripTransportationModeResponse> callback = new Callback<UpdateTripTransportationModeResponse>() {

        @Override
        public void onSuccess(UpdateTripTransportationModeResponse updateTripTransportationModeResponse) {
            // Do something
        }

        @Override
        public void onFailure(Throwable throwable) {
            // Do something
        }
    }

1
2
3
4
5
6
7
8
9
    val callback = object : Callback<UpdateTripTransportationModeResponse> {
        override fun onSuccess(updateTripTransportationModeResponse: UpdateTripTransportationModeResponse) {
            // Do something
        }

        override fun onFailure(throwable: Throwable) {
            // Do something
        }
    }

Get Streaks (since version 1.2.1)

Get Request Builder

1
    GetStreaksRequest.Builder builder = driveMotionAnalyticsClient.getStreaksRequest();

1
    val builder = driveMotionAnalyticsClient.getStreaksRequest()

Build Request

GetStreaksRequest requires assetId and assetContext, API will response with current streak and best streak for each score factors.

1
    GetStreaksRequest request = builder.withAsset(#assetId#, #assetContext#).build();

1
    val request = builder.withAsset(#assetId#, #assetContext#).build()

Implement Callback

Callback is an interface, and developers need to specify its response type. It provides two callback entries for success and failure.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
    Callback<GetStreaksResponse> callback = new Callback<GetStreaksResponse>() {

        @Override
        public void onSuccess(GetStreaksResponse getStreaksResponse) {
            // Do something
        }

        @Override
        public void onFailure(Throwable throwable) {
            // Do something
        }
    }

1
2
3
4
5
6
7
8
9
    val callback = object : Callback<GetStreaksResponse> {
        override fun onSuccess(getStreaksResponse: GetStreaksResponse) {
            // Do something
        }

        override fun onFailure(throwable: Throwable) {
            // Do something
        }
    }

Get aggregated safety score by time range (since version 2.0.0)

Get Request Builder

1
    AggregatedSafetyScoreRequest.Builder builder = driveMotionAnalyticsClient.aggregatedSafetyScoreRequest();

1
    val builder = driveMotionAnalyticsClient.aggregatedSafetyScoreRequest()

Build Request

Note

It is necessary to ensure that the called startDate and endDate represent complete days, meaning from 00:00:00 on the start day to midnight on the end day.

1
2
3
4
5
6
7
8
9
    AggregatedSafetyScoreRequest request = builder.withStartDate(#startDate#)
            .withEndDate(#endDate#)
            .withIntervalType(#IntervalType#)
            .withIntervalFilter(#IntervalFilter#)
            .withScoreCreatedTime(#Date#)
            .withAsset(#assetId#, #assetContext#)
            .withTimeZoneId(#timeZoneId#)
            .withScoreVersion(#scoreVersion#)
            .build();

1
2
3
4
5
6
7
8
9
        val request = builder.withStartDate(#startDate#)
            .withEndDate(#endDate#)
            .withIntervalType(#IntervalType#)
            .withIntervalFilter(#IntervalFilter#)
            .withScoreCreatedTime(#Date#)
            .withAsset(#assetId#, #assetContext#)
            .withTimeZoneId(#timeZoneId#)
            .withScoreVersion(#scoreVersion#)
            .build()

Parameters

  • startDate: Represents the starting date of the query range (SDK will use 0:00:00 of the day).
  • endDate: Represents the ending date of the query range (SDK will use 23:59:59 of the day).
  • intervalType: Represents the interval type of safety score (per DAY or Week)
  • scoreCreatedTime: Represents the score created time in UTC.
  • assetId: Represents the vehicle's ID (value can be "VIN" or "Channel client id" based on type of assetContext). (If null, the API retrieves the aggregated safety score for the current user.)
  • assetContext: Represents the context for assetId, if is "CAR", assetId value should be VIN, otherwise assetId should be Channel client id.
  • timeZoneId: Represents the time zone id, Example: America/Denver
  • scoreVersion: Represents the score version for calculating safety score.

Implement Callback

Callback is an interface, and developers need to specify its response type. It provides two callback entries for success and failure.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
    Callback<AggregatedSafetyScoreResponse> callback = new Callback<AggregatedSafetyScoreResponse>() {

        @Override
        public void onSuccess(AggregatedSafetyScoreResponse aggregatedSafetyScoreResponse) {
            // Do something
        }

        @Override
        public void onFailure(Throwable throwable) {
            // Do something
        }
    }

1
2
3
4
5
6
7
8
9
    val callback = object : Callback<AggregatedSafetyScoreResponse> {
        override fun onSuccess(aggregatedSafetyScoreResponse: AggregatedSafetyScoreResponse) {
            // Do something
        }

        override fun onFailure(throwable: Throwable) {
            // Do something
        }
    }

Complete call

Note

asyncCall method is deprecated from 1.2.1 and will be removed in next few releases. Please using execute method to process call in asynchronous.

1
2
3
4
5
6
    // Asynchronous call
    request.execute(callback);

    // Asynchronous call
    @Deprecated
    request.asyncCall(callback);

1
2
3
4
5
6
    // Asynchronous call
    request.execute(callback)

    // Asynchronous call
    @Deprecated
    request.asyncCall(callback)

Sync trips from cloud

Get Request Builder

1
    SyncTripsRequest.Builder builder = driveMotionAnalyticsClient.syncTripsRequest();

1
    val builder = driveMotionAnalyticsClient.syncTripsRequest()

Build Request

SyncTripsRequest has no parameters, API will sync trips from cloud.

1
    SyncTripsRequest request = builder.build();

1
    val request = builder.build()

Implement Callback

Callback is an interface, and developers need to specify its response type. It provides two callback entries for success and failure.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
    Callback<SyncTripsResponse> callback = new Callback<SyncTripsResponse>() {

        @Override
        public void onSuccess(SyncTripsResponse syncTripsResponse) {
            // Success or Failure
        }

        @Override
        public void onFailure(Throwable throwable) {
            // Do something
        }
    }

1
2
3
4
5
6
7
8
9
    val callback = object : Callback<SyncTripsResponse> {
        override fun onSuccess(syncTripsResponse: SyncTripsResponse) {
            // Success or Failure
        }

        override fun onFailure(throwable: Throwable) {
            // Do something
        }
    }

Get simulated safety score (since 2.2.0)

Get Request Builder

1
2
3
4
    GetSimulatedSafetyScoreRequest.Builder builder = driveMotionAnalyticsClient.getSimulatedSafetyScoreRequest();

    // Cloud Mode
    GetSimulatedSafetyScoreRequest.Builder cloudModeBuilder = driveMotionAnalyticsClient.withConnectionMode(#ConnectionMode#).getSimulatedSafetyScoreRequest()

1
2
3
4
    val builder = driveMotionAnalyticsClient.getSimulatedSafetyScoreRequest()

    // Cloud Mode
    val cloudModeBuilder = driveMotionAnalyticsClient.withConnectionMode(#ConnectionMode#).getSimulatedSafetyScoreRequest()

Build Request

GetSimulatedSafetyScoreRequest needs to set required tripsInfo and tripsEventStatistics and state. Other parameters scoreVersion is optional, default scoreVersion is least safety socre algorithms.

1
2
3
4
5
    GetSimulatedSafetyScoreRequest request = builder.withTripsInfo(#basicTripsInfo#)
                                        .withTripsEventStatistics(#List<EventStatistics>#)
                                        .withState(#State#)
                                        .withScoreVersion(#ScoreVersion#) // optional
                                        .build();

1
2
3
4
5
    val request = builder.withTripsInfo(#basicTripsInfo#)
                        .withTripsEventStatistics(#List<EventStatistics>#)
                        .withState(#State#)
                        .withScoreVersion(#ScoreVersion#) // optional
                        .build()

Implement Callback

Callback is an interface, and developers need to specify its response type. It provides two callback entries for success and failure.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
    Callback<GetSimulatedSafetyScoreResponse> callback = new Callback<GetSimulatedSafetyScoreResponse>() {

        @Override
        public void onSuccess(GetSimulatedSafetyScoreResponse simulatedSafetyScoreResponse) {
            // Success or Failure
        }

        @Override
        public void onFailure(Throwable throwable) {
            // Do something
        }
    }

1
2
3
4
5
6
7
8
9
    val callback = object : Callback<GetSimulatedSafetyScoreResponse> {
        override fun onSuccess(simulatedSafetyScoreResponse: GetSimulatedSafetyScoreResponse) {
            // Success or Failure
        }

        override fun onFailure(throwable: Throwable) {
            // Do something
        }
    }

Get event percentile table (since 2.4.0)

Get Request Builder

1
    GetEventPercentileTableRequest.Builder builder = driveMotionAnalyticsClient.getEventPercentileTableRequest();

1
    val builder = driveMotionAnalyticsClient.getEventPercentileTableRequest()

Build Request

GetEventPercentileTableRequest needs to set required eventType and state. scoreVersion is optional, default scoreVersion is least safety socre algorithms(Deprecated - since 2.4.0).

1
2
3
4
    GetEventPercentileTableRequest request = builder.withEventType(#EventType.SPEEDING#)
                                        .withState(#State#)
                                        .withScoreVersion(#ScoreVersion#) // optional
                                        .build();

1
2
3
4
    val request = builder.withEventType(#EventType.SPEEDING#)
                        .withState(#State#)
                        .withScoreVersion(#ScoreVersion#) // optional
                        .build()

GetEventPercentileTableRequest needs to set required state. scoreVersion is optional, default scoreVersion is least safety socre algorithms(since 2.7.0).

1
2
3
    GetEventPercentileTableRequest request = builder.withState(#State#)
                                        .withScoreVersion(#ScoreVersion#) // optional
                                        .build();

1
2
3
    val request = builder.withState(#State#)
                        .withScoreVersion(#ScoreVersion#) // optional
                        .build()

Implement Callback

Callback is an interface, and developers need to specify its response type. It provides two callback entries for success and failure.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
    Callback<GetEventPercentileTableResponse> callback = new Callback<GetEventPercentileTableResponse>() {

        @Override
        public void onSuccess(GetEventPercentileTableResponse eventPercentileTableResponse) {
            // Success or Failure
        }

        @Override
        public void onFailure(Throwable throwable) {
            // Do something
        }
    }

1
2
3
4
5
6
7
8
9
    val callback = object : Callback<GetEventPercentileTableResponse> {
        override fun onSuccess(eventPercentileTableResponse: GetEventPercentileTableResponse) {
            // Success or Failure
        }

        override fun onFailure(throwable: Throwable) {
            // Do something
        }
    }

Get Cumulative Safety Score (since 2.18.x)

This API retrieves the cumulative safety score for a specified vehicle or user within a given date range.

Usage

To fetch the cumulative safety score, use the GetCumulativeSafetyScoreRequest API.

Example Usage

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
DriveMotionService.driveMotionAnalyticsClient
    .withConnectionMode(ConnectionMode.CLOUD)
    .getCumulativeSafetyScoreRequest()
    .withStartDate(#startDate#)
    .withEndDate(#endDate#)
    .withScoreCreatedTime(#scoreCreatedTime#)
    .withTimeZoneId(#timeZoneId#)
    .withScoreBaseTime(#scoreBaseTime#)
    .withScoreVersion(#scoreVersion#)
    .withIntervalType(#intervalType#)
    .withAsset(#assetId#, #assetContext#)
    .build()
    .execute(object : Callback<GetCumulativeSafetyScoreResponse> {
    override fun onSuccess(cumulativeSafetyScoreResponse: GetCumulativeSafetyScoreResponse) {
        // Do something
    }

    override fun onFailure(throwable: Throwable) {
        // Do something
})

Parameters

  • startDate (Date): The start date of the period for which the safety score is calculated.
  • endDate (Date): The end date of the period for which the safety score is calculated.
  • assetId (String, Optional): Vehicle's ID (value can be "VIN" or "Channel client id" based on type of assetContext). (If null, the API retrieves the cumulative safety score for the user.)
  • scoreBaseTime (Date, Optional) the calculation of the CumulativeSafetyScore based on the start period of trip
  • assetContext (Enum(CAR,GLOBAL)): Context for assetId, if is "CAR", assetId value should be VIN, otherwise assetId should be Channel client id.

Response

The API returns the cumulative safety score based on the provided date range.

Error Handling

If the request fails, an error object is provided in the callback.

Get Contextual Coaching Statistics (since 2.23.0)

GetContextualCoachingStatisticsRequest is to retrieve the contextual coaching statistics and standouts for a specified vehicle or user within given date ranges.

Get Request Builder

1
    GetContextualCoachingStatisticsRequest.Builder builder = driveMotionAnalyticsClient.getContextualCoachingStatisticsRequest();

1
    val builder = driveMotionAnalyticsClient.getContextualCoachingStatisticsRequest()

Build Request

GetContextualCoachingStatisticsRequest needs to set some parameters. The current period date range is required, while previous period date range is optional. Other parameters like groupBy and rankBy are also optional.

1
2
3
4
5
6
7
8
    GetContextualCoachingStatisticsRequest request = builder.withCurrentPeriod(#startDate#, #endDate#)
                                        .withPreviousPeriod(#startDate#, #endDate#)
                                        .withAsset(#assetId#, #assetContext#)
                                        .withTimezone(#timezone#)
                                        .withScoreVersion(#scoreVersion#)
                                        .groupBy(#Set<ContextualCoachingGroupFactor>#)
                                        .rankBy(#Set<ContextualCoachingRankMetrics>#)
                                        .build();

1
2
3
4
5
6
7
8
    val request = builder.withCurrentPeriod(#startDate#, #endDate#)
                        .withPreviousPeriod(#startDate#, #endDate#)
                        .withAsset(#assetId#, #assetContext#)
                        .withTimezone(#timezone#)
                        .withScoreVersion(#scoreVersion#)
                        .groupBy(#Set<ContextualCoachingGroupFactor>#)
                        .rankBy(#Set<ContextualCoachingRankMetrics>#)
                        .build()

Parameters

  • currentPeriod: The current period date range for which the statistics are calculated (required).
  • previousPeriod: The previous period date range for comparison (optional).
  • assetId: Represents the vehicle's ID (value can be "VIN" or "Channel client id" based on type of assetContext). (If null, the API retrieves the statistics for the current user.)
  • assetContext: Represents the context for assetId, if is "CAR", assetId value should be VIN, otherwise assetId should be Channel client id.
  • timezone: Represents the time zone id, Example: America/Denver
  • scoreVersion: The version of the score algorithm, if not set, the latest version will be used.
  • groupBy: Group factors for the statistics, null for calculate all the factors.
  • rankBy: Rank metrics for the statistics, null for calculate all the metrics.

Implement Callback

Callback is an interface, and developers need to specify its response type. It provides two callback entries for success and failure.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
    Callback<GetContextualCoachingStatisticsResponse> callback = new Callback<GetContextualCoachingStatisticsResponse>() {

        @Override
        public void onSuccess(GetContextualCoachingStatisticsResponse response) {
            // Do something
        }

        @Override
        public void onFailure(Throwable throwable) {
            // Do something
        }
    }

1
2
3
4
5
6
7
8
9
    val callback = object : Callback<GetContextualCoachingStatisticsResponse> {
        override fun onSuccess(response: GetContextualCoachingStatisticsResponse) {
            // Do something
        }

        override fun onFailure(throwable: Throwable) {
            // Do something
        }
    }

Response

The API returns the contextual coaching statistics based on the provided parameters, including: - Current period statistics - Previous period statistics (if provided) - Standouts for each group factor and rank metric

Error Handling

If the request fails, an error object is provided in the callback.

Post Contextual Coaching Request (since 3.7.0)

This API initiates a contextual coaching analysis for a specific time period. It uses an asynchronous processing pattern where you first post a request to initiate the analysis, then use the returned coaching ID to retrieve the results.

Get Request Builder

1
    PostContextualCoachingRequest.Builder builder = driveMotionAnalyticsClient.postContextualCoachingRequest(startTime, endTime, timeZoneId);

1
    val builder = driveMotionAnalyticsClient.postContextualCoachingRequest(startTime, endTime, timeZoneId)

Build Request

PostContextualCoachingRequest needs to set the time range and timezone. Additional parameters like asset, score version, group factors, and rank metrics are optional.

1
2
3
4
5
    PostContextualCoachingRequest request = builder.withAsset(#assetId#, #assetContext#)
                                        .withScoreVersion(#scoreVersion#)
                                        .groupBy(#Set<GroupFactor>#)
                                        .rankBy(#Set<RankMetrics>#)
                                        .build();

1
2
3
4
5
    val request = builder.withAsset(#assetId#, #assetContext#)
                        .withScoreVersion(#scoreVersion#)
                        .groupBy(#Set<GroupFactor>#)
                        .rankBy(#Set<RankMetrics>#)
                        .build()

Parameters

  • startTime: Represents the start date and time of the analysis period.
  • endTime: Represents the end date and time of the analysis period.
  • timeZoneId: Represents the time zone id, Example: "America/New_York".
  • assetId: Represents the vehicle's ID (value can be "VIN" or "Channel client id" based on type of assetContext). (If null, the API retrieves the statistics for the current user.)
  • assetContext: Represents the context for assetId, if is "CAR", assetId value should be VIN, otherwise assetId should be Channel client id.
  • scoreVersion: The version of the score algorithm, if not set, the latest version will be used.
  • groupBy: Group factors for the statistics (TimeOfDay, DayOfWeek, DayOfMonth, TripLength).
  • rankBy: Rank metrics for the statistics (HardAccelerationPerMile, HardBrakingPerMile, SpeedingPerMile).

Implement Callback

Callback is an interface, and developers need to specify its response type. It provides two callback entries for success and failure.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
    Callback<PostContextualCoachingResponse> callback = new Callback<PostContextualCoachingResponse>() {

        @Override
        public void onSuccess(PostContextualCoachingResponse response) {
            if (response.getStatus() == ResponseStatus.SUCCESS) {
                String coachingId = response.getResult().getCoachingId();
                // Use coachingId for GetContextualCoachingRequest
            }
        }

        @Override
        public void onFailure(Throwable throwable) {
            // Handle error
        }
    }

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
    val callback = object : Callback<PostContextualCoachingResponse> {
        override fun onSuccess(response: PostContextualCoachingResponse) {
            if (response.status == ResponseStatus.SUCCESS) {
                val coachingId = response.result?.coachingId
                // Use coachingId for GetContextualCoachingRequest
            }
        }

        override fun onFailure(throwable: Throwable) {
            // Handle error
        }
    }

Get Contextual Coaching Request (since 3.7.0)

This API retrieves the contextual coaching results using the coaching ID returned from the Post Contextual Coaching Request. You need to check the processing status and may need to retry if the analysis is still pending.

Get Request Builder

1
    GetContextualCoachingRequest.Builder builder = driveMotionAnalyticsClient.getContextualCoachingRequest(coachingId);

1
    val builder = driveMotionAnalyticsClient.getContextualCoachingRequest(coachingId)

Build Request

GetContextualCoachingRequest requires the coaching ID returned from the post request.

1
    GetContextualCoachingRequest request = builder.build();

1
    val request = builder.build()

Parameters

  • coachingId: The coaching ID returned from PostContextualCoachingResponse.

Implement Callback

Callback is an interface, and developers need to specify its response type. It provides two callback entries for success and failure.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
    Callback<GetContextualCoachingResponse> callback = new Callback<GetContextualCoachingResponse>() {

        @Override
        public void onSuccess(GetContextualCoachingResponse response) {
            if (response.getStatus() == ResponseStatus.SUCCESS) {
                ContextualCoachingResult result = response.getResult();

                switch (result.getCoachingStatus()) {
                    case COMPLETED:
                        if (result.getStatusReason() == null) {
                            // Process statistics
                        } else {
                            // Handle task error
                        }
                        break;
                    case PENDING:
                    case PROCESSING:
                        // Retry after delay
                        break;
                    case FAILED:
                        // Handle cloud error
                        break;
                }
            }
        }

        @Override
        public void onFailure(Throwable throwable) {
            // Handle error
        }
    }

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
    val callback = object : Callback<GetContextualCoachingResponse> {
        override fun onSuccess(response: GetContextualCoachingResponse) {
            if (response.status == ResponseStatus.SUCCESS) {
                val result = response.result
                when (result?.coachingStatus) {
                    ProcessStatus.COMPLETED -> {
                        if (result.statusReason == null) {
                            // Process statistics
                        } else {
                            // Handle task error
                        }
                    }
                    ProcessStatus.PENDING, ProcessStatus.PROCESSING -> {
                        // Retry after delay
                    }
                    ProcessStatus.FAILED -> {
                        // Handle cloud error
                    }
                }
            }
        }

        override fun onFailure(throwable: Throwable) {
            // Handle error
        }
    }

Processing Status

The Get Contextual Coaching Request may return different processing statuses: - COMPLETED: The analysis is complete and ready. Check statusReason to determine if successful. - PENDING/PROCESSING: The analysis is still in progress. Retry after a delay. - FAILED: The analysis failed. Handle the error appropriately.

Get Trips by IDs (since 3.7.0)

This API retrieves specific trips using their unique identifiers. This is useful when you know the exact trip IDs you need to retrieve.

Get Request Builder

1
    GetTripsByIdsRequest.Builder builder = driveMotionAnalyticsClient.getTripsByIdsRequest(tripIds);

1
    val builder = driveMotionAnalyticsClient.getTripsByIdsRequest(tripIds)

Build Request

GetTripsByIdsRequest requires a list of trip IDs. Maximum 50 trips per request in cloud mode. The API requires vehicle-based requests using asset parameters.

1
2
3
4
    GetTripsByIdsRequest request = builder.withAsset(#assetId#, #assetContext#)
                                        .withExcludeTripEvents(#excludeTripEvents#)
                                        .withExcludeTripRoute(#excludeTripRoute#)
                                        .build();

1
2
3
4
    val request = builder.withAsset(#assetId#, #assetContext#)
                        .withExcludeTripEvents(#excludeTripEvents#)
                        .withExcludeTripRoute(#excludeTripRoute#)
                        .build()

Parameters

  • tripIds: List of trip IDs to retrieve (max 50 for cloud mode).
  • assetId: Represents the vehicle's ID (value can be "VIN" or "Channel client id" based on type of assetContext).
  • assetContext: Represents the context for assetId, if is "CAR", assetId value should be VIN, otherwise assetId should be Channel client id.
  • excludeTripEvents: If true, excludes trip events from the response (default: false).
  • excludeTripRoute: If true, excludes trip route points from the response (default: false).

Implement Callback

Callback is an interface, and developers need to specify its response type. It provides two callback entries for success and failure.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
    Callback<GetTripsResponse> callback = new Callback<GetTripsResponse>() {

        @Override
        public void onSuccess(GetTripsResponse response) {
            List<BasicTrip> trips = response.getTrips();
            // Process trips
        }

        @Override
        public void onFailure(Throwable throwable) {
            // Handle error
        }
    }

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
    val callback = object : Callback<GetTripsResponse> {
        override fun onSuccess(response: GetTripsResponse) {
            val trips = response.trips
            // Process trips
        }

        override fun onFailure(throwable: Throwable) {
            // Handle error
        }
    }

Cloud Mode Limit

When operating in cloud mode, the maximum number of trips that can be retrieved per request is 50. If you need to retrieve more trips, split your requests accordingly.

Asset Required

This API requires vehicle-based requests. You must provide assetId and assetContext using the withAsset() method.