search

openmobilityfoundation / mobility-data-specification

A data standard to enable right-of-way regulation and two-way communication between mobility companies and local governments.
https://www.openmobilityfoundation.org/about-mds/
Other
676 stars 232 forks source link

Getting vehicle event status in MDS 2.0 #862

Closed schnuerle closed 1 year ago

schnuerle commented 1 year ago

A question came up from an MDS user for 2.0 that I wanted to outline and get a clear answer on here.

"some [agencies] are consuming the MDS data using the endpoint provider /vehicles to determine the availability. I see that this approach doesn’t work anymore in version 2.0… There is no status indication and no location. What’s the preferred way to get this data?"

We have guidance on this here:

And this is meant to be like GBFS free bike status, but with more fields for regulators. The purpose is to know what is happening with all vehicles in the PROW for all reasons.

Here's how that looks in 1.2: https://github.com/openmobilityfoundation/mobility-data-specification/tree/main/provider#vehicles

In 2.0 here's how it looks with the Vehicle Status object https://github.com/openmobilityfoundation/mobility-data-specification/blob/release-2.0.0/data-types.md#vehicle-status

which is a subset of the Vehicles object: https://github.com/openmobilityfoundation/mobility-data-specification/blob/release-2.0.0/data-types.md#vehicles

And you can see these in action on the Provider page: https://github.com/openmobilityfoundation/mobility-data-specification/tree/release-2.0.0/provider#vehicles

The new object does not contain info about last known state of the vehicle, or battery percent. Is this on purpose, and if so where else should someone look for this data? Or is this by accident, and should last_vehicle_state and battery_pct also be included here?

cc @marie-x @avatarneil @jean-populus @jiffyclub @thekaveman

jiffyclub commented 1 year ago

I think the question could be stated as "how do I replicate the behavior of MDS 1.2 /vehicles in MDS 2.0"? I think it's an important question, it's a very big deal for us here at Populus too. Putting all the fields in one place:

MDS 1.2 /vehicles MDS 2.0 /vehicles MDS 2.0 /vehicles/status
provider_id provider_id provider_id
provider_name . .
device_id device_id device_id
vehicle_id vehicle_id .
vehicle_type vehicle_type .
propulsion_types propulsion_types .
last_event_time . .
last_vehicle_state . .
last_event_types . .
last_event_location . .
current_location . .
battery_pct . .
. data_provider_id data_provider_id
. vehicle_attributes .
. accessibility_options .
. battery_capacity .
. fuel_capacity .
. maximum_speed .
. . last_event
. . last_telemetry

The last_event field provides the vehicle's location (which I guess is presumed to be the vehicle's current location?), timestamp, state, event details, and battery percentage. So it seems like the MDS 2.0 /vehicles/status endpoint has most of what's needed to replicate the MDS 1.2 /vehicles endpoint, except for information on vehicle/propulsion type and the vehicle ID. We do use those field for our usage of of /vehicles so this split does make it so we'd need to combine info from the two endpoints to get the same result. Since the info in MDS 2.0 /vehicles doesn't change one should only need to look it up once per vehicle, but this still definitely complicates the job of getting a current, complete picture of the environment.

schnuerle commented 1 year ago

Thanks Matt I think you have it right! "MDS 2.0 /vehicles/status" is meant to get most recent info about the properties of a vehicle that change frequently. This is cross referenced with more permanent vehicle features in "MDS 2.0 /vehicles".

This reduces the payload size for /status which is an endpoint you may need to check frequently (vs /vehicles which may only need daily checks or individual vehicle lookups by id as needed).

For a snapshot of what's available in the PROW, using GBFS is the way to go. If you are an agency who needs to know more, then these 2 endpoints get you there.

To be clear and to show on your chart where some of the 1.2 fields are, take a look at this:

MDS 1.2 /vehicles MDS 2.0 /vehicles MDS 2.0 /vehicles/status
last_event_time . last_event -> timestamp
last_vehicle_state . last_event -> vehicle_state
last_event_types . last_event -> event_types
last_event_location . last_event -> location
current_location . last_telemetry -> location
battery_pct . last_telemetry -> battery_percent or fuel_percent

This discussion will be great to leverage for our upgrade guide and new docs. Thank you all!

edwinvandenbelt commented 1 year ago

thank you @jiffyclub for providing the mapping! It was exactly what I was looking for!