Scoring
Handles ScoringAggregate and ScoringAverage related requests with IMS web services.
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
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.*Identity: In order to fetch scoring data, the application must have a valid user (represented by the Identity). That user must be active.
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
To fetch the
ScoringAggregate
for the user for the today, one can use following snippetSwift
Kotlin
let service = ScoringService(identity: identity)
service.today(then: { result in
guard !result.value.isEmpty else {
// failure
return
}
completionHandler(.success(result.value))
})
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)
}
})
Fetch the
ScoringAggregate
for the user for the last 7 days, one can use following snippetSwift
Kotlin
let service = ScoringService(identity: identity)
service.last7Days(then: { result in
guard !result.value.isEmpty else {
// failure
return
}
completionHandler(.success(result.value))
})
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)
}
})
In order to get last 30, 90, and 365 days simply replace number "7" with the desired value respectively.
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).
To fetch the
ScoringAggregate
for the user over a period of time with a start and end date(range), one can use following snippetSwift
Kotlin
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))
})
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)
}
})
Fetching data for the scoring aggregate requires a start and end date (range).
*vehicle ID: In order to fetch scoring data for a vehicle, the application must have a valid vehicle associated with the identity.
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 snippetSwift
Kotlin
service.fetchAggregateScoresByVehicle(vehicleId: vehicleId, from: Date(), to: Date(), then: { result in
guard !result.value.isEmpty else {
// failure
return
}
completionHandler(.success(result.value))
})
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 usedSwift
Kotlin
service.fetchLastNDaysAggregateScoresByVehicle(vehicleId: vehicleId, days: days, then: { result in
guard !result.value.isEmpty else {
// failure
return
}
completionHandler(.success(result.value))
})
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)
}
})
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");
}
}
});
In all the above API's "Daily" can replaced by "Average" to get the corresponding response.
For example to fetch the
ScoringAverage
for the user for the last 7 days, one can use following snippetSwift
Kotlin
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))
}
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
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.
For example to fetch the
ScoringAverage
for the user for the desired week, one can use following snippetSwift
Kotlin
let service = ScoringService(identity: identity)
service.fetchWeek(weekNumber: weekNumber, then: { result in
guard !result.value.isEmpty else {
// error
return
}
completionHandler(.success(result.value))
}
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)
}
})
Fetching data for the scoring average requires a start and end date (range).
*vehicle ID: In order to fetch scoring data for a vehicle, the application must have a valid vehicle associated with the identity.
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 snippetSwift
Kotlin
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))
}
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
Kotlin
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))
}
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)
}
})
Last modified 8mo ago