Mobility Data Specification: Fleet

Fleet refers to shared customer, employees and contractors, autonomous, and remotely operated shared point-to-point, station-based, or free-floating multi-passenger or cargo vehicles like consumer car share, sanitation vehicles (garbage, recycling), city fleets, vehicle rentals, street sweepers, snow plows, utility services, construction, emergency response (police, fire, ambulance), tree maintenance, inspection and permitting vehicles, mobile health clinics, and heavy maintenance vehicles.

See the modes overview for how the mode specific information below applies across MDS.

Note: Formerly called "Car Share". Any references in the specification code or links to only "Car Share" will be updated to the broader "Fleet" scope in the next MDS 3.0 release.

Mode Attributes
- Mode ID
Trip Properties
Vehicle Properties
- Vehicle Attributes
- Accessibility Attributes
State Machine

Mode Attributes

Mode ID

The short name identifier for Fleet used across MDS is car-share. In a future release this will be updated to fleet.

Top

Trip Properties

See more available trip and fare attributes for any mode used in the trips object.

Journey ID

The journey_id field shall have a consistent value in overlapping trips for a single reservation period, e.g. trips taken by a customer between ignition states over the duration of their reservation. A reservation is the duration the customer has continuous exclusive access to the vehicle whether parked or in motion. Journeys may be point-to-point or multi-segment.

---
config:
        theme: 'base'
        themeVariables:
          'activeTaskBkgColor': '#155654'
          'activeTaskBorderColor': '#2AF1BE'
          'critBorderColor': '#2AF1BE'
          'doneTaskBkgColor': '#299c90'
          'doneTaskBorderColor': '#373737'
          'taskBkgColor': '#2AF1BE'
          'taskBorderColor': '#373737'
          'taskTextColor': '#373737'
          'taskTextDarkColor': 'white'
          'taskTextLightColor': '#373737'
          'vertLineColor': '#155654'
          'sectionBkgColor': '#ddd'
          'altSectionBkgColor': '#aaa'
          'sectionBkgColor2': '#777'
---
gantt
    title Example 1: car share single journey, company delivers vehicle to customer, one trip point-to-point by customer
    dateFormat HH:mm
    axisFormat %H:%M

    section Journey
    Journey Start : vert, v1, 17:00, 2m

    Journey : active, a, 17:00, 55m

    Trip - reservation : b, 17:00, 10m
    Trip - private : b, 17:10, 45m

    Journey End : vert, v1, 17:55, 5m

---
config:
        theme: 'base'
        themeVariables:
          'activeTaskBkgColor': '#155654'
          'activeTaskBorderColor': '#2AF1BE'
          'critBorderColor': '#2AF1BE'
          'doneTaskBkgColor': '#299c90'
          'doneTaskBorderColor': '#373737'
          'taskBkgColor': '#2AF1BE'
          'taskBorderColor': '#373737'
          'taskTextColor': '#373737'
          'taskTextDarkColor': 'white'
          'taskTextLightColor': '#373737'
          'vertLineColor': '#155654'
          'sectionBkgColor': '#ddd'
          'altSectionBkgColor': '#aaa'
          'sectionBkgColor2': '#777'
---
gantt
    title Example 2: customer car share reservation for 4 days with a trip daily for errands, gas, entertainment, etc
    dateFormat MM-DD

    section Reservation
    Reservation Start : vert, v1, 03-20, 2m

    Reservation : done, a, 03-20, 4d

    Trip - private : b, 03-20, 1d
    Trip - private : b, 03-21, 1d
    Trip - private : b, 03-22, 1d
    Trip - private : b, 03-23, 1d
    
    Reservation End : vert, v1, 03-24, 12h

---
config:
        theme: 'base'
        themeVariables:
          'activeTaskBkgColor': '#155654'
          'activeTaskBorderColor': '#2AF1BE'
          'critBorderColor': '#2AF1BE'
          'doneTaskBkgColor': '#299c90'
          'doneTaskBorderColor': '#373737'
          'taskBkgColor': '#2AF1BE'
          'taskBorderColor': '#373737'
          'taskTextColor': '#373737'
          'taskTextDarkColor': 'white'
          'taskTextLightColor': '#373737'
          'vertLineColor': '#155654'
          'sectionBkgColor': '#ddd'
          'altSectionBkgColor': '#aaa'
          'sectionBkgColor2': '#777'
