Trip

Handles Trip related requests with IMS web services.

Fetch by ID

Parameters:

• id: The unique ID of the `Trip`

• expansions: A `Set` of Expansions for the `Trip`. Defaults to an empty set.

The Expansion includes events, scores, geometry, and user.

To fetch a trip by ID, the following API can be used.

Concrete example

Swift

let tripService = TripService()
tripService.fetch(id: id,
                  expansions: expansions then: { result in
    guard !result.value.empty else {
        // error
        return
    }
    completionHandler(.success(result.value))
})

Kotlin

val service = TripService()
service.fetch(id,
              expansions) { result: Result<Content?>? ->
    if (result?.value == null || result.throwable != null) {
        // failure
    } else {
        // Success
        val content = result.value
        completionHandler(content)
    }
})

Fetch by user

Fetch a Trip collection with expanded detail.

Parameters:

• user: The user for which trips are being fetched. If nil, fetches the trips for the currently authenticated User. Defaults to nil.

• filters: A Set of Filters for the request. Defaults to an empty set..

• expansions: A Set of Expansions for the collection.

To fetch a trip by user, the following API can be used.

Concrete example

Swift

let tripService = TripService()
tripService.fetch(user: user, 
                  filters: [Filter],
                  expansions: expansions,
                  then: { result in
    guard !result.value.empty else {
        // error
        return
    }
    completionHandler(.success(result.value))
})

Kotlin

val service = TripService()
service.fetch(user,
                 filters,
                 expansions) { result: Result<Content?>? ->
    if (result?.value == null || result.throwable != null) {
        // failure
    } else {
        // Success
        val content = result.value
        completionHandler(content)
    }
})

Fetch all

Parameters:

• filters: A Set of Filters for the request. Defaults to an empty set..

• expansions: A Set of Expansions for the collection.

The filters include cursor(limit, offset), date(start, end), check here for paging through trips from the logbook.

To fetch all trips, the following API can be used.

Concrete example

Swift

let tripService = TripService()
tripService.fetchAll(filters: [Filter],
                     expansions: expansions then: { result in
    guard !result.value.empty else {
        // error
        return
    }
    completionHandler(.success(result.value))
})

Kotlin

val service = TripService()
service.fetchAll(filters,
                 expansions) { result: Result<Content?>? ->
    if (result?.value == null || result.throwable != null) {
        // failure
    } else {
        // Success
        val content = result.value
        completionHandler(content)
    }
})

Update trip

Parameters:

• trip: The Trip to update.

• transportMode: The TransportMode to apply to the Trip.

• purpose: The Purpose to apply to the Trip.

To update the trip, the following API can be used.

Concrete example

Swift

let service = TripService()
service.update(trip,
               transportMode: TransportMode,
               purpose: purpose { result in
    switch result {
    case .success(_):
        // update successful
    case .failure(_):
        // error
    }
})

Kotlin

val service = TripService()
service.updateTrip(trip,
                   transportationMode,
                   purpose) { result: Result<Content?>? ->
    if (result?.value == null || result.throwable != null) {
        // failure
    } else {
        // Success
        val content = result.value
        completionHandler(content)
    }
})

Fetch trips by vehicle

- Parameters:

• vehicleId: The id of the vehicle for which we want the list of Trip

• vehicleTripsLimit: The maximum number of trips

• shouldExpandScores: If true will provide the scores information inside the Trip object

To fetch trips by vehicle, the following API can be used.

Concrete example

Swift

let service = TripService()
service.fetchTripsByVehicle(vehicleId: vehicleId,
                            vehicleTripsLimit: vehicleTripsLimit,
                            shouldExpandScores: shouldExpandScores, then: { result in
    guard !result.value.isEmpty else {
        // error
        return
    }
    completionHandler(.success(result.value))
})

Kotlin

val service = TripService()
service.fetchTripsByVehicle(vehicleId,
                            vehicleTripsLimit,
                            shouldExpandScore) { result: Result<Content?>? ->
    if (result?.value == null || result.throwable != null) {
        // failure
    } else {
        // Success
        val content = result.value
        completionHandler(content)
    }
})

Filter

The Trip APIs support pagination through a cursor parameter, which allows efficient navigation through a user's trips. The cursor utilizes two key fields: limit and offset.

Cursor Parameters

• limit: Specifies the maximum number of trips to retrieve per request. If not provided, the default value is 50.

• offset: Defines the starting point (index) for fetching trips, relative to the most recent trip.

Usage Example

Assume a user has a total of 200 trips. The host application can retrieve trips in pages using the cursor parameters as follows:

1. Fetch the Most Recent Trips To retrieve the 50 most recent trips:

   cursor(limit: 50, offset: 0)

2. Fetch the Next Page of Trips To retrieve the next 50 trips:

   cursor(limit: 50, offset: 50)

3. Continue Paging Through Trips Subsequent requests can increment the offset by the limit value to fetch further pages:

   cursor(limit: 50, offset: 100) // Retrieves trips 101–150
   cursor(limit: 50, offset: 150) // Retrieves trips 151–200

Key Points to Note

• The limit value should be chosen based on the application's requirement for batch size, balancing data size and API call frequency.

• Pagination parameters enable efficient navigation through the logbook without overwhelming the API or client application with large data responses.