Skip to content

Commit

Permalink
Extending vehicle_types.json (#370)
Browse files Browse the repository at this point in the history 
* Update gbfs.md

* Update form_factor enums

Replaces scooter enum and adds notes about new scooter form factors, corrects reference to home_station_id 

Co-authored-by: Mitch Vars <mitch@mobilitydata.org>
  • Loading branch information
@josee-sabourin
josee-sabourin and Mitch Vars committed Dec 15, 2021
1 parent 856c4fc commit 09a1a19
Showing 1 changed file with 34 additions and 5 deletions.
39 changes: 34 additions & 5 deletions gbfs.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -413,20 +413,22 @@ Field Name | REQUIRED | Type | Defines
---|---|---|---
`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 Types](#field-types) 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>`scooter`</li><li>`other`</li></ul>
\- `form_factor` | Yes | Enum | The vehicle's general form factor. <br /><br />Current valid values are:<br /><ul><li>`bicycle`</li><li>`cargo_bicycle`</li><li>`car`</li><li>`moped`</li><li>`scooter` (will be deprecated in v3.0)</li><li>`scooter_standing` (standing kick scooter)</li><li>`scooted_seated` (this is a kick scooter with a seat, not to be confused with `moped`)</li><li>`other`</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 inspired by, but differs from the propulsion types field described in the [Open Mobility Foundation Mobility Data Specification](https://github.com/openmobilityfoundation/mobility-data-specification/blob/master/provider/README.md#propulsion-types).
\- `max_range_meters` | Conditionally REQUIRED | Non-negative float | 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 | String | The public name of this vehicle type.
\- `wheel_count` | OPTIONAL | Non-negative Integer | Number of wheels this vehicle type has.
\- `max_permitted_speed` | OPTIONAL | Non-negative Integer | The maximum speed in kilometers per hour this vehicle is permitted to reach in accordance with local permit and regulations.
\- `rated_power` | OPTIONAL | Non-negative Integer | The rated power of the motor for this vehicle type in watts.
\- `default_reserve_time`<br/>*(added in v2.3-RC)* | OPTIONAL | Non-negative Integer | Maximum time in minutes that a vehicle can be reserved before a rental begins. When a vehicle is reserved by a user the vehicle remains locked until the rental begins. During this time the vehicle is unavailable and cannot be be reserved or rented by other users. The vehicle status in `free_bike_status.json` MUST be set to `is_reserved = true`. If the value of `default_reserve_time` elapses without a rental beginning, the vehicle status MUST change to `is_reserved = false`. If `default_reserve_time` is set to `0` the vehicle type cannot be reserved.
\- `return_type`<br/>*(added in v2.3-RC)*| OPTIONAL | Array | The conditions for returning the vehicle at the end of the trip. For vehicles that have more than one return option, include all applicable methods in the array. <br /><br />Current valid values are:<br /><ul><li>`free_floating` _(The vehicle can be returned anywhere permitted within the service area - note that this field is subject to rules in `geofencing_zones.json` if defined.)_</li><li>`roundtrip_station` _(The vehicle must be returned to the initial rental station. Cannot be defined in combination with `free_floating`.)_</li><li>`any_station` _(The vehicle must be returned to any station within the service area - note that a specific station can be defined in [free_bike_status.json](#free_bike_status.json) using `home_station_id`. Cannot be defined in combination with `roundtrip_station`.)_
\- `return_type`<br/>*(added in v2.3-RC)*| OPTIONAL | Array | The conditions for returning the vehicle at the end of the trip. For vehicles that have more than one return option, include all applicable methods in the array. <br /><br />Current valid values are:<br /><ul><li>`free_floating` _(The vehicle can be returned anywhere permitted within the service area - note that this field is subject to rules in `geofencing_zones.json` if defined.)_</li><li>`roundtrip_station` _(The vehicle must be returned to the initial rental station. Cannot be defined in combination with `free_floating`.)_</li><li>`any_station` _(The vehicle must be returned to any station within the service area - note that a specific station can be defined in [free_bike_status.json](#free_bike_status.json) using `home_station`. Cannot be defined in combination with `roundtrip_station`.)_
\- `vehicle_assets`<br/>*(added in v2.3-RC)*| OPTIONAL | Object | An object where each key defines one of the items listed below.
&emsp;&emsp;\- `icon_url`<br/>*(added in v2.3-RC)*| Conditionally REQUIRED | URL | REQUIRED if `vehicle_assets` is defined. A fully qualified URL pointing to the location of a graphic icon file that MAY be used to represent this vehicle type on maps and in other applications. File MUST be in SVG V1.1 format and MUST be either square or round.
&emsp;&emsp;\- `icon_url_dark`<br/>*(added in v2.3-RC)*| OPTIONAL | URL | A fully qualified URL pointing to the location of a graphic icon file to be used to represent this vehicle type when in dark mode on maps and in other applications. File MUST be in SVG V1.1 format and MUST be either square or round.
&emsp;&emsp;\- `icon_last_modified`<br/>*(added in v2.3-RC)*| Conditionally REQUIRED | Date | REQUIRED if `icon_url` and/or `icon_url_dark` is defined. Date that indicates the last time any included vehicle icon images were modified or updated. MUST be in the format YYYY-MM-DD.
\- `default_pricing_plan_id`<br/>*(added in v2.3-RC)*| Conditionally REQUIRED | ID | REQUIRED if both `system_pricing_plans.json` and `vehicle_types.json` are defined. A `plan_id` as defined in `system_pricing_plans.json` that identifies a default pricing plan for this vehicle to be used by trip planning applications for purposes of calculating the cost of a single trip using this vehicle type. This default pricing plan is superseded by `pricing_plan_id` when it is defined in `free_bike_status.json` Publishers SHOULD define `default_pricing_plan_id` first and then override it using `pricing_plan_id` in `free_bike_status.json` when necessary.
\- `pricing_plan_ids`<br/>*(added in v2.3-RC)* | OPTIONAL | Array | Array of all pricing plan IDs as defined in `system_pricing_plans.json` that are applied to this vehicle type. <br /><br />This array SHOULD be published when there are multiple pricing plans defined in `system_pricing_plans.json` that apply to a single vehicle type.


##### Example:

```jsonc
Expand All @@ -441,6 +443,7 @@ Field Name | REQUIRED | Type | Defines
"form_factor": "bicycle",
"propulsion_type": "human",
"name": "Example Basic Bike",
"wheel_count": 2,
"default_reserve_time": 30,
"return_type": [
"any_station",
Expand All @@ -458,11 +461,36 @@ Field Name | REQUIRED | Type | Defines
"bike_plan_3"
]
},
{
"vehicle_type_id": "cargo123",
"form_factor": "cargo_bicycle",
"propulsion_type": "human",
"name": "Example Cargo Bike",
"wheel_count": 3,
"default_reserve_time": 30,
"return_type": [
"roundtrip_station"
],
"vehicle_assets": {
"icon_url": "https://www.example.com/assets/icon_cargobicycle.svg",
"icon_url_dark": "https://www.example.com/assets/icon_cargobicycle_dark.svg",
"icon_last_modified": "2021-06-15"
},
"default_pricing_plan": "cargo_plan_1",
"pricing_plans": [
"cargo_plan_1",
"cargo_plan_2",
"cargo_plan_3"
]
},
{
"vehicle_type_id": "def456",
"form_factor": "scooter",
"form_factor": "scooter_standing",
"propulsion_type": "electric",
"name": "Example E-scooter V2",
"wheel_count": 2,
"max_permitted_speed": 25,
"rated_power": 350,
"default_reserve_time": 30,
"max_range_meters": 12345,
"return_type": [
Expand All @@ -480,8 +508,9 @@ Field Name | REQUIRED | Type | Defines
"form_factor": "car",
"propulsion_type": "combustion",
"name": "Four-door Sedan",
"wheel_count": 4,
"default_reserve_time": 0,
"max_range_meters": 523992.0,
"max_range_meters": 523992,
"return_type": [
"roundtrip_station"
],
Expand Down

0 comments on commit 09a1a19

Please sign in to comment.