Mobility Data Specification: Delivery

Delivery refers to employees and contractors, autonomous, and remotely operated sidewalk robots, app delivery, packages, freight, goods, food, private hire vehicles, electric cargo bikes and trikes, mopeds and motorcycles, box trucks, bike and scooter couriers, cargo vans, semi-trucks and tractor-trailers, postal service, medicine, and other delivery services.

There can be one or multiple orders on different trips at the same time, connected via the journey identifier. The state machine tracks the trip states of the orders separately from the vehicle state.

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

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

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

Mode Attributes

Mode ID

The short name identifier for deliveries used across MDS is delivery-robots. To be delivery in the next breaking release.

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. Journeys may be point-to-point, multi-segment, or multi-segment overlapping. Note that multiple journeys can be tied together with shift_id or route_id in Journey Attributes.

---
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: delivery to a single location, then return
    dateFormat HH:mm
    axisFormat %H:%M

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

    Trip - delivery : b, 17:00, 20m
    Trip - return : b, 17:20, 20m

    End : vert, v1, 17:40, 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: four overlapping delivery trips in the same journey
    dateFormat HH:mm
    axisFormat %H:%M

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

    Journey : active, a, 17:00, 50m
    Trip - delivery : b, 17:00, 10m
    Stop 1 : vert, v1, 17:10, 2m
    Trip - roaming : b, 17:10, 10m
    Stop 2 : vert, v1, 17:20, 2m
    Trip - delivery : b, 17:20, 15m
    Trip - delivery : b, 17:20, 20m
    Trip - delivery : b, 17:20, 25m
    Stop 3 : vert, v1, 17:35, 2m
    Stop 4 : vert, v1, 17:40, 2m
    Stop 5 : vert, v1, 17:45, 2m
    Trip - return : b, 17:45, 5m

    Journey End : vert, v1, 17:50, 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 3: delivery trips (w/ multiple orders) and journeys in 2 routes and 1 driver shift
    dateFormat HH:mm
    axisFormat %H:%M

    section Routes
    Shift Start : vert, v1, 17:00, 2m
    Shift : active, crit, a, 17:00, 90m
    Route 1: done, a, 17:00, 70m
    Route 2: done, a, 18:10, 20m

    section Journey 1
    Journey : active, a, 17:00, 50m
    Trip - delivery : b, 17:00, 10m
    Trip - delivery : b, 17:10, 10m
    Trip - delivery : b, 17:20, 20m
    Order 1: crit, done, c, 17:25, 5m
    Order 2: crit, done, c, 17:30, 5m
    Order 3: crit, done, c, 17:30, 10m
    Trip - return : b, 17:40, 10m

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

    section Journey 3
    Journey : active, a, 18:10, 20m
    Trip - delivery : b, 18:10, 12m
    Trip - return : 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:

• shift_id (UUID, Optional): unique identifier for a driver or operator's working shift, tied across multiple journeys and therefore trips.
• route_id (UUID, Optional): unique identifier for a planned delivery or passenger route, tied across multiple journeys and therefore trips.

Shifts and routes are made up of journeys, and journeys are made up of trips, so these can be connected in various ways as needed.

Top

Trip ID Requirements

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.

Trip Type

The trip_type field is used to describe the trip itself.

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

• delivery (default): making a delivery
• return: returning to home location or pickup point
• advertising: displaying advertising and not making a delivery
• mapping: mapping the environment and not making a delivery
• roaming: moving in right of way but not in another trip_type
• testing: vehicle is making a test trip

Top

Trip Attributes

The trip_attributes object may have the following key value pairs:

• driver_type (enum, required): type of driver operating the device: human, semi_autonomous, autonomous, remote
• driver_id (UUID, Optional): consistent unique identifier of the primary driver. 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. For autonomous or remote operations, could be based on software version, or an internal remote human driver id.
• permit_number (string, Optional) - The permit number of the individual or organization that is operating the vehicle
• has_payload (boolean, Optional): is there any payload for any delivery included in the device at trip start. 1 = loaded, 0 = empty
• parcel_count (integer, Optional) - count of individial parcels in the vehicle during this trip
• range (integer, Optional): estimated range in meters based on energy levels in device at trip start
• order (Array, Optional): Array of one or more orders with details for this trip:
  • order_id (string, Optional): identifier for this order, which could be used to cross reference in external system
  • app_name (string, Optional): name of the app used to reserve the trip which could be provider's app or 3rd party app
  • requested_time (Timestamp, Optional): when the customer requested the order
  • order_acceptance_time (Timestamp, Optional): when the driver has accepted the order, either in person or virtually
  • order_pickup_time (Timestamp, Optional): when the driver has physicaly picked up the order
  • unload_time (Timestamp, Optional): when the order was unloaded from the vehicle to finish delivery
  • delivery_time (Timestamp, Optional): when the order was delivered (e.g. customer received their order, package was left, etc).
  • pickup_location_name (string, Optional): name of the location where the order originated from
  • pickup_address (string, Optional): street address where the order originated from
  • origin_type (string, Optional): the name of the origin type for this delivery, e.g. ghost kitchen, individual restaurant, retail store, private delivery-courier, etc.
  • dropoff_address (string, Optional): street address where the trip ended
  • payload_type (string, Optional): the primary type or cargo or payload for this delivery, e.g. prepared food, parcel, medical, alcohol, grocery, etc. Could affect fees.
  • parcel_count (integer, Optional) - count of parcels in this order
  • identification_required (boolean, Optional): does the cargo require providing customer identification before trip start or upon delivery?
  • destination_type (string, Optional): the name of the destination type for this delivery, e.g. restaurant, residential, commerical, etc.

