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 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
        }
    }];

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.

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
2
3
4
5
    let builder = driveMotionAnalyticsClient.postContextualCoachingRequest(
        startTime: startTime,
        endTime: endTime,
        timeZoneId: timeZoneId
    )

1
    TNPostContextualCoachingRequestBuilder *builder = [client postContextualCoachingRequestWithStartTime:startTime endTime:endTime timeZoneId:timeZoneId];

Build Request

TNPostContextualCoachingRequest 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
6
    let request = try builder
        .asset(assetId: #assetId#, assetContext: #assetContext#)
        .scoreVersion(#scoreVersion#)
        .groupBy(#groupFactors#)
        .rankBy(#rankMetrics#)
        .build()

1
2
3
4
5
6
7
    [builder assetWithAssetId:#assetId# assetContext:#assetContext#];
    [builder scoreVersion:#scoreVersion#];
    [builder groupByWithNumbers:#Set<NSNumber *>#];
    [builder rankByWithNumbers:#Set<NSNumber *>#];

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

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

Create a Call and execute it

Callback is a closure accepting response and error parameters.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
    let call = TNPostContextualCoachingCall()
    call.execute(request: request) { (response, error) in
        if let response = response, response.status == .success {
            let coachingId = response.result?.coachingId
            // Use coachingId for GetContextualCoachingRequest
        }
        if let error = error {
            // Handle error
        }
    }

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
    TNPostContextualCoachingCall *call = [[TNPostContextualCoachingCall alloc] init];
    [call executeWithRequest:request callback:^(TNPostContextualCoachingResponse * _Nullable response, TNDriveMotionException * _Nullable error) {
        if (response && response.status == TNResponseStatusSuccess) {
            NSString *coachingId = response.result.coachingId;
            // Use coachingId for GetContextualCoachingRequest
        }
        if (error) {
            // 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
    let builder = driveMotionAnalyticsClient.getContextualCoachingRequest(coachingId: coachingId)

1
    TNGetContextualCoachingRequestBuilder *builder = [client getContextualCoachingRequestWithCoachingId:coachingId];

Build Request

TNGetContextualCoachingRequest requires the coaching ID returned from the post request.

1
    let request = try builder.build()

1
2
    NSError *error;
    TNGetContextualCoachingRequest *request = [builder buildAndReturnError:&error];

Parameters

  • coachingId: The coaching ID returned from TNPostContextualCoachingResponse.

Create a Call and execute it

Callback is a closure accepting response and error parameters.

 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
    let call = TNGetContextualCoachingCall()
    call.execute(request: request) { (response, error) in
        if let response = response, response.status == .success {
            let result = response.result
            switch result?.coachingStatus {
            case .completed:
                if result?.statusReason == nil {
                    // Process statistics
                } else {
                    // Handle task error
                }
            case .pending, .processing:
                // Retry after delay
                break
            case .failed:
                // Handle cloud error
                break
            default:
                break
            }
        }
        if let error = error {
            // 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
27
    TNGetContextualCoachingCall *call = [[TNGetContextualCoachingCall alloc] init];
    [call executeWithRequest:request callback:^(TNGetContextualCoachingResponse * _Nullable response, TNDriveMotionException * _Nullable error) {
        if (response && response.status == TNResponseStatusSuccess) {
            ContextualCoachingResult *result = response.result;
            switch (result.coachingStatus) {
                case TNProcessStatusCompleted:
                    if (result.statusReason == nil) {
                        // Process statistics
                    } else {
                        // Handle task error
                    }
                    break;
                case TNProcessStatusPending:
                case TNProcessStatusProcessing:
                    // Retry after delay
                    break;
                case TNProcessStatusFailed:
                    // Handle cloud error
                    break;
                default:
                    break;
            }
        }
        if (error) {
            // 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
    let builder = driveMotionAnalyticsClient.getTripsByIdsRequest(tripIds: tripIds)

1
    TNGetTripsByIdsRequestBuilder *builder = [client getTripsByIdsRequestWithTripIds:tripIds];

Build Request

TNGetTripsByIdsRequest 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
5
    let request = try builder
        .asset(assetId: #assetId#, assetContext: #assetContext#)
        .excludeTripEvents(#excludeTripEvents#)
        .excludeTripRoute(#excludeTripRoute#)
        .build()

1
2
3
4
5
6
    [builder assetWithAssetId:#assetId# assetContext:#assetContext#];
    [builder excludeTripEvents:#excludeTripEvents#];
    [builder excludeTripRoute:#excludeTripRoute#];

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

Parameters

  • tripIds: Array 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).

Create a Call and execute it

Callback is a closure accepting response and error parameters.

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
    TNGetTripsByIdsCall *call = [[TNGetTripsByIdsCall alloc] init];
    [call executeWithRequest:request callback:^(TNGetTripsResponse * _Nullable response, TNDriveMotionException * _Nullable error) {
        if (response) {
            NSArray<BasicTrip *> *trips = response.trips;
            // Process trips
        }
        if (error) {
            // 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 asset() method.

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.