On-demand trips

This document describes the on-demand trips service in Fleet Engine. It assumes you have read What is Fleet Engine? and are aware of the specific Fleet Engine service capability that you need.

As you read this documentation, keep in mind the following:

You assign trips to vehicles as a way to model the real-world association between the trip and the driver who completes that trip. Read Introduction to vehicles to better understand how vehicles work in Fleet Engine.
This document also describes some vehicle elements that apply only to on-demand trips.
Fleet Engine for on-demand trips uses two resources: a Trip and a Vehicle. Fleet Engine provides both a gRPC service and REST interfaces:
- TripService: gRPC and REST
- VehicleService: gRPC and REST
- For simplicity, this manual uses gRPC examples.

What is an on-demand trip?

In Fleet Engine, a trip represents an on-demand journey that can accomplish a variety of transportation goals. For example:

People: Transport one or more persons from pickup to drop-off locations.
Food and goods: Pick up one or more food orders from a given business location and drop off these orders to one or more recipients at their locations.

Trip elements

The following illustration shows the basic elements of a trip: the assigned vehicle ID, the trip status, and the trip waypoints. The waypoint types vary depending on the stage of the journey: pickup, intermediate, and drop-off. In any trip, an intermediate destination or waypoint is optional. In the image example, the vehicle has arrived at the pickup loc

Data model for trips

As your backend assigns trips to vehicles, it must also know about other trips scheduled for the vehicle. For that reason, the following diagrams illustrate the data model of the Trip resource alongside the diagram for its associated Vehicle resource. You can review both diagrams to explore the relationships between the two resources, keeping in mind the following:

Trips are assigned to a vehicle by ID.
The trip-vehicle association is many-to-one. That is, a given trip might be the only trip scheduled for the vehicle, or it might be one of many trips for the vehicle.
Trip objects contain two lists of trip waypoints, one for the trip itself and one for the assigned vehicle. This is explained in more detail in this document.
The on-demand vehicle also has a list of trip waypoints, described more fully in this document.

Trip data model

Vehicle data model

Trip types

When your service creates a trip, it can set the tripType field as either of the following: EXCLUSIVE or SHARED.

Exclusive trips

An exclusive trip is one whose journey does not overlap with other trips, and one which the vehicle completes either before or after other trips on its schedule. This means that when your system assigns exclusive trips, it can only assign them to a vehicle to be completed in sequence, not concurrently. To illustrate, you might create exclusive trips with any the following characteristics:

A trip with a single pickup and a single drop-off for a vehicle with no other trips on its schedule.
A trip with a pickup, intermediate waypoint, and a drop-off for a vehicle with no other trip on its schedule.
A trip with a pickup and drop-off added to the end of an already-scheduled trip for the vehicle. In these cases, each trip is exclusive to the other, but the trips are ordered in a back-to-back fashion. Additionally, such trips can include intermediate destinations if required.

Shared trips

A shared trip is one whose journey can overlap with other trip bookings. For these trip types, your system can assign them to happen concurrently with interleaving destinations. For example, the drop-off for one trip might occur after the pickup for another trip. Additionally, shared trips may not use intermediate waypoints.

Typically, you would use a shared trip for one of the shared pooling scenarios illustrated in the Trip scenarios section.

Trip waypoints

For Google Maps, a waypoint is a place along a route, usually defined by a latitude/longitude coordinate. For on-demand trips, a waypoint is represented by a TripWaypoint object, which contains additional information such as the following:

The trip ID
The WaypointType, either pickup, intermediate, or drop-off
Path and distance information between the previous trip waypoint and the current one
Traffic conditions along the path to the trip waypoint
Travel time and ETA to trip waypoint

See the references:

TripWaypoint: gRPC or REST
WaypointType: gRPC or REST

Trip waypoint types

A trip waypoint is defined in relation to the general lifecycle of a vehicle journey:

