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

Java

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

Kotlin

    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 aggregated drive score by time range (since version 1.0.0)

Get Request Builder

Java

    AggregatedScoreRequest.Builder builder = driveMotionAnalyticsClient.aggregatedScoreRequest();

Kotlin

    val builder = driveMotionAnalyticsClient.aggregatedScoreRequest()

Build Request

AggregatedScoreRequest needs to set some parameters. The start date and the end date are required to define the time range for query. IntervalType is optional, and currently supports three modes: calendar month, calendar week, and daily. It can further provide unit aggregation capabilities within the time range.

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.

Java

    AggregatedScoreRequest request = builder.withStartDate(#startDate#)
                                        .withEndDate(#endDate#)
                                        .withIntervalType(#IntervalType#)
                                        .withAsset(#assetId#, #assetContext#)
                                        .build();

Kotlin

    val request = builder.withStartDate(#startDate#)
                                        .withEndDate(#endDate#)
                                        .withIntervalType(#IntervalType#)
                                        .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.

Java

    Callback<AggregatedScoreResponse> callback = new Callback<AggregatedScoreResponse>() {

        @Override
        public void onSuccess(AggregatedScoreResponse aggregatedScoreResponse) {
            // Do something
        }

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

Kotlin

    val callback = object : Callback<AggregatedScoreResponse> {
        override fun onSuccess(aggregatedScoreResponse: AggregatedScoreResponse) {
            // Do something
        }

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

Info

Method ScoreFactorType.getType(displayName: String) can be used to parse the type field in ScoreFactor.

Get trips by time range (since version 1.0.0)

Get Request Builder

Java

    GetTripsRequest.Builder builder = driveMotionAnalyticsClient.getTripsRequest();

Kotlin

    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.

Java

    GetTripsRequest request = builder.withStartDate(#startDate#)
                                .withEndDate(#endDate#)
                                .withLimit(#limit#)
                                .withOffset(#offset#)
                                .withSortBy(#TripSortType#)
                                .withTransportationModes(#TransportationModes#)
                                .withExcludeTripEvents(#ExcludeTripEvents#)
                                .withAsset(#assetId#, #assetContext#)
                                .withTripSelectionStatus(#TripSelectionStatus#)
                                .build();

Kotlin

    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.

Java

    Callback<GetTripsResponse> callback = new Callback<GetTripsResponse>() {

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

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

Kotlin

    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

Java

    GetTripDetailRequest.Builder builder = driveMotionAnalyticsClient.getTripDetailRequest();

Kotlin

    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.

Java

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

Kotlin

    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.

Java

    Callback<GetTripDetailResponse> callback = new Callback<GetTripDetailResponse>() {

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

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

Kotlin

    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

Java

    GetLiveTripDetailRequest.Builder builder = driveMotionAnalyticsClient.getLiveTripDetailRequest();

Kotlin

    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.

Java

    GetLiveTripDetailRequest request = builder.build();

Kotlin

    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.

Java

    Callback<GetLiveTripDetailResponse> callback = new Callback<GetLiveTripDetailResponse>() {

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

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

Kotlin

    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

Java

    GetConfigDescriptionsRequest.Builder builder = driveMotionAnalyticsClient.getConfigDescriptionsRequest();

Kotlin

    val builder = driveMotionAnalyticsClient.getConfigDescriptionsRequest()

Build Request

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

Java

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

Kotlin

    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.

Java

    Callback<GetConfigDescriptionsResponse> callback = new Callback<GetConfigDescriptionsResponse>() {

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

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

Kotlin

    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

Java

    GetLatestTripDetailRequest.Builder builder = driveMotionAnalyticsClient.getLatestTripDetailRequest();

Kotlin

    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.

Java

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

Kotlin

    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.

Java

    Callback<GetLatestTripDetailResponse> callback = new Callback<GetLatestTripDetailResponse>() {

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

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

Kotlin

    val callback = object : Callback<GetLatestTripDetailResponse> {
        override fun onSuccess(getLatestTripDetailResponse: GetLatestTripDetailResponse) {
            // Do something
        }

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

Get cumulative drive score by fixed time window (since version 1.1.0)

Get Request Builder

Java

    GetCumulativeScoreRequest.Builder builder = driveMotionAnalyticsClient.getCumulativeScoreRequest();

Kotlin

    val builder = driveMotionAnalyticsClient.getCumulativeScoreRequest()

Build Request

GetCumulativeScoreRequest requires optional lastNumOfDays for historic score and sub scores, and the valid days number is greater than 0 and less than or equal to 30 days, as well as parameters assetId and assetContext.

Java

    GetCumulativeScoreRequest request = builder.setLastNumOfDays(#lastNumOfDays#)
                                        .withAsset(#assetId#, #assetContext#)
                                        .build();

Kotlin

    val request = builder.setLastNumOfDays(#lastNumOfDays#)
                                        .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.

Java

    Callback<GetCumulativeScoreResponse> callback = new Callback<GetCumulativeScoreResponse>() {

        @Override
        public void onSuccess(GetCumulativeScoreResponse getCumulativeScoreResponse) {
            // Do something
        }

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

Kotlin

    val callback = object : Callback<GetCumulativeScoreResponse> {
        override fun onSuccess(getCumulativeScoreResponse: GetCumulativeScoreResponse) {
            // Do something
        }

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

Update trip transportation mode (since version 1.2.0)

Get Request Builder

Java

    UpdateTripTransportationModeRequest.Builder builder = driveMotionAnalyticsClient.updateTripTransportationModeRequest();

Kotlin

    val builder = driveMotionAnalyticsClient.updateTripTransportationModeRequest()

Build Request

UpdateTripTransportationModeRequest needs to set required tripId and transportationMode.

Java

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

Kotlin

    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.

Java

    Callback<UpdateTripTransportationModeResponse> callback = new Callback<UpdateTripTransportationModeResponse>() {

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

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

Kotlin

    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

Java

    GetStreaksRequest.Builder builder = driveMotionAnalyticsClient.getStreaksRequest();

Kotlin

    val builder = driveMotionAnalyticsClient.getStreaksRequest()

Build Request

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

Java

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

Kotlin

    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.

Java

    Callback<GetStreaksResponse> callback = new Callback<GetStreaksResponse>() {

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

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

Kotlin

    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

Java

    AggregatedSafetyScoreRequest.Builder builder = driveMotionAnalyticsClient.aggregatedSafetyScoreRequest();

Kotlin

    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.

Java

    AggregatedSafetyScoreRequest request = builder.withStartDate(#startDate#)
            .withEndDate(#endDate#)
            .withIntervalType(#IntervalType#)
            .withIntervalFilter(#IntervalFilter#)
            .withScoreCreatedTime(#Date#)
            .withAsset(#assetId#, #assetContext#)
            .withTimeZoneId(#timeZoneId#)
            .withScoreVersion(#scoreVersion#)
            .build();

Kotlin

        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.

Java

    Callback<AggregatedSafetyScoreResponse> callback = new Callback<AggregatedSafetyScoreResponse>() {

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

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

Kotlin

    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.

Java

    // Asynchronous call
    request.execute(callback);

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

Kotlin

    // Asynchronous call
    request.execute(callback)

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

Sync trips from cloud

Get Request Builder

Java

    SyncTripsRequest.Builder builder = driveMotionAnalyticsClient.syncTripsRequest();

Kotlin

    val builder = driveMotionAnalyticsClient.syncTripsRequest()

Build Request

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

Java

    SyncTripsRequest request = builder.build();

Kotlin

    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.

Java

    Callback<SyncTripsResponse> callback = new Callback<SyncTripsResponse>() {

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

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

Kotlin

    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

Java

    GetSimulatedSafetyScoreRequest.Builder builder = driveMotionAnalyticsClient.getSimulatedSafetyScoreRequest();

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

Kotlin

    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.

Java

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

Kotlin

    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.

Java

    Callback<GetSimulatedSafetyScoreResponse> callback = new Callback<GetSimulatedSafetyScoreResponse>() {

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

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

Kotlin

    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

Java

    GetEventPercentileTableRequest.Builder builder = driveMotionAnalyticsClient.getEventPercentileTableRequest();

Kotlin

    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).

Java(Deprecated)

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

Kotlin(Deprecated)

    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).

Java

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

Kotlin

    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.

Java

    Callback<GetEventPercentileTableResponse> callback = new Callback<GetEventPercentileTableResponse>() {

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

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

Kotlin

    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

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

Java

    GetContextualCoachingStatisticsRequest.Builder builder = driveMotionAnalyticsClient.getContextualCoachingStatisticsRequest();

Kotlin

    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.

Java

    GetContextualCoachingStatisticsRequest request = builder.withCurrentPeriod(#startDate#, #endDate#)
                                        .withPreviousPeriod(#startDate#, #endDate#)
                                        .withAsset(#assetId#, #assetContext#)
                                        .withTimezone(#timezone#)
                                        .withScoreVersion(#scoreVersion#)
                                        .groupBy(#Set<ContextualCoachingGroupFactor>#)
                                        .rankBy(#Set<ContextualCoachingRankMetrics>#)
                                        .build();

Kotlin

    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.

Java

    Callback<GetContextualCoachingStatisticsResponse> callback = new Callback<GetContextualCoachingStatisticsResponse>() {

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

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

Kotlin

    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.