Skip to content

DriveMotionAnalyticsClient

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

Get TNDriveMotionAnalyticsClient

1
2
3
4
5
    do {
        let driveMotionAnalyticsClient = try TNDriveMotionService.getDriveMotionAnalyticsClient()
    } catch {
        // The SDK is not initialized
    }

1
2
3
4
5
    NSError *error;
    TNDriveMotionAnalyticsClient *client = [TNDriveMotionService getDriveMotionAnalyticsClientWithError:&error];
    if (error) {
        // The SDK is not initialized
    }

Use TNDriveMotionAnalyticsClient

TNDriveMotionAnalyticsClient 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, TNDriveMotionAnalyticsClient 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, create a call object and then use the execute method of the request object to complete the asynchronous call of the request.

Note

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

Get aggregated drive score by time range (since version 1.0.0)

Get Request Builder

1
    let builder = driveMotionAnalyticsClient.aggregatedScoreRequest()

1
    TNAggregatedScoreRequestBuilder *builder = [driveMotionAnalyticsClient aggregatedScoreRequest];

Build Request

TNAggregatedScoreRequest needs to set some parameters. The start date and the end date are required to define the time range for query. TNIntervalType 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.

1
2
3
4
5
    let request = builder.startDate(#startDate#)
                         .endDate(#endDate#)
                         .intervalType(#IntervalType#)
                         .asset(#assetId#, #assetContext#)
                         .build()

1
2
3
4
5
    [builder startDate:#startDate#];
    [builder endDate:#endDate#];
    [builder intervalType:#IntervalType#];
    [builder asset:#assetId#: #assetContext#];
    TNAggregatedScoreRequest *request = [builder build];

Create a Call and execute it

Callback is a closure accepting response and error parameters.

1
2
3
4
5
6
7
8
9
    let call = TNAggregatedScoreCall()
    call.execute(request: request) { (response, error) in
        if let response = response {
            // Handle response
        }
        if let error = error {
            // Handle error
        }
    }

1
2
3
4
5
6
7
8
9
    TNAggregatedScoreCall *call = [TNAggregatedScoreCall new];
    [call executeWithRequest:request callback:^(TNAggregatedScoreResponse * _Nullable response, TNDriveMotionException * _Nullable error) {
        if (response) {
            // Handle response
        }
        if (error) {
            // Handle error
        }
    }];

Info

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

Get trips by time range (since version 1.0.0)

Get Request Builder

1
    let builder = driveMotionAnalyticsClient.getTripsRequest()

1
    TNGetTripsRequestBuilder *builder = [driveMotionAnalyticsClient getTripsRequest];

Build Request

TNGetTripsRequest 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
    let request = builder.startDate(#startDate#)
                         .endDate(#endDate#)
                         .limit(#limit#)
                         .offset(#offset#)
                         .sortType(#tripSortType#)
                         .transportationModes(#transportationModes#)
                         .excludeTripEvents(#excludeTripEvents#)
                         .asset(#assetId#, #assetContext#)
                         .tripSelectionStatus(#TripSelectionStatus#)
                         .build()

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
    [builder startDate:#startDate#];
    [builder endDate:#endDate#];
    [builder limit:#limit#];
    [builder offset:#offset#];
    [builder sortType:#sortType#];
    [builder transportationModes:#transportationModes#];
    [builder excludeTripEvents:#excludeTripEvents#];
    [builder asset:#assetId#: #assetContext#];
    [builder tripSelectionStatus:#TripSelectionStatus#]
    TNGetTripsRequest *request = [builder 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.tripStartTimeDESC. Setting it to TripSortType.tripStartTimeASC 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.

Create a call and execute it

Callback is a closure accepting response and error parameters.

1
2
3
4
5
6
7
8
9
    let call = TNGetTripsCall()
    call.execute(request: request) { (response, error) in
        if let response = response {
            // Handle response
        }
        if let error = error {
            // Handle error
        }
    }

1
2
3
4
5
6
7
8
9
    TNGetTripsCall *call = [TNGetTripsCall new];
    [call executeWithRequest:request callback:^(TNGetTripsResponse * _Nullable response, TNDriveMotionException * _Nullable error) {
        if (response) {
            // Handle response
        }
        if (error) {
            // Handle error
        }
    }];

Get trip detail by trip id (since version 1.0.0)

Get Request Builder

1
    let builder = driveMotionAnalyticsClient.getTripDetailRequest()

1
    TNGetTripDetailRequestBuilder *builder = [driveMotionAnalyticsClient getTripDetailRequest];

Build Request

TNGetTripDetailRequest requires trip id, assetId and assetContext. This API only supports the query of the trip that has finished.

1
2
3
    let request = builder.tripId(#tripId#)
                         .asset(#assetId#, #assetContext#)
                         .build()

1
2
3
    [builder tripId:#tripId#];
    [builder asset:#assetId#: #assetContext#];
    TNGetTripDetailRequest *request = [builder build];

Create a call and execute it

Callback is a closure accepting response and error parameters.

1
2
3
4
5
6
7
8
9
    let call = TNGetTripDetailCall()
    call.execute(request: request) { (response, error) in
        if let response = response {
            // Handle response
        }
        if let error = error {
            // Handle error
        }
    }

1
2
3
4
5
6
7
8
9
    TNGetTripDetailCall *call = [TNGetTripDetailCall new];
    [call executeWithRequest:request callback:^(TNGetTripDetailResponse * _Nullable response, TNDriveMotionException * _Nullable error) {
        if (response) {
            // Handle response
        }
        if (error) {
            // Handle error
        }
    }];

Get live trip detail (since version 1.0.0)

Get Request Builder

1
    let builder = driveMotionAnalyticsClient.getLiveTripDetailRequest()

1
    TNGetLiveTripDetailRequestBuilder *builder = [driveMotionAnalyticsClient getLiveTripDetailRequest];

Build Request

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

1
    let request = builder.build()

1
    TNGetLiveTripDetailRequest *request = [builder build];

Create a call and execute it

Callback is a closure accepting response and error parameters.

1
2
3
4
5
6
7
8
9
    let call = TNGetLiveTripDetailCall()
    call.execute(request: request) { (response, error) in
        if let response = response {
            // Handle response
        }
        if let error = error {
            // Handle error
        }
    }

1
2
3
4
5
6
7
8
9
    TNGetLiveTripDetailCall *call = [TNGetLiveTripDetailCall new];
    [call executeWithRequest:request callback:^(TNGetLiveTripDetailResponse * _Nullable response, TNDriveMotionException * _Nullable error) {
        if (response) {
            // Handle response
        }
        if (error) {
            // Handle error
        }
    }];

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

Get Request Builder

1
    let builder = driveMotionAnalyticsClient.getConfigDescriptionsRequest()

1
    TNGetConfigDescriptionsRequestBuilder *builder = [driveMotionAnalyticsClient getConfigDescriptionsRequest];

Build Request

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

1
2
    let request = builder.type(#type#)
                         .build()

1
2
    [builder type:#type#];
    TNGetConfigDescriptionsRequest *request = [builder build];

Create a call and execute it

Callback is a closure accepting response and error parameters.

1
2
3
4
5
6
7
8
9
    let call = TNGetConfigDescriptionsCall()
    call.execute(request: request) { (response, error) in
        if let response = response {
            // Handle response
        }
        if let error = error {
            // Handle error
        }
    }

1
2
3
4
5
6
7
8
9
    TNGetConfigDescriptionsCall *call = [TNGetConfigDescriptionsCall new];
    [call executeWithRequest:request callback:^(TNGetConfigDescriptionsResponse * _Nullable response, TNDriveMotionException * _Nullable error) {
        if (response) {
            // Handle response
        }
        if (error) {
            // Handle error
        }
    }];

Get the latest trip detail (since version 1.1.0)

Get Request Builder

1
    let builder = driveMotionAnalyticsClient.getLatestTripDetailRequest()

1
    TNGetLatestTripDetailRequestBuilder *builder = [driveMotionAnalyticsClient getLatestTripDetailRequest];

Build Request

TNGetLatestTripDetailRequest require assetId and assetContext parameters. But this API only fetch the latest finished trip.

1
    let request = builder.asset(#assetId#, #assetContext#).build()

1
2
    [builder asset:#assetId#: #assetContext#];
    TNGetLatestTripDetailRequest *request = [builder build];

Create a call and execute it

Callback is a closure accepting response and error parameters.

1
2
3
4
5
6
7
8
9
    let call = TNGetLatestTripDetailCall()
    call.execute(request: request) { (response, error) in
        if let response = response {
            // Handle response
        }
        if let error = error {
            // Handle error
        }
    }

1
2
3
4
5
6
7
8
9
    TNGetLatestTripDetailCall *call = [TNGetLatestTripDetailCall new];
    [call executeWithRequest:request callback:^(TNGetLatestTripDetailResponse * _Nullable response, TNDriveMotionException * _Nullable error) {
        if (response) {
            // Handle response
        }
        if (error) {
            // Handle error
        }
    }];

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

Get Request Builder

1
    let builder = driveMotionAnalyticsClient.getCumulativeScoreRequest()

1
    TNGetCumulativeScoreRequestBuilder *builder = [driveMotionAnalyticsClient getCumulativeScoreRequest];

Build Request

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

1
2
3
    let request = builder.lastNumOfDays(#lastNumOfDays#)
                         .asset(#assetId#, #assetContext#)
                         .build()

1
2
3
    [builder lastNumOfDays:#lastNumOfDays#];
    [builder asset:#assetId#: #assetContext#];
    TNGetCumulativeScoreRequest *request = [builder build];

Create a call and execute it

Callback is a closure accepting response and error parameters.

1
2
3
4
5
6
7
8
9
    let call = TNGetCumulativeScoreCall()
    call.execute(request: request) { (response, error) in
        if let response = response {
            // Handle response
        }
        if let error = error {
            // Handle error
        }
    }

1
2
3
4
5
6
7
8
9
    TNGetCumulativeScoreCall *call = [TNGetCumulativeScoreCall new];
    [call executeWithRequest:request callback:^(TNGetCumulativeScoreResponse * _Nullable response, TNDriveMotionException * _Nullable error) {
        if (response) {
            // Handle response
        }
        if (error) {
            // Handle error
        }
    }];

Update trip transportation mode (since version 1.2.1)

Get Request Builder

1
    let builder = driveMotionAnalyticsClient.updateTripTransportationModeRequest()

1
    TNUpdateTripTransportationModeRequestBuilder *builder = [driveMotionAnalyticsClient updateTripTransportationModeRequest];

Build Request

TNUpdateTripTransportationModeRequest needs to set required tripId and transportationMode.

1
2
3
    let request = builder.tripId(#lastNumOfDays#)
                         .(#transportationMode#)
                         .build()

1
2
3
    [builder tripId:#tripId#];
    [builder transportationMode:#transportationMode#];
    TNUpdateTripTransportationModeRequest *request = [builder build];

Create a call and execute it

Callback is a closure accepting response and error parameters.

1
2
3
4
5
6
7
8
9
    let call = TNUpdateTripTransportationModeCall()
    call.execute(request: request) { (response, error) in
        if let response = response {
            // Handle response
        }
        if let error = error {
            // Handle error
        }
    }

1
2
3
4
5
6
7
8
9
    TNUpdateTripTransportationModeCall *call = [TNUpdateTripTransportationModeCall new];
    [call executeWithRequest:request callback:^(TNUpdateTripTransportationModeResponse * _Nullable response, TNDriveMotionException * _Nullable error) {
        if (response) {
            // Handle response
        }
        if (error) {
            // Handle error
        }
    }];

Get Streaks (since version 1.2.1)

Get Request Builder

1
    let builder = driveMotionAnalyticsClient.getStreaksRequest()

1
    TNGetStreaksRequestBuilder *builder = [driveMotionAnalyticsClient getStreaksRequest];

Build Request

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

1
2
    let request = builder.asset(#assetId#, #assetContext#)
                         .build()

1
2
    [builder asset:#assetId#: #assetContext#];
    TNGetStreaksRequest *request = [builder build];

Create a call and execute it

Callback is a closure accepting response and error parameters.

1
2
3
4
5
6
7
8
9
    let call = TNGetStreaksCall()
    call.execute(request: request) { (response, error) in
        if let response = response {
            // Handle response
        }
        if let error = error {
            // Handle error
        }
    }

1
2
3
4
5
6
7
8
9
    TNGetStreaksCall *call = [TNGetStreaksCall new];
    [call executeWithRequest:request callback:^(TNGetStreaksResponse * _Nullable response, TNDriveMotionException * _Nullable error) {
        if (response) {
            // Handle response
        }
        if (error) {
            // Handle error
        }
    }];

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

Get Request Builder

1
    let builder = driveMotionAnalyticsClient.aggregatedSafetyScoreRequest()

1
    TNAggregatedSafetyScoreRequestBuilder *builder = [driveMotionAnalyticsClient aggregatedSafetyScoreRequest];

Build Request

TNAggregatedSafetyScoreRequest needs to set some parameters. The start date and the end date are required to define the time range for query. TNSafetyIntervalType is optional, and currently supports three modes: calendar week, and daily. It can further provide unit aggregation capabilities within the time range.TNSafetyIntervalFilter is optional, and currently supports tree modes: all, eventOnly, scoreOnly.

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
    let request = builder.startDate(#startDate#)
                         .endDate(#endDate#)
                         .intervalType(#IntervalType#)
                         .intervalFilter(#IntervalFilter#)
                         .asset(#assetId#, #assetContext#)
                         .scoreCreatedTime(#Date#)
                         .timeZoneId(#timeZoneId#)
                         .scoreVersion(#scoreVersion#)
                         .build()

1
2
3
4
5
6
7
8
9
    [builder startDate:#startDate#];
    [builder endDate:#endDate#];
    [builder intervalType:#IntervalType#];
    [builder intervalFilter:#IntervalFilter#];
    [builder asset:#assetId#: #assetContext#];
    [builder scoreCreatedTime:#Date#]
    [builder timeZoneId:#Date#]
    [builder scoreVersion:#scoreVersion#]
    TNAggregatedSafetyaScoreRequest *request = [builder 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.

Create a Call and execute it

Callback is a closure accepting response and error parameters.

1
2
3
4
5
6
7
8
9
    let call = TNAggregatedSafetyScoreCall()
    call.execute(request: request) { (response, error) in
        if let response = response {
            // Handle response
        }
        if let error = error {
            // Handle error
        }
    }

1
2
3
4
5
6
7
8
9
    TNAggregatedSafetyScoreCall *call = [TNAggregatedSafetyScoreCall new];
    [call executeWithRequest:request callback:^(TNAggregatedSafetyScoreResponse * _Nullable response, TNDriveMotionException * _Nullable error) {
        if (response) {
            // Handle response
        }
        if (error) {
            // Handle error
        }
    }];

Sync trips from cloud

Get Request Builder

1
    let builder = driveMotionAnalyticsClient.syncTripsRequest()

1
    TNSyncTripsRequestBuilder *builder = [driveMotionAnalyticsClient syncTripsRequest];

Build Request

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

1
    let request = builder.build()

1
    TNSyncTripsRequest *request = [builder build];

Create a call and execute it

Callback is a closure accepting response and error parameters.

1
2
3
4
5
6
7
8
9
    let call = TNSyncTripsCall()
    call.execute(request: request) { (response, error) in
        if let response = response {
            // Handle response
        }
        if let error = error {
            // Handle error
        }
    }

1
2
3
4
5
6
7
8
9
    TNSyncTripsCall *call = [TNSyncTripsCall new];
    [call executeWithRequest:request callback:^(TNSyncTripsResponse * _Nullable response, TNDriveMotionException * _Nullable error) {
        if (response) {
            // Handle response
        }
        if (error) {
            // Handle error
        }
    }];

Get simulated safety score (since version 2.0.0)

Get Request Builder

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

    // Cloud Mode
    let cloudModebuilder = driveMotionAnalyticsClient.withConnectionMode(mode:#connectionMode#).getSimulatedSafetyScoreRequest()

1
2
3
4
    TNGetSimulatedSafetyScoreRequestBuilder *builder = [driveMotionAnalyticsClient getSimulatedSafetyScoreRequest];

    // Cloud Mode
    TNGetSimulatedSafetyScoreRequestBuilder *cloudModeBuilder = [[driveMotionAnalyticsClient withConnectionModeWithMode:#connectionMode#] getSimulatedSafetyScoreRequest];

Build Request

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

1
2
3
4
    let request = builder.tripsInfo(#BasicTripsInfo#)
                         .tripsEventStatistics(#List<EventStatistics>#)
                         .state(#State#)
                         .scoreVersion(#ScoreVersion#) // optional

1
2
3
4
5
    [builder tripsInfo:#startDate#];
    [builder tripsEventStatistics:#endDate#];
    [builder state:#State#];
    [builder scoreVersion:#ScoreVersion#]; // optional
    TNGetSimulatedSafetyScoreRequest *request = [builder build];

Create a Call and execute it

Callback is a closure accepting response and error parameters.

1
2
3
4
5
6
7
8
9
    let call = TNGetSimulatedSafetyScoreCall()
    call.execute(request: request) { (response, error) in
        if let response = response {
            // Handle response
        }
        if let error = error {
            // Handle error
        }
    }

1
2
3
4
5
6
7
8
9
    TNGetSimulatedSafetyScoreCall *call = [TNGetSimulatedSafetyScoreCall new];
    [call executeWithRequest:request callback:^(TNGetSimulatedSafetyScoreResponse * _Nullable response, TNDriveMotionException * _Nullable error) {
        if (response) {
            // Handle response
        }
        if (error) {
            // Handle error
        }
    }];

Get event percentile table (since version 2.4.0)

Get Request Builder

1
    let builder = driveMotionAnalyticsClient.getEventPercentileTableRequest()

1
    TNGetEventPercentileTableRequestBuilder *builder = [driveMotionAnalyticsClient getEventPercentileTableRequest];

Build Request

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

1
2
3
    let request = builder.eventType(#DMEventType#)
                         .state(#State#)
                         .scoreVersion(#ScoreVersion#) // optional

1
2
3
4
    [builder eventType:#DMEventType#];
    [builder state:#State#];
    [builder scoreVersion:#ScoreVersion#]; // optional
    TNGetEventPercentileTableRequest *request = [builder build];

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

1
2
    let request = builder.state(#State#)
                         .scoreVersion(#ScoreVersion#) // optional

1
2
3
    [builder state:#State#];
    [builder scoreVersion:#ScoreVersion#]; // optional
    TNGetEventPercentileTableRequest *request = [builder build];

Create a Call and execute it

Callback is a closure accepting response and error parameters.

1
2
3
4
5
6
7
8
9
    let call = TNGetEventPercentileTableCall()
    call.execute(request: request) { (response, error) in
        if let response = response {
            // Handle response
        }
        if let error = error {
            // Handle error
        }
    }

1
2
3
4
5
6
7
8
9
    TNGetEventPercentileTableCall *call = [TNGetEventPercentileTableCall new];
    [call executeWithRequest:request callback:^(TNGetEventPercentileTableResponse * _Nullable response, TNDriveMotionException * _Nullable error) {
        if (response) {
            // Handle response
        }
        if (error) {
            // Handle error
        }
    }];

Get Cumulative Safety Score (since 2.18.x)

TNGetCumulativeSafetyScoreRequestis to retrieve the cumulative safety score for a specified vehicle or user within a given date range.

Example Usage

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
let request = try? TNDriveMotionService.getDriveMotionAnalyticsClient()
            .withConnectionMode(mode: TNConnectionMode.default)
            .getCumulativeSafetyScoreRequest()
            .startDate(xxx)
            .endDate(xxx)
            .scoreBaseTime(#scoreBaseTime#)
            .asset(#assetId#, #assetContext#)
            .build()
TNGetCumulativeSafetyScoreCall().execute(request: request!) { response, error in
}

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: 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.)
  • scoreBaseTime (Date, Optional) the calculation of the CumulativeSafetyScore based on the start period of trip.
  • assetContext: Represents the 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)

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

Example Usage

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
let request = try? TNDriveMotionService.getDriveMotionAnalyticsClient()
            .withConnectionMode(mode: TNConnectionMode.default)
            .getContextualCoachingStatisticsRequest()
            .currentPeriod(#DateRange#)
            .previousPeriod(#DateRange#)
            .groupBy(#Set<ContextualCoachingGroupFactor>#)
            .rankBy(#Set<ContextualCoachingRankMetrics>#)
            .asset(#assetId#, #assetContext#)
            .timezone(#TimeZone#)
            .scoreVersion(#ScoreVersion#)
            .build()

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
TNDriveMotionAnalyticsClient *client = [TNDriveMotionService getDriveMotionAnalyticsClientWithError:nil];
GetContextualCoachingStatisticsRequestBuilder *builder = [client getContextualCoachingStatisticsRequest];

// Set required parameters
DateRange *currentPeriod = [[DateRange alloc] initWithStart:#startDate# end:#endDate#];
[builder currentPeriod:currentPeriod];

// Set optional parameters
[builder previousPeriod:#DateRange#];
[builder assetWithAssetId:#assetId# assetContext:#assetContext#];
[builder timezone:#timezone#];
[builder scoreVersion:#scoreVersion#];
[builder groupByWithNumbers:#Set<NSNumber *>#];
[builder rankByWithNumbers:#Set<NSNumber *>#];

NSError *error;
TNGetContextualCoachingStatisticsRequest *request = [builder buildAndReturnError:&error];

Parameters

  • currentPeriod (DateRange): The current period date range for which the statistics are calculated.
  • previousPeriod (DateRange): The previous period date range for comparison (optional).
  • groupBy (Set<ContextualCoachingGroupFactor>): Group factors for the statistics, nil for calculate all the factors.
  • rankBy (Set<ContextualCoachingRankMetrics>): Rank metrics for the statistics, nil for calculate all the metrics.
  • assetId: Represents the vehicle's ID (value can be "VIN" or "Channel client id" based on type of assetContext). (If nil, 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.

Create a Call and execute it

Callback is a closure accepting response and error parameters.

1
2
3
4
5
6
7
8
9
    let call = TNGetContextualCoachingStatisticsCall()
    call.execute(request: request) { (response, error) in
        if let response = response {
            // Handle response
        }
        if let error = error {
            // Handle error
        }
    }

1
2
3
4
5
6
7
8
9
    TNGetContextualCoachingStatisticsCall *call = [TNGetContextualCoachingStatisticsCall alloc];
    [call executeWithRequest:request callback:^(TNGetContextualCoachingStatisticsResponse * _Nullable response, TNDriveMotionException * _Nullable error) {
        if (response) {
            // Handle response
        }
        if (error) {
            // Handle error
        }
    }];

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.