---
gantt
    title Example 3: a shift of a city snow plow driver, showing journeys from a central location, and trips inside the journeys
    dateFormat HH:mm
    axisFormat %H:%M

    section Shift
    Shift Start : vert, v1, 17:00, 2m
    Shift : done, a, 17:00, 90m

    section Journey 1
    Journey 1 : active, a, 17:00, 50m
    Trip - private : b, 17:00, 10m
    Trip - private : b, 17:10, 10m
    Trip - private : b, 17:20, 20m
    Trip - empty : b, 17:40, 10m

    section Journey 2
    Journey 2 : active, a, 17:50, 20m
    Trip - private : b, 17:50, 10m
    Trip - empty : b, 18:00, 10m

    section Journey 3
    Journey 3 : active, a, 18:10, 20m
    Trip - private : b, 18:10, 12m
    Trip - empty : b, 18:22, 8m

    Shift End : vert, v1, 18:30, 10m

Top

Journey Attributes

The journey_attributes object may have the following key value pairs:

reservation_id (UUID, Optional): unique identifier for an entire vehicle reservation, tied across multiple journeys and therefore trips.
shift_id (UUID, Optional): unique identifier for a driver or operator's working shift, tied across multiple journeys and therefore trips.

Top

Trip ID Requirements

Events require a valid trip_id in events where event_types contains reservation_start, reservation_stop, trip_start, trip_resume, trip_stop,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.

Top

Trip Type

The trip_type field must have one of the following enumerated values:

private (default): a private trip made by one paying customer with one or more guests, or a driver using the vehicle
reservation: en route to pickup a customer who has made a reservation, or movement before starting an official task
mapping: primarily mapping the environment
empty: vehicle movement with no customer or work (outside of other trip_type values) that may need to be reported, e.g. for maintenance, returning, etc

Top

Trip Attributes

The trip_attributes object may have the following key value pairs:

reservation_type (enumerated, required): how was the vehicle reserved, one of phone_dispatch, phone, text, app
app_name (text, Optional): name of the app used to reserve the vehicle which could be provider's app or 3rd party app
permit_license_number (string, Optional) - The permit license number of the organization that dispatched the vehicle
driver_id (string, Optional): Universal identifier of a specific driver, static across operators, like a driver's license number, for company employees in reservation or empty trip types, not private trips. Could also be used as a lookup in an agency's internal driver system.

Top

Fare Attributes

The fare_attributes object may have the following key value pairs:

payment_type (enumerated, required): account_number, cash, credit_card, mobile_app, no payment, phone, voucher, test
fare_type (enumerated, required): meter_fare, upfront_pricing, flat_rate. Indicator of which rate was charged.
tolls (currency, Optional) - Sum of any and all tolls charged for the trip, such as bridge tolls
base_rate (currency, Optional) - Minimum fare to be charged as soon as the trip starts.
exit_fee (currency, Optional) - Fee to exit location, like an airport
other_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 customer
extra_amount (currency, Optional) - miscellaneous extra amounts charged to customer not covered by other fields.
taxes (currency, Optional) - amount of taxes paid for the ride
surcharge (currency, Optional) - any surcharge pricing

Top

Vehicle Properties

See more available vehicle attributes and accessibility options for any mode used in the vehicles object.

Vehicle Attributes

The vehicle_attributes object may have the following key value pairs:

