The documentation in this section shows how to create and work with trips using the Google Maps Mobility on-demand trips service. It assumes familiarity with the following:
- Fleet Engine: You should be familiar with Fleet Engine implementation details, request mechanisms, and security. For that, see What is the Fleet Engine service? and the security topics in Set up Fleet Engine.
- Vehicles basics for on-demand services. See Introduction to vehicles.
- Trip basics for on-demand services. See On-demand trips.
The TripService
that you'll use is available for gRPC and REST.
For simplicity sake, field references follow the gRPC convention.
In Fleet Engine for on-demand services, a trip is a type of journey that models
the fulfillment of a food delivery or ride request from your consumers. A trip
has a status that you report to Fleet Engine as the journey evolves, such as
NEW
, ENROUTE_TO_PICKUP
, and more. The trip status corresponds to geo-located
waypoints assigned to the vehicle, and Fleet Engine modifies these vehicle
waypoints with each trip update you make. See On demand trips in Fleet
Engine essentials for more about trips and their relationship to vehicles.
Life of a trip
In order to track each trip in Fleet Engine, you must first create a Trip
entity. See either gRPC or REST for reference.
The following table describes an example end-to-end flow of a trip created in your system and its lifecycle stages in Fleet Engine. It assumes you have set up Fleet Engine and have a vehicle to assign to the trip, with location updates enabled in the driver app. See Driver SDK: On-demand trips.
1 | Receive booking request. | Before a Fleet Engine trip begins, your booking system first receives a
request for a ride or delivery from a consumer through your app or other
booking system. Your system then creates the trip entity using
CreateTrip with required fields, such as the pickup location.
It can also set other fields at this point, such passengers and
dropoff location, or wait until it assigns a vehicle. See
Create a single-destination trip. |
2 | Assign vehicle. | You can either assign vehicles to trips directly within your system and report the assignment to Fleet Engine, or you can use the Search Vehicle service to search for vehicles, filtering by both trip and vehicle attributes to find the best vehicle to complete the journey. Any online vehicle within your search radius makes their proximity known through location updates provided by the Driver SDK. Once |
3 | Update trip. | Once the driver accepts the trip and begins navigating to the
pickup location, your system updates the trip status from NEW
to ENROUTE_TO_PICKUP . You continue to poll the vehicle
location throughout the journey, either through a direct connection from
the app to your backend, or by polling Fleet Engine, which receives an
ongoing stream of vehicle location updates from the Driver SDK. Your
system then reports each journey milestone to Fleet Engine, which updates
the vehicle's waypoint list accordingly.
|
4 | Share journey with consumer. | Fleet Engine makes trip details and vehicle location available to the Consumer SDK, which uses a listener to receive trip updates and display them in the consumer app. Fleet Engine automatically updates ETA, remaining distance, routes, and remaining vehicle waypoints. See Share journeys for on-demand trips for more information. |
5 | Complete trip. | Once the vehicle reaches the destination waypoint of the trip and your
driver indicates a successful trip, your system sets the
TripStatus to COMPLETE in Fleet Engine. Keep in
mind that, like vehicles, trip entities remain active within Fleet Engine
for 7 days regardless of status, at which point they are removed. |
Trip sequence flow
The following diagram shows a more detailed view of this flow.