Pickup waypoint—Used for the origin or beginning of a trip, such as when a driver picks up a food order for subsequent delivery, or when a driver picks up a person for later drop-off.
Intermediate waypoint—An intermediate destination that can be used for a variety of purposes, such as when a driver drops off one passenger of the same booking party, but the trip itself is not complete, since more passengers remain. This waypoint is optional and may be used only for exclusive trips.
Drop-off waypoint—Used for the final location of the journey, such as when the remaining passenger exits the vehicle.

Trip waypoint lists

A Trip entity includes two lists of waypoints, each of which are a repeated field of type TripWaypoint. One list describes those fields necessary for the trip itself, and the other to describe all waypoints remaining for the vehicle associated with the trip. This allows you have a full picture of all elements of the journey: the trip and the entire vehicle journey.

Remaining waypoints for the vehicle—A field called vehicle_waypoints. It contains all remaining waypoints for all trips assigned to the vehicle.
Remaining waypoints for the trip—A field called remaining_waypoints. It contains waypoints that the vehicle must travel in sequence before the trip's final drop-off point. See the scenarios in Trip scenarios.
- For a single-destination trip assigned to a vehicle with no other trips on its schedule, this would include only a pickup and a drop-off location, assuming the vehicle had not left the pickup waypoint.
- For any other trip scenario where the vehicle is also scheduled for other trips, the remaining waypoints for any trip on its itinerary would include all waypoints from other trips that the vehicle must traverse before reaching the drop-off waypoint for that trip. For example, in a back-to-back trip where the vehicle is en-route to drop-off for trip A, the remaining waypoints for trip B would include the drop-off waypoint for trip A. Fleet Engine computes this information using the vehicle_waypoints field.

See the reference for the Trip entity: gRPC or REST.

Trip scenarios

The following diagrams illustrate a variety of supported trip scenarios. In these scenarios, only the shared pooling trip is of type SHARED; all others are EXCLUSIVE. The diagrams also show the trip status and the remaining waypoints for the vehicle performing the trip, concepts described later in this guide.

Single-destination trip

A single-destination trip is an EXCLUSIVE trip with one pickup and one drop-off location. For example, a driver picks up a passenger from one location and transports them to another; or a driver retrieves a food delivery order from a restaurant and drops it off to a customer.

Multi-destination trips

A multi-destination trip is an EXCLUSIVE trip that contains one or more intermediate destinations between the pickup and the drop-off locations. For example, three rideshare customers book a ride together from one person's phone, but each have separate destinations.

Back-to-back trips

Back-to-back trips are EXCLUSIVE trips that contain a series of independent trips that occur one right after the other. Each trip in the chain can be single or multi-destination. In this scenario, a driver commits to picking up another customer before completing the current trip.

These trips can only be assigned to vehicles that allow back-to-back scheduling. See the Vehicle REST, gRPC reference.

Shared pooling trips

A shared pooling trip differs from the other trip types. Firstly, it must be a SHARED trip, not an EXCLUSIVE one. Here, the vehicle executes the trips concurrently rather than in sequence as with exclusive trips. While a shared pooling trip shares its journey with other trips, it does not share pickup and drop-off location information between trips. Instead, each trip is an exclusive booking such that the end user who booked one trip cannot see the pickup or destination information for any other trip but their own. For example:

An airport shuttle service picks up various customers at their residence and deposits them at different airport terminals along the route. Person 2 might use your consumer app to track progress of the trip, but their app only shows their part of the journey and not where person 1 was picked up, nor where person 1 is going to be dropped off, even though parts of their journeys overlap.
A food delivery driver picks up three food orders from the same restaurant to deliver to different customer residences. Using your consumer app, Person 3 can view where and when their food was picked up and see the driver route, but not see food drop-off locations for persons 1 and 2.

Trip status and its lifecycle

This section describes trip status and its impact on the vehicle and various scenarios you encounter as you assign and manage on-demand trips.