year (integer, required)
make (string, required)
model (string, required)
color (string, required)
vin (string, required) - the Vehicle Identification Number of the vehicle
license_plate (string, required) - the registered external license plate number of the vehicle
inspection_date (date YYYY-MM-DD, Optional) - the date of the last inspection of the vehicle
snow_shovel (boolean, Optional) - shovel for removing snow or ice from around vehicle or vehicle path
snow_brush (boolean, Optional) - brushes for removing snow or ice from vehicle
bike_rack (boolean, Optional) - car roof or trunk mounted bike rack
park_access (boolean, Optional) - access pass to a national/regional/municipal park system
toll_transponder (boolean, Optional) - toll transponder for national/regional toll system
phone_charger (boolean, Optional) - a place to charge your phone
sunshade (boolean, Optional) - sunshade available (i.e. for windshield)
cargo_volume_capacity (integer, Optional) - Cargo volume available in the vehicle, expressed in liters. For cars, it corresponds to the space between the boot floor, including the storage under the hatch, to the rear shelf in the trunk.
cargo_load_capacity (integer, Optional) - The capacity of the vehicle cargo space (excluding passengers), expressed in kilograms
door_count (integer, Optional) - number of doors this vehicle type has
wheel_count (integer, Optional) - number of wheels this vehicle type has
air_conditioning (boolean, Optional) - vehicle has air conditioning
gear_switch (enum, Optional) - one of automatic (automatic and semi-automatic), manual (single or dual clutch, intelligent manual), variable (Continuously Variable Transmission (CVT))
convertible (boolean, Optional) - vehicle has a retractable roof
cruise_control (boolean, Optional) - vehicle has a cruise control system
navigation (boolean, Optional) - vehicle has a built-in navigation system
wheel_drive (string, Optional) - type of wheel drive of the vehicle (e.g., 4WD, AWD, front wheel drive, back wheel drive)
child_seat (boolean, Optional) - the vehicle is equipped with a children's seat
pets_allowed (boolean, Optional) - pets are allowed in the vehicle
rooftop_cargo_box (boolean, Optional) - the vehicle is equipped with a rooftop cargo box
roof_rails (boolean, Optional) - the vehicle is equipped with roof rails
ski_hatch (boolean, Optional) - the vehicle has a ski hatch in the rear seat row
winter_tires (boolean, Optional) - the vehicle is equipped with winter tires

Note many of these attributes come from fields in GBFS vehicle_types.

Top

Accessibility Attributes

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

Top

State Machine

Vehicle States

Valid fleet vehicle states are

removed
available
non_operational
reserved
on_trip
stopped
non_contactable
elsewhere

See Vehicle States for descriptions.

Top

Event Types

Valid fleet vehicle event types are

charging_start
charging_end
comms_lost
comms_restored
customer_cancellation
driver_cancellation
fueling_start
fueling_end
maintenance
maintenance_pick_up
maintenance_end
provider_cancellation
remote_start
remote_end
reservation_stop
reservation_start
service_end
service_start
trip_end
trip_enter_jurisdiction
trip_leave_jurisdiction
trip_resume
trip_start
trip_stop

See vehicle Event Types for descriptions.

Top

