Add vehicle type definitions #136
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -9,7 +9,9 @@ This document explains the types of files and data that comprise the General Bik | |
| * [File Requirements](#file-requirements) | ||
| * [Field Definitions](#field-definitions) | ||
| * [gbfs.json](#gbfsjson) | ||
| * [gbfs_versions.json](#gbfs_versionsjson) | ||
| * [system_information.json](#system_informationjson) | ||
| * [vehicle_types.json](#vehicle_typesjson) | ||
| * [station_information.json](#station_informationjson) | ||
| * [station_status.json](#station_statusjson) | ||
| * [free_bike_status.json](#free_bike_statusjson) | ||
|
|
@@ -54,6 +56,7 @@ File Name | Required | Defines | |
| gbfs.json | Optional | Auto-discovery file that links to all of the other files published by the system. This file is optional, but highly recommended. | ||
| gbfs_versions.json | Optional | Lists all feed endpoints published according to versions of the GBFS documentation. | ||
| system_information.json | Yes | Describes the system including System operator, System location, year implemented, URLs, contact info, time zone | ||
| vehicle_types.json | Conditionally required | Describes the types of vehicles that System operator has available for rent. Required of systems that include information about vehicle types in the station_status and/or free_bike_status files. If this file is not included, then all vehicles in the feed are assumed to be non-motorized bicycles | ||
| station_information.json | Conditionally required | Mostly static list of all stations, their capacities and locations. Required of systems utilizing docks. | ||
| station_status.json | Conditionally required | Number of available bikes and docks at each station and station availability. Required of systems utilizing docks. | ||
| free_bike_status.json | Conditionally required | Describes bikes that are available for rent. Required of systems that don't utilize docks or offer bikes for rent outside of stations. | ||
|
|
@@ -183,7 +186,7 @@ Field Name | Required | Defines | |
| _versions_ | Yes | Array that contains one object, as defined below, for each of the available versions of a feed. The array must be sorted by increasing MAJOR and MINOR version number. | ||
| \- version | Yes | String identifying the semantic version of the feed in the form X.Y. | ||
| \- url | Yes | URL of the corresponding gbfs.json endpoint. | ||
|
|
||
| ```json | ||
| { | ||
| "last_updated": 1434054678, | ||
|
|
@@ -223,6 +226,48 @@ email | Optional | A single contact email address for customers to | |
| timezone | Yes | The time zone where the system is located. Time zone names never contain the space character but may contain an underscore. Please refer to the "TZ" value in https://en.wikipedia.org/wiki/List_of_tz_database_time_zones for a list of valid values | ||
| license_url | Optional | A fully qualified URL of a page that defines the license terms for the GBFS data for this system, as well as any other license terms the system would like to define (including the use of corporate trademarks, etc) | ||
|
|
||
| ### vehicle_types.json | ||
|
|
||
| The following fields are all attributes within the main "data" object for this feed. | ||
|
|
||
| Field Name | Required | Defines | ||
| ------------------| --------- | ---------- | ||
| 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>`car`</li><li>`moped`</li><li>`other`</li><li>`scooter`</li></ul> | ||
| \- propulsion_type | Yes | An enumerable that describes 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) | ||
| \- is_carryable | Yes | 1/0 boolean - is the vehicle small and lightweight enough that it could be transported up/down stairs or rolled up/down a steep hill? | ||
| \- max_range_meters | Conditionally Required | If the vehicle has a motor (as indicated by having a value other than `human` in the `propulsion_type` field), this field is required. This represents the furthest distance in meters that the vehicle can travel without recharging or refueling when it has the maximum amount of energy potential (for example a full battery or full tank of gas). | ||
| \- name | Optional | The public name of this vehicle type. | ||
|
|
||
| Example: | ||
|
|
||
| ```json | ||
| { | ||
| "last_updated": 1434054678, | ||
| "ttl": 0, | ||
| "version": "1.0", | ||
| "data": { | ||
| "vehicle_types": [ | ||
| { | ||
| "vehicle_type_id": "abc123", | ||
| "form_factor": "bicycle", | ||
| "propulsion_type": "human", | ||
| "is_carryable": 1, | ||
| "name": "Example Basic Bike" | ||
| }, | ||
| { | ||
| "vehicle_type_id": "def456", | ||
| "form_factor": "scooter", | ||
| "propulsion_type": "electric", | ||
| "is_carryable": 1, | ||
| "name": "Example E-scooter V2", | ||
| "max_range_meters": 12345 | ||
| } | ||
| ] | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| ### station_information.json | ||
| All stations contained in this list are considered public (ie, can be shown on a map for public use). If there are private stations (such as Capital Bikeshare’s White House station) these should not be exposed here and their status should not be included in station_status.json. | ||
|
|
@@ -240,22 +285,112 @@ 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, 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:
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 |
||
|
|
||
| Example: | ||
|
|
||
| ```json | ||
| { | ||
| "last_updated": 1434054678, | ||
| "ttl": 0, | ||
| "version": "1.0", | ||
| "data": { | ||
| "stations": [ | ||
| { | ||
| "station_id": "pga", | ||
| "name": "Parking garage A", | ||
| "lat": 12.34, | ||
| "lon": 45.67, | ||
| "vehicle_type_capacity": { | ||
| "abc123": 7, | ||
| "def456": 9 | ||
| } | ||
| } | ||
| ] | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| ### 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 | Conditionally required | Number of vehicles of all types available for rental. This field is required in feeds that do not have the [vehicle_types.json](#vehicle_typesjson) file defined. In feeds that do have the [vehicle_types.json](#vehicle_typesjson) file defined, this field should not be defined and the `vehicles` field should be used instead. | ||
| \- num_bikes_disabled | Optional | Number of disabled vehicles of any type at the station. Vendors who do not want to publicize the number of disabled vehicles or docks in their system can opt to omit station capacity (in station_information), num_bikes_disabled and num_docks_disabled. If station capacity is published then broken docks/vehicles can be inferred (though not specifically whether the decreased capacity is a broken bike or dock) | ||
| \- num_docks_available | Conditionally Required | Number of docks accepting returns of any vehicle type. This field is required in feeds that do not have the [vehicle_types.json](#vehicle_typesjson) file defined. In feeds that do have the [vehicle_types.json](#vehicle_typesjson) file defined, this field should not be defined and the `vehicle_docks_available` field should be used instead. | ||
| \- num_docks_disabled | Optional | Number of empty but disabled dock points at the station. This value remains as part of the spec as it is possibly useful during development | ||
| \- is_installed | Yes | 1/0 boolean - is the station currently on the street | ||
| \- is_renting | Yes | 1/0 boolean - is the station currently renting bikes (even if the station is empty, if it is set to allow rentals this value should be 1) | ||
| \- is_returning | Yes | 1/0 boolean - is the station accepting bike returns (if a station is full but would allow a return if it was not full then this value should be 1) | ||
| \- last_reported | Yes | Integer POSIX timestamp indicating the last time this station reported its status to the operator's backend | ||
| \- vehicle_docks_available | Conditionally Required | This field is required in feeds where the [vehicle_types.json](#vehicle_typesjson) is defined. This field's value is an object consisting of keys that are vehicle_type_ids as described in [vehicle_types.json](#vehicle_typesjson) and values that represent the number of docks accepting vehicle returns of vehicles of the respective vehicle type. If a single dock can accept multiple vehicle types, these should be added to the count of available docks for each applicable vehicle type (ie: there could be 8 total docks at a station, but there could be two vehicle types that each have 5 available docks). | ||
| \- vehicle_docks_disabled | Optional | An object consisting of keys that are vehicle_type_ids as described in [vehicle_types.json](#vehicle_typesjson) and values that represent the number of empty but disabled dock points for vehicles of the respective vehicle type at the station. | ||
| \- vehicles | Conditionally Required | This field is required if the [vehicle_types.json](#vehicle_typesjson) file has been defined. This field's value is an array of objects. Each object contains data about a specific vehicle that is currently present at the docking station. Each of these vehicles is assumed to be rentable unless otherwise indicated with the is_reserved or is_disabled flags. All of the remaining fields in this table represent key/values for each vehicle object in this array. | ||
| \-- bike_id | Yes | Unique identifier of a bike | ||
| \-- 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 | Yes | The vehicle_type_id of this vehicle as described in [vehicle_types.json](#vehicle_typesjson). | ||
| \-- current_range_meters | Conditionally Required | If the corresponding vehicle_type definition for this vehicle has a motor, then this field is required. 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. | ||
|
|
||
| Example: | ||
|
|
||
| ```json | ||
| { | ||
| "last_updated": 1434054678, | ||
| "ttl": 0, | ||
| "version": "1.0", | ||
| "data": { | ||
| "stations": [ | ||
| { | ||
| "station_id": "station 1", | ||
| "is_installed": 1, | ||
| "is_renting": 1, | ||
| "is_returning": 1, | ||
| "last_reported": 1434054678, | ||
| "vehicles": [{ | ||
| "bike_id": "mno345", | ||
| "is_reserved": 0, | ||
| "is_disabled": 0, | ||
| "vehicle_type_id": "abc123" | ||
| }, { | ||
| "bike_id": "pqr678", | ||
| "is_reserved": 0, | ||
| "is_disabled": 0, | ||
| "vehicle_type_id": "def456", | ||
| "current_range_meters": 5432 | ||
| }], | ||
| "vehicle_docks_available": { | ||
| "abc123": 2, | ||
| "def456": 1 | ||
| } | ||
| }, { | ||
| "station_id": "station 2", | ||
| "is_installed": 1, | ||
| "is_renting": 1, | ||
| "is_returning": 1, | ||
| "last_reported": 1434054678, | ||
| "num_docks_available": 8, | ||
| "vehicles": [{ | ||
| "bike_id": "stu901", | ||
| "is_reserved": 0, | ||
| "is_disabled": 0, | ||
| "vehicle_type_id": "abc123" | ||
| }, { | ||
| "bike_id": "vwx234", | ||
| "is_reserved": 0, | ||
| "is_disabled": 0, | ||
| "vehicle_type_id": "def456", | ||
| "current_range_meters": 5432 | ||
| }] | ||
| } | ||
| ] | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
|
|
||
| ### free_bike_status.json | ||
| Describes bikes that are not at a station and are not currently in the middle of an active ride. | ||
|
|
@@ -268,6 +403,42 @@ 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. | ||
| \- last_reported | Optional | Integer POSIX timestamp indicating the last time this vehicle reported its status to the operator's backend | ||
| \- current_range_meters | Conditionally Required | If the [vehicle_types.json](#vehicle_typesjson) file is defined and the corresponding vehicle_type definition for this vehicle has a motor, then this field is required. 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. |
||
| Example: | ||
|
|
||
| ```json | ||
| { | ||
| "last_updated": 1434054678, | ||
| "ttl": 0, | ||
| "version": "1.0", | ||
| "data": { | ||
| "bikes": [ | ||
| { | ||
| "bike_id": "ghi789", | ||
| "last_reported": 1434054678, | ||
| "lat": 12.34, | ||
| "lon": 56.78, | ||
| "is_reserved": 0, | ||
| "is_disabled": 0, | ||
| "vehicle_type_id": "abc123" | ||
| }, { | ||
| "bike_id": "jkl012", | ||
| "last_reported": 1434054687, | ||
| "lat": 12.34, | ||
| "lon": 56.78, | ||
| "is_reserved": 0, | ||
| "is_disabled": 0, | ||
| "vehicle_type_id": "def456", | ||
| "current_range_meters": 450 | ||
| } | ||
| ] | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
|
|
||
| ### system_hours.json | ||
| Describes the system hours of operation. A JSON array of hours defined as follows: | ||
|
|
@@ -376,9 +547,6 @@ There are some items that were proposed in an earlier version of this document b | |
| * _equipment_ - Removed due to a lack of specificity behind the intent of this field and a question about the actual relevance to the public | ||
| * _jurisdictions_ - It is believed that the need for this field is negated by the presence of the system_regions.json feed | ||
|
|
||
| ## Disclaimers | ||
|
|
||
| _Apple Pay, PayPass and other third-party product and service names are trademarks or registered trademarks of their respective owners._ | ||
|
|
||
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@evansiroky I'm curious the rationale behind making the
nameoptional. My initial thought was that this might complicate things for consumers who will then need to invent language around displaying this data, but as a consumer you probably have much better insights into whether this would actually a problem or not.There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
As a consumer, I would prefer this field to be required. However, it seems that a number of systems don't have names for their vehicles. Take for example Pacers Bikeshare. I can't find any info on the models they call their bikes - even though they have both regular and e-bikes. So the thought was that maybe some producers don't call their bike models anything and maybe this field should be optional to reflect that. I'm open to making this required.