Add Docked Bikeshare Systems (and Stops History)

[cmdoptesc]

Explain pull request

With issues #374 , #428 , and #438 it seems there's an ever-increasing desire to bring docked-bikeshare information into MDS.

We propose minor additions to the existing /trips and /status_changes endpoints and also the addition of new /stations and /station_status_changes endpoints. The two new endpoints are undoubtedly modeled after GBFS; however they’re intended for historical queries, unlike GBFS's primary purpose of providing "real-time travel advice" to bikeshare riders.

To update trips to support docks (issue #428 ), we should add two new optional fields: station_start and station_end. If a vehicle starts and/or ends its trip at a station, the fields would be populated with the station ID(s).

For status changes (issue #438 ), there will be an optional event_station_id field, whose purpose is similar to the above. If a device has a status change that occurs at a station, then the field will be populated with the station ID.

For actual information on stations (issue #374 ), we’ve split this into two endpoints: /stations and /station_status_changes.

The reason for this separation is because the /stations endpoint guarantees that the user will get an inventory of all stations at predictable point in time. Since it’s costly and redundant to store the state of a station of every possible historical point in time, this endpoint would provide states on a daily cadence. To get the state at any other point in time, the user would use the /station_status_changes endpoint; which is a stream of events.

So with two endpoints, a consumer of the API can recreate the state of any station at any point in the past without needing to start from the very beginning.

Lastly, I want disclose that I may not have the availability to shepherd this proposal all the way to completion. If someone else in the MDS community would like to take the reins on this, I welcome your support.

Is this a breaking change

This PR adds optional fields to existing endpoints and proposes the addition of two new endpoints.

• No, not breaking

Impacted Spec

Which spec(s) will this pull request impact?

• provider

Issues for Discussion

Which spec(s) will this pull request impact?

• provider

Issues for Discussion

• We chose to use Vehicles[] and Docks[] instead of a field like num_bikes_available so that the station may support any type of vehicle without requiring any changes to the schema. GBFS currently has an issue with representing ebike counts, where some providers have started using their own unofficial field like num_ebikes_available. I'm well aware of the performance implications when parsing, but the approach of stringifying vehicle_types and propulsion_types as keys seems suboptimal as well. E.g.

{
  num_bike_human_available: 10,
  num_bike_electric_assist_available: 5,
  num_scooter_electric_available: 3
}

• Stations have vehicle_types and propulsion_types fields, which represent what that station supports, however it doesn’t list the specific combination (e.g. an ebike is a bike and electric_assist). To do so would require the creation of some third object that would combine vehicle_type and propulsion_type. This was purposely omitted to reduce complexity.

• The Vehicles object, given its inclusion of device_id and vehicle_id, will allow a user to recreate trips. This is a minor privacy concern, especially when compared to routes routes because because docked trips are "snapped" to stations, so the level of trip detail here is coarser.

• Do we want to try to align station change_type_reasons with the existing agency and provider event_type framework?

[avatarneil]

There are already open pull requests that begin to satisfy the desire for docked bikeshare systems in both MDS-Agency and MDS-Provider, see #427 and #430. We've been discussing #427 significantly in the bi-weekly Provider Working Group calls. There are still pending issues for addition of Stops to /trips and /status_changes, which I've been developing PRs for. I think it'd make sense to perhaps reduce the scope of this PR to focus on the updates requested by #438 or #428, and to utilize the Stops type that we've been discussing in the working groups for about a month now.

[avatarneil]

@cmdoptesc Follow-up to my above comment, I'd really love this to just become a PR for introducing a status_changes equivalent for Stops to resolve #438, as well as adding a GeoJSON Foreign Member stop_id to the Geographic Data field for vehicle status_changes.

[cmdoptesc]

Hi @avatarneil thanks for taking a look at this.

I was on the Provider Working Group call in January with my coworker @rgangopadhya and am aware of your stops proposals. I don't believe this PR and #427 are clashing because yours is focused on realtime information. Internally, @rgangopadhya and I had discussed making a recommendation for historical support in #427 (prior to it being split out into Provider and Agency), but decided that it didn't make sense to blow up the scope of that PR.

Because #427 is realtime and this PR is historical, I'd love to get alignment on naming and the actual set of fields to reduce the dissonance when requesting realtime vs historical data.

In addition, my understanding from the Provider Working Group call we attended was that there was some feedback on #427 that generalizing stations to stops (i.e. combining GTFS and GBFS) felt a bit too far ahead of the actual use-cases on the ground. This motivated us to focus this PR on fields related to "micromobility" stations.

I see a need for realtime stop/station data, and I see a need for historical stop/station data, and MDS would be benefited by both.

Lastly, with regards to adding stops to trips using GeoJSON Foreign Members (#438), I lean towards stop/station information being found at the top level of a trips or status_change object. This way it’d be easier for a consumer of the API to find all trips originating or ending at a station without needing to parse the route geometry.

[avatarneil]

Hey @cmdoptesc, thank you for the clarification! I think that we should absolutely try to align Stations and Stops.

It was my hope that we could extend status_changes to support the Stop type with only minor modifications. I recently reduced the scope of Stops to be a superset of GBFS and removed all mention/influence from GTFS, so the definition is smaller in scope and focused on micro mobility instead of future mobility types MDS may support.

Funnily enough, I was a little hesitant on using GeoJSON Foreign Members too; in my opinion, just because a spec allows injecting arbitrary data doesn't mean you should. I'd went with that approach purely because I was deferring to @jfh01's suggestion, though I absolutely am in support of the stop/station information being held at the top level, and think it should be brought up during the next Provider WG. Would you be interested in bringing that up, or would you like me to?

In any case, I think this definitely warrants some more discussion. Do you think it'd be worth having some discussions similar to the recent Agency/Provider reconciliation breakaway groups outside of the WG? Thanks for putting this all together by the way, super exciting to see these pieces coalesce :)

[rgangopadhya]

Hi @jfh01, @thekaveman, and @avatarneil (as the most likely interested parties in this PR). I wanted to be up front on our (Remix's, including @cmdoptesc's) potential availability to help drive this forward, rather than risking this slipping. We don't have much bandwidth in this quarter, so the most we can commit to now is just being involved in the conversation and making sure that the perspective reflected in this PR is considered, but we can't help beyond that.

I think materially that looks like us hopping on a call with some interested parties in a breakaway group like @avatarneil recommended a couple months ago. I was hoping we could have a meaningful conversation about this in the last provider call prior to 0.4.1, but we had to rightfully drop it in favor of getting essential 0.4.1 stuff out the door, and there wasn't enough debate about this constellation of issues. I do still think this is an important issue and would hate for it to be a lost opportunity simply because of our particular situation.

[CLAassistant]

All committers have signed the CLA.

[jfh01]

Here is a doc we put together with MobilityData and NABSA to provide additional guidance on how GBFS and MDS should align with each other:

https://github.com/openmobilityfoundation/governance/blob/master/technical/GBFS_and_MDS.md

[schnuerle]

Moved this to the 1.1.0 release per our recent calls since it has a focus on historic data for stops and we are focusing on more real time for the beta Docked/Stops in 1.0.0 with PR #427.

[schnuerle]

We will be discussing this tomorrow at our Joint Working Group meeting, so attend if you are interested. @cmdoptesc

https://github.com/openmobilityfoundation/mobility-data-specification/wiki/Web-conference-notes,-2020.09.17-(Joint-Working-Group-City-Services)

[schnuerle]

From the working group call yesterday.

Idea: make this like status changes, but for stops.
A queryable history of what happened at a stop.
Eg, what has happened at this stop in the past?
But we don’t want 2 sources of truth.
Much if not all of this info can be determined by other parts of MDS and is already required and available with a little work
See Provider routes

Populus - useful to them. Use case: know trips w/ docks/dockless already there. See travel patterns between stations.

Another way to accomplish this is an ID for each MDS event that can be referenced elsewhere, like in routes along with stop ID.

Need to get more people to weigh in and use case and see if this is needed, or if the existing data is good enough.

@cmdoptesc what does this sound like to you? Are we missing anything?
Is this issue really about a history at stops now, and not about docked bikeshare (which MDS can already support)? If so I'd like to rename the PR to reflect that, eg. 'Add History to Stops'.
In any case, I think this PR needs to be significantly reworked to use the Stops language and data structures already in MDS, instead of the Stations language you are proposing. Might be easier to close this PR and start a new one with history wrapped around the existing Stops structures.

[schnuerle]

Hi @cmdoptesc, I'd like to propose closing this PR and instead opening a new PR or issue that is focussed on just history within stops. It could be created by you or someone else. I believe all the rest of your ideas have been addressed, and we need some community feedback and a leader to take on the stops history as a standalone idea.

[schnuerle]

Closing this since there hasn't been much activity during the 1.1.0 release, and much of the PR has been addressed. Leaving it to someone to focus on Stops history in a new issue or new PR to move this idea forward.