Passenger Services refers to taxis, transportation network companies (TNCs), commercial transport apps (CTAs), and private hire vehicles (PHVs). Passenger Services typically have a driver, one or more passengers, and multiple passengers may be on different trips. The state machine tracks the trip states of the passengers separately from the vehicle state.
See the modes overview for how the mode specific information below applies across MDS.
Taxis typically require explicit tracking of maintenance while TNCs typically do not. Public agency regulations, legal authority, differ based on local, state, and federal laws and jurisdictions between taxis, TNCs, CTAs, PHV, etc.
The short name identifier for Passenger Services used across MDS is passenger-services.
See more available trip and fare attributes for any mode used in the trips object.
The journey_id field shall have a consistent value in overlapping trips, e.g. "pooled" or "shared" rides with different start and/or end locations. Journeys may be point-to-point, multi-segment, or multi-segment overlapping.
- Example 1: one private trip with reservation, then return to depot
- Example 2: three shared trips, some overlapping
The journey_attributes object may have the following key value pairs:
shift_id(UUID, optional): unique identifier for an entire driver's work shift, tied across multiple journeys and therefore trips.
Events require a valid trip_id in events where event_types contains reservation_start, reservation_stop, trip_start, trip_pause, trip_resume, trip_end,trip_cancel, customer_cancellation, provider_cancellation, or driver_cancellation.
Additionally, trip_id is required if event_types contains a trip_enter_jurisdiction or trip_leave_jurisdiction event pertaining to a trip.
The trip_type field must have one of the following enumerated values:
private: a private trip made by one paying customer with one or more guestsshared: a shared or pooled trip with more than one paying customerreservation: en route to pickup a customer who has made a reservation, with no passengers in the vehicleempty: vehicle movement with no passengers (outside of othertrip_typevalues) that may need to be reported, e.g. for deadheading
The trip_attributes object may have the following key value pairs:
hail_type(enumerated, required):street_hail,phone_dispatch,phone,text,appapp_name(text, optional): name of the app used to reserve the trip which could be provider's app or 3rd party apppassenger_count(integer, required): unique count of passengers transported during trip durationrequested_time(Timestamp, required): when the passenger requested the triprequested_trip_start_location(GPS, Conditionally Required): Location where the customer requested the trip to start (required if this is within jurisdictional boundaries)quoted_trip_start_time(Timestamp, Required): Time the trip was estimated or scheduled to start, that was provided to the passengerdispatch_time(Timestamp, Conditionally Required): Time the vehicle was dispatched to the customer (required if trip was dispatched)trip_wait_time(milliseconds, optional): part of the passenger trip where the vehicle was moving slow or stopped (e.g. <12mph), which is a different fare rate in some jurisdictionstrip_fare_time(milliseconds, optional): part of the passenger trip where the vehicle was moving more quickly (e.g. >12mph), which is a different fare rate in some jurisdictionspickup_address(text, optional): street address where the trip originated fromdropoff_address(text, optional): street address where the trip endedpermit_license_number(string, optional) - The permit license number of the organization that dispatched the vehicledriver_id(string, optional): Universal identifier of a specific driver, static across operators, like a driver's license number. Could also be used as a lookup in an agency's internal driver system.wheelchair_transported(boolean, optional) - was a wheelchair transported as part of this trip?cancellation_reason(String, Conditionally Required): The reason why a driver cancelled a reservation. (required if a driver cancelled a trip, and adriver_cancellationevent_type was part of the trip)
The fare_attributes object may have the following key value pairs:
payment_type(enumerated, required):account_number,cash,credit_card,mobile_app,no_payment,paratransit,phone,voucher,testfare_type(enumerated, required):meter_fare,upfront_pricing,flat_rate. Indicator of which rate was charged.meter_fare_amount(currency, conditionally required): ifupfront_pricingis used as afare_typeinclude what the metered fare would have been ifmeter_farewould have been used. Allows cost comparison in evaluation of programs and pilots.tolls(currency, optional) - Sum of any and all tolls charged for the trip, such as bridge tollsbase_rate(currency, optional) - Minimum fare to be charged as soon as the trip starts.exit_fee(currency, optional) - Fee to exit location, like an airportother_fees(currency, optional) - amount of any fees charged to the customer. Includes baggage fees, cleaning fee. Excludes other fees returned.tip(currency, optional) - amount of tip paid by customerextra_amount(currency, optional) - miscellaneous extra amounts charged to customer not covered by other fields.taxes(currency, optional) - amount of taxes paid for the ridesurcharge(currency, optional) - any surcharge pricingcommission(currency, optional) - any extra commission for the ridedriver_trip_pay(currency, optional) - The payment the driver received for the triprate_code_id(enumerated, optional) - one ofmeter_fare,shared,out_of_town,disabled,upfront_pricing,promo_rate
See more available vehicle attributes and accessibility attributes for any mode used in the vehicles object.
The vehicle_attributes object may have the following key value pairs:
year(integer, optional)make(string, optional)model(string, optional)color(string, optional)vin(string, optional) - the Vehicle Identification Number of the vehicleplacard_number(string, optional) - the registered placard number of the vehiclelicense_plate(string, optional) - the registered vehicle license/number/registration plate identifier on the vehicleinspection_date(date YYYY-MM-DD, optional) - the date of the last inspection of the vehicle
This accessibility_attributes enum represents the accessibility attributes available on a given vehicle, or the accessibility attributes utilized for a given trip.
accessibility_attributes |
Description |
|---|---|
wheelchair_accessible |
This vehicle is wheelchair accessible |
Valid passenger services vehicle states are
removedavailablenon_operationalreservedon_tripstoppednon_contactableelsewhere
See Vehicle States for descriptions.
Valid passenger services vehicle event types are
comms_lostcomms_restoreddriver_cancellationmaintenancemaintenance_pick_upmaintenance_endpassenger_cancellationprovider_cancellationreservation_stopreservation_startservice_endservice_starttrip_endtrip_enter_jurisdictiontrip_leave_jurisdictiontrip_resumetrip_starttrip_stop
This list is somewhat shorter than the micromobility event list, as passenger service vehicles are controlled by a driver or potentially an AI. They are not picked up or dropped off for rebalancing or compliance, for example, and they do not go out of service because of a low battery.
See vehicle Event Types for descriptions.
This is the list of vehicle_state and event_type pairings that constitute the valid transitions of the vehicle state machine.
From vehicle_state |
To vehicle_state |
trip_state |
event_type |
Description |
|---|---|---|---|---|
available |
elsewhere |
N/A | trip_leave_jurisdiction |
The vehicle has left jurisdictional boundaries while available for-hire |
available |
non_contactable |
N/A | comms_lost |
The vehicle has went out of comms while available for-use |
available |
non_operational |
N/A | service_end |
The vehicle has went out of service (is unavailable for-hire) |
available |
reserved |
reserved |
reservation_start |
The vehicle was reserved by a passenger |
elsewhere |
available |
N/A | trip_enter_jurisdiction |
The vehicle has entered jurisdictional boundaries while available for-hire |
elsewhere |
non_contactable |
N/A | comms_lost |
The vehicle has went out of comms while outside of jurisdictional boundaries |
elsewhere |
non_operational |
N/A | trip_enter_jurisdiction |
The vehicle has entered jurisdictional boundaries while not operating commercially |
elsewhere |
on_trip |
on_trip |
trip_enter_jurisdiction |
The vehicle has entered jurisdictional boundaries while on a trip |
elsewhere |
reserved |
N/A | trip_enter_jurisdiction |
The vehicle has entered jurisdictional boundaries while reserved by a customer |
non_contactable |
available |
N/A | comms_restored |
The vehicle has come back into comms while available for-hire |
non_contactable |
elsewhere |
N/A | comms_restored |
The vehicle has come back into comms while outside of jurisdictional boundaries |
non_contactable |
non_operational |
N/A | comms_restored |
The vehicle has come back into comms while not operating commercially |
non_contactable |
on_trip |
on_trip |
comms_restored |
The vehicle has come back into comms while on a trip |
non_contactable |
removed |
N/A | comms_restored |
The vehicle has come back into comms while removed |
non_contactable |
reserved |
reserved |
comms_restored |
The vehicle has come back into comms while reserved by a passenger |
non_contactable |
stopped |
stopped |
comms_restored |
The vehicle has come back into comms while stopped |
non_operational |
available |
N/A | service_start |
The vehicle has went into service (is available for-hire) |
non_operational |
elsewhere |
N/A | trip_leave_jurisdiction |
The vehicle has left jurisdictional boundaries while not operating commercially |
non_operational |
non_contactable |
N/A | comms_lost |
The vehicle has went out of comms while not operating commercially |
non_operational |
non_operational |
N/A | maintenance |
The vehicle has maintenance performed on site |
non_operational |
non_operational |
N/A | maintenance_end |
Maintenance is complete |
non_operational |
removed |
N/A | maintenance_pick_up |
The vehicle has entered the depot for maintenance |
non_operational |
removed |
N/A | decommissioned |
The vehicle has been removed from the Provider's fleet |
on_trip |
elsewhere |
N/A | trip_leave_jurisdiction |
The vehicle has left jurisdictional boundaries while on a trip |
on_trip |
non_contactable |
N/A | comms_lost |
The vehicle has gone out of comms while on a trip |
on_trip |
stopped |
stopped |
trip_stop |
The vehicle has stopped while on a trip |
removed |
non_contactable |
N/A | comms_lost |
The vehicle has gone out of comms while removed |
removed |
non_operational |
N/A | maintenance_end |
The vehicle has left the depot |
removed |
non_operational |
N/A | recommissioned |
The vehicle has been re-added to the Provider's fleet after being previously decommissioned |
reserved |
available |
N/A | driver_cancellation |
The driver has canceled the reservation |
reserved |
available |
N/A | passenger_cancellation |
The passenger has canceled the reservation |
reserved |
available |
N/A | provider_cancellation |
The provider has canceled the reservation |
reserved |
elsewhere |
N/A | trip_leave_jurisdiction |
The vehicle has left the jurisdiction while in a reservation |
reserved |
non_contactable |
N/A | comms_lost |
The vehicle went out of comms while being reserved by a passenger |
reserved |
stopped |
stopped |
reservation_stop |
The vehicle has stopped to pick up the passenger |
stopped |
available |
N/A | driver_cancellation |
The driver has canceled the trip while either waiting for the passenger, or dropping them off |
stopped |
available |
N/A | passenger_cancellation |
The passenger has canceled the trip while the vehicle is waiting to pick them up, or they are being dropped off |
stopped |
available |
N/A | provider_cancellation |
The provider has canceled the trip while the vehicle is waiting for a passenger, or dropping them off |
stopped |
available |
N/A | trip_end |
The trip has been successfully completed |
stopped |
non_contactable |
N/A | comms_lost |
The vehicle has went out of comms while stopped |
stopped |
on_trip |
on_trip |
trip_resume |
Resume a trip that was previously stopped (e.g. picking up a friend to go to the airport with) |
stopped |
on_trip |
on_trip |
trip_start |
Start a trip |
This State Machine Diagram shows how vehicle_state and event_type relate to each other and how vehicles can transition between states. See Google Slides for the source file.
When there is only one trip ongoing, trip_state == vehicle_state
In cases where there are multiple trips ongoing, please follow the trip state model pseudocode for determining what the vehicle state should be:
t = all on-going trips for vehicle
v = vehicle state
if t.any(state == ‘stopped’):
v = ‘stopped’
else:
if t.any(state == ‘on_trip’):
v = ‘on_trip’
else:
if t.any(state == ‘reserved’):
v = ‘reserved’
trip_state mappings should be the same as in the table above.