Add vehicle type definitions #136
Conversation
|
Interesting proposal, maybe it's time for a bigger update for GBFS/GVFS to include all the developments that have been going on over the past 4 years (The proposal that you are doing now is breaking existing api's, that requires a 2.0 update). This is a wish list I created last year https://github.com/openbikeshare/gbfsplus. It would be nice if as much business rules as possible can be generalised in a standard. That's the only way accurate planning algorithms can be build. |
gvfs.md
Outdated
| "vehicle_weight": 15.88, | ||
| "power_output": 350, | ||
| "passenger_capacity": 1, | ||
| "enclosed": 0 |
There was a problem hiding this comment.
Maybe add a field for if and what kind of driver license is needed according to local rules.
There was a problem hiding this comment.
Is there some data standard that we can reference to add this data?
There was a problem hiding this comment.
Within the European Union we do have a standardised classification https://en.wikipedia.org/wiki/European_driving_licence, I don't know if there is any data standard for this.
gvfs.md
Outdated
| "short_name": "ib", | ||
| "url": "https://www.inboardtechnology.com/", | ||
| "timezone": "America/Los_Angeles", | ||
| "vehicle_types": [ |
There was a problem hiding this comment.
Is there a reason you prefer this information within system.json?
A separate file for vehicle_types is more in the spirit of the standard until now in my opinion. But it doesn't really matter to me.
There was a problem hiding this comment.
I put it in here because I thought it made sense for the vehicles to be associated with a certain system or operator.
gvfs.md
Outdated
| "vehicle_url": "https://www.inboardtechnology.com/products/m1-electric-skateboard", | ||
| "image_small": "http://cdn.shopify.com/s/files/1/1136/4406/files/Skateboard_x150.png?11016692238788873189", | ||
| "image_large": "http://cdn.shopify.com/s/files/1/1136/4406/products/m1_pdp_fullBleed_6_9e6614b5-c3e4-4dd1-b18b-fd51451d0c17_1600x.jpg?v=1535665708", | ||
| "propulsion_type": "ELECTRIC", |
There was a problem hiding this comment.
maybe add a field voor vehicle_type as well?
bike/scooter/car/motor
There was a problem hiding this comment.
I intentionally avoided this kind of field because there are already so many kinds of micromobility vehicles being made that may not be classifiable in a commonly understood way. In the example json in this PR, I included an electric skateboard which already falls outside the proposed types you have listed. This kind of classification of the vehicle type I believe is best left for interpretation by the gvfs-consuming application. In OpenTripPlanner I forsee adding updaters that would parse each vehicle type and assign it a various operational characteristics that would determine how the vehicle would be able to travel through the street network in the routing algorithms.
There was a problem hiding this comment.
I think it doesn't hurt to add a vehicle_type for all mainstream modes. If new mainstream modes appear they can be added as well to the specification without breaking previous api's. We could also specify 'other' for all other modes that should be derived.
|
IMO with scooters entering the mix this is a solid move to start thinking about this. We work with all of the GBFS feeds daily and noticed everyone is starting to deviate from the spec to accommodate dockless bikes, custom fields for scooter battery levels, vehicle type fields all named differently, etc. - and once everyone starts to deviate from the spec for their own use cases the spec doesn't mean much anymore. To pull off a big change like this I think it needs to have an accompanying JSONSchema + a CLI or web tool to validate a URL against the spec. This will make it much easier for people to migrate to this next iteration. I can assist anywhere needed for this, so let me know if you need a hand with it. As one point of feedback though - I think it would be nice to use objects instead of arrays of objects with key/value pairs ( |
|
I very much like the idea of a CLI and/or validation tool, but do not have the capacity for contributing towards building one at this time. Looks like someone may already be doing this in https://github.com/PierrickP/gbfs-validator? |
|
@evansiroky it seems like simple JSON schema validation would be perfect for validation across languages/implementations. #37 was opened for that a while back. |
|
@evansiroky good idea! I've been working the past few months on generalizing the GBFS specs to fit any transport mode. We have a large Mobility as a Service (also called mobility on demand) deployment in the Netherlands at the moment, I'm trying to facilitate a number of transport operators (bike & scooter sharing, car sharing and public transport) into creating a common API. We have a working group for standardisation set up within the MaaS-alliance, a global public-private collaboration of stakeholders. We are aiming to set up our work on https://github.com/maas-alliance/apis. I've been working from Swaggerhub until now (https://app.swaggerhub.com/apis/efel85/GTOAS/1.0.4), but will be merging everything on there to the maas-alliance github. I would be very interested in hearing what you think and if we can collaborate! |
|
Today I have to start creating TypeScript interfaces to use for both bikes and scooters. This PR is very interesting to me, but like @contra says, we will have to deviate from the GBFS standard because this isn't ready yet. But I think we will look into following this PR unless anybody knows of a better approach. |
|
This is a great discussion which highlights some much needed updates to the specification. I'm working with NABSA on a proposal to hire a consultant to help manage this project. If approved, NABSA will issue an RFP to develop a governance model and versioning scheme that will help keep things moving forward. In addition to better governance, GBFS needs to better reflect changes in the mobility industry. NABSA has now broadened it's scope to include micro-mobility services beyond shared bicycles and the specification should support those services. What else should go into a scope of work for this RFP? I'll also post this on the Issues page. |
- revert most renamings of bike -> vehicle - rename gvfs.json file back to gbfs.json - move vehicle definitions to vehicle_types.json file - add vehicle information data in a non-breaking manner
|
I have significantly refactored this PR. Please see the updated PR description. |
gbfs.md
Outdated
| \- vehicle_type_id | Yes | Unique identifier of a vehicle type. See [Field Definitions](#field-definitions) above for ID field requirements | ||
| \- form_factor | Yes | An enumerable describing the vehicle's general form factor. <br /><br />Current valid values are:<br /><ul><li>`bicycle`</li><li>`scooter`</li><li>`car`</li></ul> | ||
| \- propulsion_types | Yes | An array consisting of enumerables that describe the propulsion type of the vehicle. <br /><br />A device may have one or more values from the propulsion_type, depending on the number of modes of operation. For example, a scooter that can be powered by foot or by electric motor would have the propulsion_type represented by the array ['human', 'electric']. A bicycle with pedal-assist would have the propulsion_type represented by the array ['human', 'electric_assist'] if it can also be operated as a traditional bicycle. A car with an internal combustion engine would be represented by the array ['combustion']<br /><br />Current valid values are:<br /><ul><li>`human` _(Pedal or foot propulsion)_</li><li>`electric assist` _(Provides power only alongside human propulsion)_</li><li>`electric` _(Contains throttle mode with a battery-powered motor)_</li><li>`combustion` _(Contains throttle mode with a gas engine-powered motor)_</li></ul> This field was copied from [City of Los Angeles Mobility Data Specification](https://github.com/CityOfLosAngeles/mobility-data-specification/blob/73995a151f0a1d67aab3d617a4693f8f81967936/provider/README.md#propulsion-types) | ||
| \- description | Optional | A free text description of the vehicle |
There was a problem hiding this comment.
Can you add what is description meant to be used for?
There was a problem hiding this comment.
Good idea. I added more detail.
gbfs.md
Outdated
| ### vehicle_types.json | ||
| The following fields are all attributes within the main "data" object for this feed. | ||
|
|
||
| ield Name | Required | Defines |
| @@ -218,6 +325,38 @@ bikes | Yes | Array that contains one object per bike that is | |||
| \- lon | Yes | Longitude of the bike. The field value must be a valid WGS 84 latitude in decimal degrees format. See: http://en.wikipedia.org/wiki/World_Geodetic_System, https://en.wikipedia.org/wiki/Decimal_degrees | |||
| \- is_reserved | Yes | 1/0 value - is the bike currently reserved for someone else | |||
| \- is_disabled | Yes | 1/0 value - is the bike currently disabled (broken) | |||
| \- vehicle_type_id | Conditionally Required | The vehicle_type_id of this vehicle as described in [vehicle_types.json](#vehicle_typesjson). This field is required if the [vehicle_types.json](#vehicle_typesjson) is defined. | |||
| \- range | Optional | If the vehicle has a motor, this value represents the furthest distance in meters that the vehicle can travel without recharging or refueling with the vehicle's current charge or fuel. | |||
|
|
|||
There was a problem hiding this comment.
Can we add a last_reported field here, which would optionally specify the timestamp when the bike was last reported (defaulting to feed last_updated)? It would be consistent with station_status.json, which already has last_reported.
There was a problem hiding this comment.
I added this field and marked it as required. I believe this might introduce a breaking change, so if I need to mark it as optional in order to be backwards-compatible, I will do so.
gbfs.md
Outdated
| @@ -218,6 +325,38 @@ bikes | Yes | Array that contains one object per bike that is | |||
| \- lon | Yes | Longitude of the bike. The field value must be a valid WGS 84 latitude in decimal degrees format. See: http://en.wikipedia.org/wiki/World_Geodetic_System, https://en.wikipedia.org/wiki/Decimal_degrees | |||
| \- is_reserved | Yes | 1/0 value - is the bike currently reserved for someone else | |||
| \- is_disabled | Yes | 1/0 value - is the bike currently disabled (broken) | |||
| \- vehicle_type_id | Conditionally Required | The vehicle_type_id of this vehicle as described in [vehicle_types.json](#vehicle_typesjson). This field is required if the [vehicle_types.json](#vehicle_typesjson) is defined. | |||
| \- range | Optional | If the vehicle has a motor, this value represents the furthest distance in meters that the vehicle can travel without recharging or refueling with the vehicle's current charge or fuel. | |||
There was a problem hiding this comment.
current_range_meters would be a more explicit name. "current" makes it clear what range is being referred to and its nice to make the units explicit. Similarly, I'd prefer if max_range was renamed to max_range_meters.
There was a problem hiding this comment.
Sounds good, I implemented this as you recommended.
|
Wanted to make sure that the folks who were engaged in this conversation earlier have the chance to see the changes @evansiroky made and provide feedback. |
gbfs.md
Outdated
| ------------------| --------- | ---------- | ||
| vehicle_types | Yes | Array that contains one object per vehicle type in the system as defined below | ||
| \- vehicle_type_id | Yes | Unique identifier of a vehicle type. See [Field Definitions](#field-definitions) above for ID field requirements | ||
| \- form_factor | Yes | An enumerable describing the vehicle's general form factor. <br /><br />Current valid values are:<br /><ul><li>`bicycle`</li><li>`scooter`</li><li>`car`</li></ul> |
There was a problem hiding this comment.
I think there may be a missing moped value here for providers like Revel/Scoot.
There was a problem hiding this comment.
I went ahead and added moped. I also added the value other in order to allow the definition of any vehicle form factor that is not able to be categorized by any of the pre-defined form factors.
gbfs.md
Outdated
|
|
||
| ### station_status.json | ||
|
|
||
| Field Name | Required | Defines | ||
| --------------------- | ----------| ---------- | ||
| stations | Yes | Array that contains one object per station in the system as defined below | ||
| \- station_id | Yes | Unique identifier of a station (see station_information.json) | ||
| \- num_bikes_available | Yes | Number of bikes available for rental | ||
| \- num_bikes_available | Conditionally required | Number of vehicles of all types available for rental. This field is not required if the `vehicles_available` field has been defined. |
There was a problem hiding this comment.
Thoughts on deprecating this + num_docks_available since it is bike specific? Not sure if making breaking changes are out of scope here, since versioning is still up for discussion. Seems like a lot to have two ways of specifying the same thing, but one is clearly better than the other.
There was a problem hiding this comment.
I do like the idea of versioning and would change this and rename everything that says "bike" to "vehicle", but will await guidance from the community.
|
@HeidiMG Left a few minor comments, overall looks great and a solid improvement. |
gbfs.md
Outdated
| @@ -190,22 +229,90 @@ stations | Yes | Array that contains one object per station in th | |||
| \- region_id | Optional | ID of the region where station is located (see [system_regions.json](#system_regionsjson)) | |||
| \- post_code | Optional | Postal code where station is located | |||
| \- rental_methods | Optional | Array of enumerables containing the payment methods accepted at this station. <br />Current valid values (in CAPS) are:<br /><ul><li>KEY _(i.e. operator issued bike key / fob / card)_</li> <li>CREDITCARD</li> <li>PAYPASS</li> <li>APPLEPAY</li> <li>ANDROIDPAY</li> <li>TRANSITCARD</li> <li>ACCOUNTNUMBER</li> <li>PHONE</li> </ul> This list is intended to be as comprehensive at the time of publication as possible but is subject to change, as defined in [File Requirements](#file-requirements) above | |||
| \- capacity | Optional | Number of total docking points installed at this station, both available and unavailable | |||
| \- capacity | Optional | Number of total docking points installed at this station, both available and unavailable, regardless of what vehicle types are allowed at each dock. This field should only be used if every dock at the station is able to accept every vehicle type used in the system. | |||
| \- vehicle_type_capacity | Optional | An object where each key is a vehicle_type_id as described in [vehicle_types.json](#vehicle_typesjson) and the value is a number representing the total docking points installed at this station, both available and unavailable for the specified vehicle type. | |||
There was a problem hiding this comment.
Do we need to enable a hierarchy or groups of vehicle types? e.g. are there cases where there are various defined electric bikes with different amenities, and we just need to specify capacity for electric bikes in general?
There was a problem hiding this comment.
I don't think this is necessary as it is possible to determine the form factor and additional information about a vehicle type by looking up the data associated with a particular vehicle type ID.
There was a problem hiding this comment.
Recently and number of cities ( DC, Bay Area, Portland etc.) have taken steps to introduce various types of adaptive cycles to their bike share fleets. Additionally there are a number of examples of shared cargo bikes now in Europe. How would these types of vehicles be differentiated within the form factor and vehicle type? Existing examples are:
- Upright handcycle
- Recumbent handcycle
- Recumbent leg trike
- Recumbent trike tandem
- Side-by-side tandem bicycle
- Cargo bicycle
- Cargo tricycle
There was a problem hiding this comment.
I think the intent of the form_factor field is to have a very general classification and avoid making up a potentially endless hyper-specific list of enumerations of what a vehicle's "type" is. Therefore, all of those vehicles @mplsmitch listed would each have a form_factor value of bicycle. For now, the place to further explain details about the vehicle would be in the description field of a vehicle type object in the vehicle_types.json file. In my initial PR, I didn't include this field, but instead proposed to add many more fields with additional places to differentiate vehicles (such as adding pictures which @sven4all brought up again). However, after a discussion with @antrim and @kanagy, I removed those other fields and added the form_factor field in order to try to make a minimum viable pull request to merge in.
|
Good improvements, I would like to support this PR. |
gbfs.md
Outdated
| "vehicle_type_id": "abc123", | ||
| "form_factor": "bicycle", | ||
| "propulsion_types": ["human"], | ||
| "description": "a bicycle without a motor" |
There was a problem hiding this comment.
I think it would be really nice if it's possible to add a link to a photo/graphic of the vehicle type. Is that something we can specify as optional field as well well?
If we add it, I think it's a good idea to specify the resolution and format of the image.
|
This was one issue discussed during an in-person GBFS developers workshop held before the NABSA 2019 conference (workshop agenda and notes). Participants discussed fields that we’d like to see included in the spec in the future, but there was general agreement that this proposal is a valuable addition that makes the spec better able to represent options available without foreclosing on future additions to the spec. Other issues that came up for future work include the creation and maintenance of a centralized vehicle type definition repository and traveler privacy implications of increasingly specific vehicle attributes. A couple of changes proposed during the workshop include: making free_bike_status.json last_reported optional and changing "description" to "name." The intention is for last_reported to become required in the future, but we want to get the non-breaking changes in motion as soon as possible. |
|
Seeing no further feedback, I think it is a good time to call a vote again to try to see if this proposal is can be accepted. I hereby call a vote on this proposal. Voting will be open for 7 full days, until 11:59PM UTC on April 21st. Please vote for or against the proposal, and include the organization for which you are voting in your comment. |
|
Voting +1 for Stae - great work @evansiroky 👍 |
|
I vote in favor of this proposal for MIA map intelligence agency. |
|
Voting +1 for Google Maps. Thanks for the work Evan. |
|
+1 from PBSC |
|
Voting +1 on behalf of Transit |
|
Voting +1 on behalf of Bird. Thanks @evansiroky for pushing this across the line. |
gbfs.md
Outdated
| `vehicle_types` | Yes | Array | Array that contains one object per vehicle type in the system as defined below | ||
| \- `vehicle_type_id` | Yes | ID | Unique identifier of a vehicle type. See [Field Definitions](#field-definitions) above for ID field requirements | ||
| \- `form_factor` | Yes | Enum | The vehicle's general form factor. <br /><br />Current valid values are:<br /><ul><li>`bicycle`</li><li>`car`</li><li>`moped`</li><li>`other`</li><li>`scooter`</li></ul> | ||
| \- `propulsion_type` | Yes | Enum | The primary propulsion type of the vehicle. <br /><br />Current valid values are:<br /><ul><li>`human` _(Pedal or foot propulsion)_</li><li>`electric_assist` _(Provides power only alongside human propulsion)_</li><li>`electric` _(Contains throttle mode with a battery-powered motor)_</li><li>`combustion` _(Contains throttle mode with a gas engine-powered motor)_</li></ul> This field was insipred by, but differs from the propulsion types field described in the [City of Los Angeles Mobility Data Specification](https://github.com/CityOfLosAngeles/mobility-data-specification/blob/73995a151f0a1d67aab3d617a4693f8f81967936/provider/README.md#propulsion-types) |
There was a problem hiding this comment.
Please update this description from City of Los Angeles Mobility Data Specification --> Open Mobility Foundation and the URL updated to https://github.com/openmobilityfoundation/mobility-data-specification
|
Wouldn't this be the time to change from |
|
@charlesjump I agree that it's time to vote on changing bike_id to vehicle_id, but right now this PR represents a non-breaking change. Is it worth making this whole PR a breaking change to make the transition to vehicle_id now, or could we open a separate PR for that breaking change and go ahead and get this one in process? |
|
@heidiguenin which version of GBFS will this change be included? |
|
@charlesjump - Both #219 (Geofencing, virtual station, and dockless support) and vehicle type definitions, if passed, would be included in v2.1. I believe that they're mostly already implemented out in the field, too, so they should be able to move from release candidate to official fairly quickly. Changing bike_id to vehicle_id, once passed in a vote, would be added to the v3.0 release candidate that currently includes #182 - requiring license_url. |
|
The vote on this is now closed, and it passes! Votes in favor: No votes against. We'll be merging and creating v2.1RC in the coming days. If you're implementing this currently or planning on it in the future, please let us know. Thanks all! |
correcting spelling error
|
As we're getting ready to tag the new release - is there anyone who is implementing this PR yet? |
Google is starting implementation with Lime. We plan to migrate our custom fields to use the official vehicle_types.json for free floating bikes and scooters. |
Hello there, I am Evan Siroky and I have been working on improving OpenTripPlanner to be able to plan multi-modal trips with one-way car rentals (Car2Go and ReachNow). In this process, I copy-pasted a lot of the code for the bikeshare stuff and realized that it would be great if all this common code could be generalized to accomodate any kind of vehicle rental system.
This spec is a great standard in use by many bikeshare systems, but it can kind of be generalized to other modes. This repository already has a ticket about adding scooters (#105) and there's also some discussion about bike types (#81). It also looks like there are 2 other places where people have began work on proposing a change to add e-bikes (see @sven4all's changes here and @dsgermain's changes here).
I've done a lot of thinking about this and am going to go ahead and throw this PR out there with proposed changes that will hopefully allow this specification to accomodate basically any vehicle that someone could rent. My approach to adding these fields comes from a trip planning software development perspective, so some of the highly technical bits of information like the cruising speed, weight, power output and energy potential are things that I'm asking for in order to be able to calculate how far a vehicle could travel before running out of juice and how well the vehicle could climb inclined roads.
High level changes
GBFS (General Bikeshare Feed Specification)toGVFS (General Vehicleshare Feed Specification)to reflect the specification's possibility of defining a vehicle share system with any type of vehicle. 🤣 Not sure how far I'm going to get with this suggestion, so I'm totally fine with changing things back to GBFS.gbfs.jsontogvfs.json. 🤣free_bike_status.jsontofree_vehicle_status.jsonChanges to
system_information.jsonAdds a required field
vehicle_types. This value of this key would contain an array of objects with the following keys:vehicle_type_id,name,description,vehicle_url,image_small,image_large,propulsion_type,cruising_speed,range_with_full_energy_potential,vehicle_weight,power_output,passenger_capacityandenclosed.Changes to
station_information.jsonAdds a required field
allowed_vehicle_typeswhich would contain a list of strings that arevehicle_type_ids that are allowed to use the station.Changes to
station_status.jsonnum_bikes_availabletonum_vehicles_availablenum_bikes_disabledtonum_vehicles_disablednum_vehicles_available,num_vehicles_disabled,num_docks_availableandnum_docks_disabledare all changed to have an object with a key representing the vehicle_type_id and a numeric value indicating the number for that vehicle type.Changes to
free_bike_status.jsonfree_vehicle_status.jsonbikesis renamed tovehiclesbike_idis renamed tovehicle_idvehicle_type_idandrange_with_current_energy_potentialare addedChanges to
system_alerts.jsonvehicle_type_idsis added2019-09-19 Update
After discussions occurring as a part of ongoing work related to #137, I am significantly revising and simplifying this PR in hopes of coming to a consensus on a minimum viable product. Furthermore, I have reimplemented this PR in a non-breaking way. See below for a list of proposed changes:
Addition of
vehicle_types.jsonfileThis optional file can be used to desribe different vehicle types that an operator is renting out. The current fields allowed are
vehicle_type_id,form_factor,propulsion_types,descriptionandmax_range.Changes to
station_information.jsonfileThe field
vehicle_type_capacitycan now be added to specify capacity by vehicle type at a station. A note of clarification has been added to the existingcapacityfield in such a way that existing feeds won't break.Changes to
station_status.jsonfileThe fields
vehicle_docks_available,vehicle_docks_disabled,vehicles_availableandvehicles_disabledhave all been added. Clarification notes and changes in requirements have been added to thenum_bikes_availableandnum_docks_availablein such a way that existing feeds won't break with these changes.Changes to
free_bike_status.jsonfileThe fields
vehicle_type_idandrangehave been added in such a way that existing feeds won't break.2019-10-07 Update
After discussions occurring at the GBFS developer workshop, I have made two small changes that should now make this PR non-breaking. See below for a list of all proposed changes for this PR:
Addition of
vehicle_types.jsonfileThis optional file can be used to describe different vehicle types that an operator has available for rent. The current fields allowed are
vehicle_type_id,form_factor,propulsion_types,max_range_metersandname.Changes to
station_information.jsonfileThe field
vehicle_type_capacitycan now be added to specify capacity by vehicle type at a station. A note of clarification has been added to the existingcapacityfield in such a way that existing feeds won't break.Changes to
station_status.jsonfileThe fields
vehicle_docks_available,vehicle_docks_disabled,vehicles_availableandvehicles_disabledhave all been added. Clarification notes and changes in requirements have been added to thenum_bikes_availableandnum_docks_availablein such a way that existing feeds won't break with these changes.Changes to
free_bike_status.jsonfileThe fieldsvehicle_type_id,last_reportedandcurrent_range_metershave been added in such a way that existing feeds won't break.2019-11-23 Update
See below for a list of all proposed changes for this PR:
Addition of
vehicle_types.jsonfileThis optional file can be used to describe different vehicle types that an operator has available for rent. The current fields allowed are
vehicle_type_id,form_factor,propulsion_type,is_carryable,max_range_metersandname.Changes to
station_information.jsonfileThe field
vehicle_type_capacitycan now be added to specify capacity by vehicle type at a station. A note of clarification has been added to the existingcapacityfield in such a way that existing feeds won't break.Changes to
station_status.jsonfileThe fields
vehicle_docks_available,vehicle_docks_disabledandvehicleshave all been added. Clarification notes and changes in requirements have been added to thenum_bikes_available,num_bikes_disabled,num_docks_availableandlast_reportedin such a way that existing feeds won't break with these changes.Changes to
free_bike_status.jsonfileThe fields
vehicle_type_id,last_reportedandcurrent_range_metershave been added in such a way that existing feeds won't break.