Scoring

Handles ScoringAggregate and ScoringAverage related requests with IMS web services.

Scoring

You can get the average and maximum aggregate scores for previous trips taken by using the ScoringAggregateService. Functions have been added to query the scores over various different time periods. The time periods available are:

• today

• the last 7 days / last week

• the last 30 days / last month

• the last 90 days

• the last 365 days

• the last N days

• custom date range

The definition of a day is based on the user's current timezone.

For the following, the example timezone should be considered to be UTC-0400 (i.e Toronto). If a request for today's data is made at on the 2nd day of the month, at 23:00 (11PM) UTC-0400, the result should be based on that specific day, even though the current date according to the UTC would be the 3rd day of the month. (11:00PM UTC-0400 corresponds to 03:00AM the next day on UTC-0000 time).

Some other examples: User's time: 2020-01-01 - 00:01AM UTC-0400 (04:01AM UTC-0000) Results: 2020-01-01

User's time: 2020-01-01 - 12:01PM UTC-0400 (04:01PM UTC-0000) Results: 2020-01-01

User's time: 2020-01-01 - 10:01PM UTC-0400 (2020-01-02 02:01AM UTC-0000) Results: 2020-01-01

Scoring Aggregate

An aggregate of scoring averages and sub scoring (braking, cornering, acceleration and speed).

Any valid user on the DriveSync system (identified via the Identity) should be able to know scoring aggregate.

Required information

*Identity: In order to fetch scoring data, the application must have a valid user (represented by the Identity). That user must be active.

Pre-made date ranges

There are some Pre-made requests for easy access to some commonly used date ranges, as they are commonly used for other scoring components.

The current list includes:

• Today

• Last 7 days

• Last 30 days

• Last 90 days

• Last 365 days

Today

Concrete example

To fetch the ScoringAggregate for the user for the today, one can use following snippet

Swift

let service = ScoringService(identity: identity)
service.today(then: { result in
    guard !result.value.isEmpty else {
        // failure
        return
    }
    completionHandler(.success(result.value))
})

Kotlin

val service = ScoringService(identity)
service.fetchTodaysDailyScores() { result: Result<Content?>? ->
    if (result?.value == null || result.throwable != null) {
        // failure
    } else {
        // Success
        val content = result.value
        completionHandler(content)
    }
})

Last 7 days

Concrete example

Fetch the ScoringAggregate for the user for the last 7 days, one can use following snippet

Swift

let service = ScoringService(identity: identity)
service.last7Days(then: { result in
    guard !result.value.isEmpty else {
        // failure
        return
    }
    completionHandler(.success(result.value))
})

Kotlin

val service = ScoringService(identity)
service.fetchLast7DaysDailyScores() { result: Result<Content?>? ->
        if (result?.value == null || result.throwable != null) {
            // failure
        } else {
            // Success
            val content = result.value
            completionHandler(content)
        }
})

Other values

In order to get last 30, 90, and 365 days simply replace number "7" with the desired value respectively.

Custom date range

Fetching data for the scoring aggregate requires a start and end date (range).

The date is assumed to be based on the user's current timezone. As an example, if the current user's timezone is set to UTC-5:00, the long 1603416046000 corresponds to 2020-10-22 (even though it corresponds to 2020-10-23 1:20AM UTC).

Concrete example

To fetch the ScoringAggregate for the user over a period of time with a start and end date(range), one can use following snippet

Swift

let service = ScoringService(identity: identity)
service.dateRange(from: Date(), to: Date(), then: { result in
    guard !result.value.isEmpty else {
        // failure
        return
    }
    completionHandler(.success(result.value))
})

Kotlin

val service = ScoringService(identity)
service.fetchDaily(from, to) { result: Result<Content?>? ->
    if (result?.value == null || result.throwable != null) {
        // failure
    } else {
        // Success
        val content = result.value
        completionHandler(content)
    }
})

Vehicle

Fetching data for the scoring aggregate requires a start and end date (range).

Required information

*vehicle ID: In order to fetch scoring data for a vehicle, the application must have a valid vehicle associated with the identity.

Concrete example

To fetch the ScoringAggregate for a vehicle of the user over a period of time with a start and end date(range), one can use following snippet

Swift

service.fetchAggregateScoresByVehicle(vehicleId: vehicleId, from: Date(), to: Date(), then: { result in
    guard !result.value.isEmpty else {
        // failure
        return
    }
    completionHandler(.success(result.value))
})

Kotlin

val service = ScoringService(identity)
service.fetchAggregateScoresByVehicle(vehicleID, from, to) {
     result: Result<Content?>? ->
        if (result?.value == null || result.throwable != null) {
            // failure
        } else {
            // Success
            val content = result.value
            completionHandler(content)
        }
})