A trip generally progresses through various states, from creation to completion. Broadly speaking, a trip can be active or inactive, depending on its status. Trip status impacts a variety of use case scenarios with Fleet Engine, as well as the ability for you to identify vehicle progress through the journey. The rest of this document discusses those scenarios.

The following table lists trip status by active and inactive kinds.

Active trip statuses	Inactive trip statuses
`NEW` `UNKNOWN_TRIP_STATUS` `ENROUTE_TO_PICKUP` `ARRIVED_AT_PICKUP` `ENROUTE_TO_INTERMEDIATE_DESTINATION` `ARRIVED_AT_INTERMEDIATE_DESTINATION` `ENROUTE_TO_DROPOFF`	`COMPLETE` `CANCELED`

Trip status and remaining vehicle waypoints

When assigning additional trips to a vehicle already executing a trip, you should understand the relationship between the remaining waypoints for the vehicle and how trip status impacts those remaining waypoints.

For example, you might assign a new rideshare request to a vehicle that supports exclusive trips only and is in the midst of completing a trip. In this case you would model the trip as a back-to-back trip. When assigning such a trip, your system should ensure that the waypoints for the new trip occur after the waypoints for the ongoing trip.

During the vehicle journey, Fleet Engine removes a previous trip waypoint from the vehicle's list of remaining waypoints only when the vehicle reports that it is en route to the next destination or completed. That is, any of the following:

ENROUTE_TO_INTERMEDIATE_DESTINATION
ENROUTE_TO_DROPOFF
COMPLETED

When trip status changes to COMPLETED, Fleet Engine removes the final waypoint of the trip from the vehicle's remaining waypoint list.

By contrast, status changes indicating arrival at a waypoint typically have no effect on the list of remaining waypoints for the vehicle:

ARRIVED_AT_PICKUP
ARRIVED_AT_INTERMEDIATE_DESTINATION
ARRIVED_AT_DROPOFF

To illustrate with an on-demand ride example: suppose the driver picks up a customer from their residence, transports them to a venue where they wait for the customer to complete a task, and then transports the customer back to their residence. When initially created, the trip has three waypoints: PICKUP, INTERMEDIATE, and DROPOFF. The following table illustrates the results of a query for remaining waypoints at various states of the journey:

Trip status	Remaining waypoints
`ARRIVED_AT_PICKUP`	`PICKUP` `INTERMEDIATE` `DROPOFF`
`ENROUTE_TO_INTERMEDIATE_DESTINATION`	~~`PICKUP`~~ `INTERMEDIATE` `DROPOFF`
`ARRIVED_AT_INTERMEDIATE_DESTINATION`	~~`PICKUP`~~ `INTERMEDIATE` `DROPOFF`
`ENROUTE_TO_DROPOFF`	~~`PICKUP`~~ ~~`INTERMEDIATE`~~ `DROPOFF`
`ARRIVED_AT_DROPOFF`	~~`PICKUP`~~ ~~`INTERMEDIATE`~~ `DROPOFF`
`COMPLETE`	~~`PICKUP`~~ ~~`INTERMEDIATE`~~ ~~`DROPOFF`~~

Status requirements for reassigned or cancelled trips

Before you can do any of the following, you must set trip status to either NEW or CANCELED.

When changing vehicle assignments for a trip. For example, if a driver declines a vehicle assignment for a trip and it needs to be reassigned to a different vehicle.
When clearing a vehicle assignment for a trip. For example, if a driver cancels a trip en route and you want to clear the vehicle assignment, the status must be either NEW or CANCELED.

Search results based on trip status

When you use the SearchTrips service for a specific vehicle, it returns the list of active trips in the SearchTripsResponse. Active trips also appear in the Vehicle entity's active_trips field. See the SearchTripsResponse reference for details: gRPC or REST.

Therefore, all trips with an active status appear in the active_trips field, but completed or cancelled trips don't.