Top

Fare Attributes

The fare_attributes object may have the following key value pairs:

• fare_order (Array, Optional): Array of one or more orders with details for this trip:
  • payment_type (enumerated, Optional): account_number, cash, credit_card, mobile_app, no payment, phone, voucher, test
  • price (currency, Optional): Total price of the order
  • tip (currency, Optional) - amount of tip paid by customer
  • taxes (currency, Optional) - amount of taxes paid for the trip
  • fees (currency, Optional): any additional fees (positive) or incentives/discounts (negative) for this trip

Top

Vehicle Properties

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

Vehicle Attributes

The vehicle_attributes object may have the following key value pairs:

• year (integer, Optional)
• make (string, Optional)
• model (string, Optional)
• color (string, Optional)
• inspection_date (date YYYY-MM-DD, Optional): the date of the last inspection of the vehicle
• software_version (string, Optional): the version of the software being used on this trip
• equipped_cameras (integer, Optional): number of cameras equipped on device
• equipped_lighting (integer, Optional): number of lights used to illuminate the environment on the device
• wheel_count (integer, Optional): number of wheels on the device
• width (integer, Optional): width in meters of the device
• length (integer, Optional): length in meters of the device
• height (integer, Optional): height in meters of the device (minus flexible elements like flags)
• weight (integer, Optional): weight in kilograms rounded up of the device not including cargo
• top_speed (integer, Optional): theoretical top speed in meters per second of the device
• storage_capacity (integer, Optional): cubic centimeters of cargo space available not including any cargo

Top

Accessibility Attributes

The accessibility_attributes enum represents the accessibility attributes available on a given vehicle, or the accessibility attributes utilized for a given trip.

accessibility_attributes		Description
audio_cue	Optional	is the device equipped with audio cues upon delivery
visual_cue	Optional	is the device equipped with visual cues upon delivery
remote_open	Optional	can the device door be remotely opened to retrieve cargo upon delivery

Top

State Machine

Vehicle States

Valid delivery vehicle states are

• removed
• available
• non_operational
• reserved
• on_trip
• stopped
• non_contactable
• missing
• elsewhere

See Vehicle States for descriptions.

Top

Event Types

Valid delivery vehicle event types are

• comms_lost
• comms_restored
• compliance_pick_up
• decommissioned
• not_located
• located
• maintenance
• maintenance_pick_up
• maintenance_end
• driver_cancellation
• order_drop_off
• order_pick_up
• customer_cancellation
• provider_cancellation
• recommission
• reservation_start
• reservation_stop
• service_end
• service_start
• trip_end
• trip_enter_jurisdiction
• trip_leave_jurisdiction
• trip_resume
• trip_start
• trip_pause

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 gone out of comms while available for-use
available	non_operational	service_end	The vehicle has gone out of service (is unavailable for-hire)
available	reserved	reservation_start	The vehicle was reserved by a customer

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 gone 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
missing	available	located	The vehicle has been located while available for-hire
missing	elsewhere	located	The vehicle has been located while outside of jurisdictional boundaries
missing	non_operational	located	The vehicle has been located while not operating commercially
missing	on_trip	located	The vehicle has been located while on a trip
missing	removed	located	The vehicle has been located while removed
missing	reserved	located	The vehicle has been located while reserved by a customer
missing	stopped	located	The vehicle has been located while stopped

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	missing	not_located	The vehicle has gone missing after a period of lost comms
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 customer
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 gone 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 gone out of comms while not operating commercially
non_operational	non_operational	maintenance	The vehicle has maintenance performed on site
non_operational	non_operational	maintenance_end	Maintenance is complete
non_operational	removed	maintenance_pick_up	The vehicle has entered the depot for maintenance
non_operational	removed	decommissioned	The vehicle has been removed from the Provider's fleet

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 to pick up the order
on_trip	stopped	order_drop_off	The vehicle is at the customer's place
on_trip	stopped	order_pick_up	The vehicle has come to pick up the order from the origin point
on_trip	stopped	trip_pause	The vehicle has paused 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 has left the depot
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	customer_cancellation	The customer has canceled the reservation
reserved	available	driver_cancellation	The driver 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 has gone out of comms while being reserved by a customer
reserved	stopped	reservation_stop	The vehicle has stopped to pickup reservation

From vehicle_state	To vehicle_state	event_type	Description
stopped	available	customer_cancellation	The customer has canceled the trip while the vehicle is waiting
stopped	available	driver_cancellation	The driver has canceled the trip while waiting
stopped	available	provider_cancellation	The provider has canceled the trip while the vehicle is waiting
stopped	available	trip_end	The trip has been successfully completed
stopped	non_contactable	comms_lost	The vehicle has gone out of comms while stopped
stopped	on_trip	trip_resume	Resume a trip that was previously paused (e.g. picking up an order)
stopped	on_trip	trip_start	Start a trip

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.

Delivery State Notes

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 = for the one vehicle, all on-going trips which are 'delivery' or undefined trips (we do not take into account 'roaming', 'return' or 'advertising' trips)
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’
else:
if t=[]:
    v = ‘available’

trip_state mappings should be the same as in the table above.

Top

---

Modes Overview

---

MDS Home