Vehicle States Events

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`	`event_type`	Description
`available`	`elsewhere`	`trip_leave_jurisdiction`	The vehicle has left jurisdictional boundaries while available for-hire
`available`	`non_contactable`	`comms_lost`	The vehicle has went out of comms while available for-use
`available`	`non_operational`	`service_end`	The vehicle has went out of service (is unavailable for-hire)
`available`	`reserved`	`reservation_start`	The vehicle was reserved by a passenger

From `vehicle_state`	To `vehicle_state`	`event_type`	Description
`elsewhere`	`available`	`trip_enter_jurisdiction`	The vehicle has entered jurisdictional boundaries while available for-hire
`elsewhere`	`non_contactable`	`comms_lost`	The vehicle has went out of comms while outside of jurisdictional boundaries
`elsewhere`	`non_operational`	`trip_enter_jurisdiction`	The vehicle has entered jurisdictional boundaries while not operating commercially
`elsewhere`	`on_trip`	`trip_enter_jurisdiction`	The vehicle has entered jurisdictional boundaries while on a trip
`elsewhere`	`reserved`	`trip_enter_jurisdiction`	The vehicle has entered jurisdictional boundaries while reserved by a customer

From `vehicle_state`	To `vehicle_state`	`event_type`	Description
`non_contactable`	`available`	`comms_restored`	The vehicle has come back into comms while available for-hire
`non_contactable`	`elsewhere`	`comms_restored`	The vehicle has come back into comms while outside of jurisdictional boundaries
`non_contactable`	`non_operational`	`comms_restored`	The vehicle has come back into comms while not operating commercially
`non_contactable`	`on_trip`	`comms_restored`	The vehicle has come back into comms while on a trip
`non_contactable`	`removed`	`comms_restored`	The vehicle has come back into comms while removed
`non_contactable`	`reserved`	`comms_restored`	The vehicle has come back into comms while reserved by a passenger
`non_contactable`	`stopped`	`comms_restored`	The vehicle has come back into comms while stopped

From `vehicle_state`	To `vehicle_state`	`event_type`	Description
`non_operational`	`available`	`service_start`	The vehicle has went into service (is available for-hire)
`non_operational`	`elsewhere`	`trip_leave_jurisdiction`	The vehicle has left jurisdictional boundaries while not operating commercially
`non_operational`	`non_contactable`	`comms_lost`	The vehicle has went out of comms while not operating commercially
`non_operational`	`removed`	`decommissioned`	The vehicle has been removed from the Provider's fleet
`non_operational`	`removed`	`maintenance_pick_up`	The vehicle has entered the depot for maintenance
`non_operational`	`removed`	`maintenance`	The vehicle is undergoing maintenance on site

From `vehicle_state`	To `vehicle_state`	`event_type`	Description
`on_trip`	`elsewhere`	`trip_leave_jurisdiction`	The vehicle has left jurisdictional boundaries while on a trip
`on_trip`	`non_contactable`	`comms_lost`	The vehicle has gone out of comms while on a trip
`on_trip`	`stopped`	`trip_stop`	The vehicle has stopped while on a trip

From `vehicle_state`	To `vehicle_state`	`event_type`	Description
`removed`	`non_contactable`	`comms_lost`	The vehicle has gone out of comms while removed
`removed`	`non_operational`	`maintenance_end`	The vehicle maintenance work has ended
`removed`	`non_operational`	`recommissioned`	The vehicle has been re-added to the Provider's fleet after being previously `decommissioned`

From `vehicle_state`	To `vehicle_state`	`event_type`	Description
`reserved`	`available`	`driver_cancellation`	The driver has canceled the reservation
`reserved`	`available`	`customer_cancellation`	The customer has canceled the reservation
`reserved`	`available`	`provider_cancellation`	The provider has canceled the reservation
`reserved`	`elsewhere`	`trip_leave_jurisdiction`	The vehicle has left the jurisdiction while in a reservation
`reserved`	`non_contactable`	`comms_lost`	The vehicle went out of comms while being reserved by a passenger
`reserved`	`stopped`	`reservation_stop`	The customer has activated the vehicle

From `vehicle_state`	To `vehicle_state`	`event_type`	Description
`stopped`	`available`	`driver_cancellation`	The driver has canceled the trip
`stopped`	`available`	`customer_cancellation`	The customer has canceled the trip
`stopped`	`available`	`provider_cancellation`	The provider has canceled the trip
`stopped`	`available`	`trip_end`	The trip has been successfully completed
`stopped`	`non_contactable`	`comms_lost`	The vehicle has went out of comms while stopped
`stopped`	`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`	`trip_start`	Start a trip
`stopped`	`stopped`	`charging_end`	End charging the device battery
`stopped`	`stopped`	`charging_start`	Start charging the device battery
`stopped`	`stopped`	`fueling_end`	End fueling the device with physical fuel
`stopped`	`stopped`	`fueling_start`	Start fueling the device with physical fuel
`stopped`	`stopped`	`remote_end`	Remotely stop the engine while vehicle is already stopped
`stopped`	`stopped`	`remote_start`	Remotely start the engine while vehicle is stopped, usually to charge battery or warm up

Top

State Machine Diagram

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.

Top

Modes Overview

MDS Home

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Mobility Data Specification: Fleet

Table of Contents

Mode Attributes

Mode ID

Trip Properties

Journey ID

Journey Attributes

Trip ID Requirements

Trip Type

Trip Attributes

Fare Attributes

Vehicle Properties

Vehicle Attributes

Accessibility Attributes

State Machine

Vehicle States

Event Types

Vehicle States Events

State Machine Diagram

Uh oh!

FilesExpand file tree

car-share.md

Latest commit

History

car-share.md

File metadata and controls

Mobility Data Specification: Fleet

Table of Contents

Mode Attributes

Mode ID

Trip Properties

Journey ID

Journey Attributes

Trip ID Requirements

Trip Type

Trip Attributes

Fare Attributes

Vehicle Properties

Vehicle Attributes

Accessibility Attributes

State Machine

Vehicle States

Event Types

Vehicle States Events

State Machine Diagram