To fetch the ScoringAggregate for a vehicle of the user for the past N days, the following can be used

Swift

service.fetchLastNDaysAggregateScoresByVehicle(vehicleId: vehicleId, days: days, then: { result in
    guard !result.value.isEmpty else {
        // failure
        return
    }
    completionHandler(.success(result.value))
})

Kotlin

val service = ScoringService(identity)
service.fetchLastNDaysAggregateScoresByVehicle(vehicleID, days) {
     result: Result<Content?>? ->
        if (result?.value == null || result.throwable != null) {
            // failure
        } else {
            // Success
            val content = result.value
            completionHandler(content)
        }
})

Failures

ScoringService provides a [Throwable] in the results sent to the [ResultCallback].

The [Result] provided can be differentiated by checking the type of results, which is always [Result.Success] or [Result.Failure].

Alternatively, the [ResultCallback] can test for the presence of the throwable.

scoringService.fetchTodaysScores(result -> {
   ScoringAggregate aggregate = result.getValue();
   if (aggregate != null) {
       setScoreTextValue("Daily: ", result.getValue());
   } else {
       NetworkException exception = (NetworkException) result.getThrowable();
       if (exception.getReason() == NetworkException.Reason.SERVER_NOT_FOUND) {
           showError("Server not found");
       }
   }
});

Scoring average

In all the above API's "Daily" can replaced by "Average" to get the corresponding response.

Concrete example

For example to fetch the ScoringAverage for the user for the last 7 days, one can use following snippet

Swift

let service = ScoringService(identity: identity)
service.custom(from: fromDate, to: toDate, then: { result in
    guard !result.value.isEmpty else {
        // error
        return
    }
    completionHandler(.success(result.value))
}

Kotlin

val service = ScoringService(identity)
service.fetchLast7DaysAverageScores() { result: Result<Content?>? ->
        if (result?.value == null || result.throwable != null) {
            // failure
        } else {
            // Success
            val content = result.value
            completionHandler(content)
        }
})

Note: In iOS (Swift) the method fetchLastNDaysAverageScores, has vehicle ID as optional. Please see vehicle__

Weekly average

To receive week by week score data, call fetchWeek api to recieve the desired data. The number passed as argument is a UInt representing the number of weeks you want the data. For example, to retreive current week you'll pass 0 and for last week you need to pass 1.

Concrete example

For example to fetch the ScoringAverage for the user for the desired week, one can use following snippet

Swift

let service = ScoringService(identity: identity)
service.fetchWeek(weekNumber: weekNumber, then: { result in
    guard !result.value.isEmpty else {
        // error
        return
    }
    completionHandler(.success(result.value))
}

Kotlin

val service = ScoringService(identity)
service.fetchWeek(weekNumber) { result: Result<Content?>? ->
        if (result?.value == null || result.throwable != null) {
            // failure
        } else {
            // Success
            val content = result.value
            completionHandler(content)
        }
})

Vehicle

Fetching data for the scoring average requires a start and end date (range).

Required information

*vehicle ID: In order to fetch scoring data for a vehicle, the application must have a valid vehicle associated with the identity.

Concrete example

To fetch the ScoringAverage for a vehicle of the user over a period of time with a start and end date(range), one can use following snippet

Swift

let service = ScoringService(identity: identity)
service.fetchAverageScoresByVehicle(vehicleId: vehicleId, from: fromDate, to: toDate, then: { result in
    guard !result.value.isEmpty else {
        // error
        return
    }
    completionHandler(.success(result.value))
}

Kotlin

val service = ScoringService(identity)
service.fetchAverageScoresByVehicle(vehicleID, from, to) {
     result: Result<Content?>? ->
        if (result?.value == null || result.throwable != null) {
            // failure
        } else {
            // Success
            val content = result.value
            completionHandler(content)
        }
})

To fetch the ScoringAverage for a vehicle of the user for the past N days, the following can be used.

Note: In iOS (Swift) the method fetchLastNDaysAverageScores, has vehicle ID as optional. If it is NOT passed, the api returns user's last N days average scores.

Swift

let service = ScoringService(identity: identity)
service.fetchLastNDaysAverageScores(vehicleId: vehicleId, days: days, then: { result in
    guard !result.value.isEmpty else {
        // error
        return
    }
    completionHandler(.success(result.value))
}

Kotlin

val service = ScoringService(identity)
service.fetchLastNDaysAverageScoresByVehicle(vehicleID, days) {
     result: Result<Content?>? ->
        if (result?.value == null || result.throwable != null) {
            // failure
        } else {
            // Success
            val content = result.value
            completionHandler(content)
        }
})