# General Bikeshare Feed Specification (GBFS) This document explains the types of files and data that comprise the General Bikeshare Feed Specification (GBFS) and defines the fields used in those files. # Reference version This documentation refers to **v2.3**.
For past and upcoming versions see the [README](https://github.com/NABSA/gbfs#current-version-recommended). ## Terminology The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119](https://tools.ietf.org/html/rfc2119), [BCP 14](https://tools.ietf.org/html/bcp14) and [RFC8174](https://tools.ietf.org/html/rfc8174) when, and only when, they appear in all capitals, as shown here. ## Table of Contents * [Introduction](#introduction) * [Term Definitions](#term-definitions) * [Files](#files) * [Accessibility](#accessibility) * [File Requirements](#file-requirements) * [Licensing](#licensing) * [Field Types](#field-types) * [Files](#files) * [gbfs.json](#gbfsjson) * [gbfs_versions.json](#gbfs_versionsjson) *(added in v1.1)* * [system_information.json](#system_informationjson) * [vehicle_types.json](#vehicle_typesjson) *(added in v2.1)* * [station_information.json](#station_informationjson) * [station_status.json](#station_statusjson) * [free_bike_status.json](#free_bike_statusjson) * [system_hours.json](#system_hoursjson) * [system_calendar.json](#system_calendarjson) * [system_regions.json](#system_regionsjson) * [system_pricing_plans.json](#system_pricing_plansjson) * [system_alerts.json](#system_alertsjson) * [geofencing_zones.json](#geofencing_zonesjson) *(added in v2.1)* * [Deep Links - Analytics and Examples](#deep-links) *(added in v1.1)* ## Introduction This specification has been designed with the following concepts in mind: * Provide the status of the system at this moment * Do not provide information whose primary purpose is historical The specification supports real-time travel advice in GBFS-consuming applications. ## Term Definitions This section defines terms that are used throughout this document. * JSON - (JavaScript Object Notation) is a lightweight format for storing and transporting data. This document uses many terms defined by the JSON standard, including field, array, and object. (https://www.w3schools.com/js/js_json_datatypes.asp) * Field - In JSON, a name/value pair consists of a field name (in double quotes), followed by a colon, followed by a value. (https://www.w3schools.com/js/js_json_syntax.asp) * GeoJSON - GeoJSON is a format for encoding a variety of geographic data structures. (https://geojson.org/) * REQUIRED - The field MUST be included in the dataset, and a value MUST be provided in that field for each record. * OPTIONAL - The field MAY be omitted from the dataset. If an OPTIONAL column is included, some of the entries in that field MAY be empty strings. An omitted field is equivalent to a field that is empty. * Conditionally REQUIRED - The field or file is REQUIRED under certain conditions, which are outlined in the field or file description. Outside of these conditions, this field or file is OPTIONAL. ## Files File Name | REQUIRED | Defines ---|---|--- gbfs.json | Yes
*(as of v2.0)* | Auto-discovery file that links to all of the other files published by the system. gbfs_versions.json
*(added in v1.1)* | OPTIONAL | Lists all feed endpoints published according to versions of the GBFS documentation. system_information.json | Yes | Details including system operator, system location, year implemented, URL, contact info, time zone. vehicle_types.json
*(added in v2.1)* | 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 `free_bike_status.json` file. If this file is not included, then all vehicles in the feed are assumed to be non-motorized bicycles. station_information.json | Conditionally REQUIRED | List of all stations, their capacities and locations. REQUIRED of systems utilizing docks. station_status.json | Conditionally REQUIRED | Number of available vehicles and docks at each station and station availability. REQUIRED of systems utilizing docks. free_bike_status.json | Conditionally REQUIRED | *(as of v2.1)* Describes all vehicles that are not currently in active rental. REQUIRED for free floating (dockless) vehicles. OPTIONAL for station based (docked) vehicles. Vehicles that are part of an active rental MUST NOT appear in this feed. system_hours.json | OPTIONAL | Hours of operation for the system. system_calendar.json | OPTIONAL | Dates of operation for the system. system_regions.json | OPTIONAL | Regions the system is broken up into. system_pricing_plans.json | OPTIONAL | System pricing scheme. system_alerts.json | OPTIONAL | Current system alerts. geofencing_zones.json
*(added in v2.1)* | OPTIONAL | Geofencing zones and their associated rules and attributes. ## Accessibility Datasets SHOULD be published at an easily accessible, public, permanent URL. (for example, https://www.example.com/gbfs/v3/gbfs.json). The URL SHOULD be directly available without requiring login to access the file to facilitate download by consuming software applications. To be compliant with GBFS, all systems MUST have an entry in the [systems.csv](https://github.com/NABSA/gbfs/blob/master/systems.csv) file. ### Feed Availability Automated tools for application performance monitoring SHOULD be used to ensure feed availability. Producers SHOULD provide a technical contact who can respond to feed outages in the `feed_contact_email` field in the `system_information.json` file. ### Seasonal Shutdowns, Disruptions of Service Feeds SHOULD continue to be published during seasonal or temporary shutdowns. Feed URLs SHOULD NOT return a 404. An empty bikes array SHOULD be returned by `free_bike_status.json`. Stations in `station_status.json` SHOULD be set to `is_renting:false`, `is_returning:false` and `is_installed:false` where applicable. Seasonal shutdown dates SHOULD be reflected in `system_calendar.json`. Announcements for disruptions of service, including disabled stations or temporary closures of stations or systems, SHOULD be made in `system_alerts.json`. ## File Requirements * All files SHOULD be valid JSON. * All files in the spec MAY be published at a URL path or with an alternate name (for example, `station_info` instead of `station_information.json`) *(as of v2.0)*. * All data SHOULD be UTF-8 encoded. * Line breaks SHOULD be represented by unix newline characters only (\n). * Pagination is not supported. ### File Distribution * Files are distributed as individual HTTP endpoints. * REQUIRED files MUST NOT 404. They MUST return a properly formatted JSON file as defined in [Output Format](#output-format). * OPTIONAL files MAY 404. A 404 of an OPTIONAL file SHOULD NOT be considered an error. ### Version Endpoints The version of the GBFS specification to which a feed conforms is declared in the `version` field in all files. See [Output Format](#output-format). All endpoints within a data set SHOULD conform to the same MAJOR or MINOR version. Mixing of versions within data sets is NOT RECOMMENDED.
GBFS documentation will include a list of current and past supported MAJOR and MINOR versions. Supported versions SHALL NOT span more than two MAJOR versions. Past versions with _Supported_ status MAY be patched to correct bugs or vulnerabilities, but new features will not be introduced. Past versions with _Deprecated_ status will not be patched, and their use SHOULD be discontinued. Producers SHOULD continue to maintain existing feeds while they have _Supported_ status. GBFS producers SHOULD provide endpoints that conform to the current MAJOR version release within 180 days of a new MAJOR version release. It is not necessary to support more than one MINOR release of the same MAJOR release group, because MINOR releases are backwards-compatible. See [Specification Versioning](https://github.com/NABSA/gbfs/blob/master/README.md#specification-versioning). ### Auto-Discovery Publishers SHOULD implement auto-discovery of GBFS feeds by linking to the location of the `gbfs.json` auto-discovery endpoint. * The location of the auto-discovery file SHOULD be provided in the HTML area of the shared mobility landing page hosted at the URL specified in the `url` field of the `system_information.json` file. * This is referenced via a _link_ tag with the following format: * `` * References: * https://microformats.org/wiki/existing-rel-values * https://microformats.org/wiki/rel-faq#How_is_rel_used * A shared mobility landing page MAY contain links to auto-discovery files for multiple systems. ### Localization * Each set of data files SHOULD be distributed in a single language as defined in `system_information.json`. * A system that wants to publish feeds in multiple languages SHOULD do so by publishing multiple distributions, such as: * `https://www.example.com/data/en/system_information.json` * `https://www.example.com/data/fr/system_information.json` ### Text Fields and Naming Rich text SHOULD NOT be stored in free form text fields. Fields SHOULD NOT contain HTML. All customer-facing text strings (including station names) SHOULD use Mixed Case (not ALL CAPS), following local conventions for capitalization of place names on displays capable of displaying lower case characters. * Examples: * Central Park South * Villiers-sur-Marne * Market Street Abbreviations SHOULD NOT be used for names and other text (for example, St. for Street), unless a location is called by its abbreviated name (for example, “JFK Airport”). Abbreviations may be problematic for accessibility by screen reader software and voice user interfaces. Consuming software can be engineered to reliably convert full words to abbreviations for display, but converting from abbreviations to full words is prone to more risk of error. Names used for stations, virtual stations, and geofenced areas SHOULD be human-readable. Naming conventions used for locations SHOULD consider a variety of use cases including both text and maps. Descriptions SHOULD NOT include information so specific that it could be used in tracking of vehicles or trips. ### Coordinate Precision Feeds SHOULD provide 6 digits (0.000001) of precision for decimal degrees lat/lon coordinates. Decimal places | Degrees | Distance at the Equator ---|---|--- 0|1.0|111 km 1|0.1|11.1 km 2|0.01|1.11 km 3|0.001|111 m 4|0.0001|11.1 m 5|0.00001|1.11 m **6**|**0.000001**|**0.11 m** 7|0.0000001|1.11 cm ### Data Latency The data returned by the near-realtime endpoints `station_status.json` and `free_bike_status.json` SHOULD be as close to realtime as possible, but in no case should it be more than 5 minutes out-of-date. Appropriate values SHOULD be set using the `ttl` property for each endpoint based on how often the data in feeds are refreshed or updated. For near-realtime endpoints where the data should always be refreshed, the `ttl` value SHOULD be `0`. The`last_updated` timestamp represents the publisher's knowledge of the current state of the system at that point in time. The `last_reported` timestamp represents the last time a station or vehicle reported its status to the operator's backend. ## Licensing It is RECOMMENDED that all GBFS data sets be offered under an open data license. Open data licenses allow consumers to freely use, modify, and share GBFS data for any purpose in perpetuity. Licensing of GBFS data provides certainty to GBFS consumers, allowing them to integrate GBFS data into their work. All GBFS data sets SHOULD specify a license using the `license_id` field with an [SPDX identifier](https://spdx.org/licenses/) or by using the `license_url` field with a URL pointing to a custom license in `system_information.json`. See the GBFS repo for a [comparison of a subset of standard licenses](https://github.com/NABSA/gbfs/blob/master/data-licenses.md). ## Field Types * Array - A JSON element consisting of an ordered sequence of zero or more values. * Boolean - One of two possible values, `true`or `false`. Boolean values MUST be JSON booleans, not strings (meaning `true` or `false`, not `"true"` or `"false"`). *(as of v2.0)* * Country code - Country code following the [ISO 3166-1 alpha-2 notation](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2). * Date - A date in the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) Complete Date Extended Format: YYYY-MM-DD . Example: `2019-09-13` for September 13th, 2019. * Datetime *(added in v2.3)*- Combination of a date and a time following [ISO 8601 notation](https://www.iso.org/iso-8601-date-and-time-format.html). Attributes : [year](https://docs.python.org/3/library/datetime.html#datetime.datetime.year), [month](https://docs.python.org/3/library/datetime.html#datetime.datetime.month), [day](https://docs.python.org/3/library/datetime.html#datetime.datetime.day), [hour](https://docs.python.org/3/library/datetime.html#datetime.datetime.hour), [minute](https://docs.python.org/3/library/datetime.html#datetime.datetime.minute), [second](https://docs.python.org/3/library/datetime.html#datetime.datetime.second), and timezone. * Email - An email address. Example: `example@example.com` * Enum (Enumerable values) - An option from a set of predefined constants in the "Defines" column. Enum values SHOULD be lowercase. Example: The `rental_methods` field contains values `creditcard`, `paypass`, etc... * Float *(added in v2.1)* - A 32-bit floating point number. * GeoJSON FeatureCollection - A FeatureCollection as described by the IETF RFC 7946 https://tools.ietf.org/html/rfc7946#section-3.3. * GeoJSON MultiPolygon - A Geometry Object as described by the IETF RFC https://tools.ietf.org/html/rfc7946#section-3.1.7. * ID - Should be represented as a string that identifies that particular entity. An ID: * MUST be unique within like fields (for example, `station_id` MUST be unique among stations). * Does not have to be globally unique, unless otherwise specified. * MUST NOT contain spaces. * MUST be persistent for a given entity (station, plan, etc). An exception is floating bike `bike_id`, which MUST NOT be persistent for privacy reasons (see `free_bike_status.json`). *(as of v2.0)* * Language - An IETF BCP 47 language code. For an introduction to IETF BCP 47, refer to https://www.rfc-editor.org/rfc/bcp/bcp47.txt and https://www.w3.org/International/articles/language-tags/. Examples: `en` for English, `en-US` for American English, or `de` for German. * Latitude - WGS84 latitude in decimal degrees. The value MUST be greater than or equal to -90.0 and less than or equal to 90.0. Example: `41.890169` for the Colosseum in Rome. * Longitude - WGS84 longitude in decimal degrees. The value MUST be greater than or equal to -180.0 and less than or equal to 180.0. Example: `12.492269` for the Colosseum in Rome. * Non-negative Float - A 32-bit floating point number greater than or equal to 0. * Non-negative Integer - An integer greater than or equal to 0. * Object - A JSON element consisting of key-value pairs (fields). * String - Can only contain text. Strings MUST NOT contain any formatting codes (including HTML) other than newlines. * Time - Service time in the HH:MM:SS format for the time zone indicated in `system_information.json` (00:00:00 - 47:59:59). Time can stretch up to one additional day in the future to accommodate situations where, for example, a system was open from 11:30pm - 11pm the next day (23:30:00-47:00:00). * Timestamp - Timestamp fields MUST be represented as integers in POSIX time (representing the number of seconds since January 1st 1970 00:00:00 UTC). * Timezone - TZ timezone from the https://www.iana.org/time-zones. Timezone names never contain the space character but MAY contain an underscore. Refer to https://en.wikipedia.org/wiki/List_of_tz_zones for a list of valid values. Example: `Asia/Tokyo`, `America/Los_Angeles` or `Africa/Cairo`. * URI *(added in v1.1)* - A fully qualified URI that includes the scheme (for example, `com.example.android://`). Any special characters in the URI MUST be correctly escaped. See the following https://www.w3.org/Addressing/URL/4_URI_Recommentations.html for a description of how to create fully qualified URI values. Note that URIs MAY be URLs. * URL - A fully qualified URL that includes `http://` or `https://`. Any special characters in the URL MUST be correctly escaped. See the following https://www.w3.org/Addressing/URL/4_URI_Recommentations.html for a description of how to create fully qualified URL values. ### Extensions Outside of the Specification To accommodate the needs of feed producers and consumers prior to the adoption of a change, additional fields can be added to feeds even if these fields are not part of the official specification. Custom extensions that may provide value to the GBFS community and align with the [GBFS Guiding Principles](https://github.com/NABSA/gbfs/blob/master/README.md#guiding-principles) SHOULD be proposed for inclusion in the specification through the change process. Extreme caution is advised to avoid introducing extensions which may be used to track the movements of vehicles or their users. Field names of extensions SHOULD be prefixed with an underscore ( _) character. It is strongly RECOMMENDED that these additional fields be documented on the [wiki](https://github.com/NABSA/gbfs/wiki) page of the GBFS repository in this format: Submitted by | Field Name | File Name | Defines ---|---|---|--- Publisher's name|_field_name|Name of GBFS endpoint where field is used|Description of purpose of use ## JSON Files ### Output Format Every JSON file presented in this specification contains the same common header information at the top level of the JSON response object: Field Name | REQUIRED | Type | Defines ---|---|---|--- `last_updated` | Yes | Timestamp | Indicates the last time data in the feed was updated. This timestamp represents the publisher's knowledge of the current state of the system at this point in time. `ttl` | Yes | Non-negative integer | Number of seconds before the data in the feed will be updated again (0 if the data should always be refreshed). `version`
*(added in v1.1)* | Yes | String | GBFS version number to which the feed conforms, according to the versioning framework. `data` | Yes | Object | Response data in the form of name:value pairs. **Example:** ```json { "last_updated": 1640887163, "ttl": 3600, "version": "2.3", "data": { "name": "Example Bike Rental", "system_id": "example_cityname", "timezone": "America/Chicago", "language": "en" } } ``` ### gbfs.json The `gbfs.json` discovery file SHOULD represent a single system or geographic area in which vehicles are operated. The location (URL) of the `gbfs.json` file SHOULD be made available to the public using the specification’s [auto-discovery](#auto-discovery) function.
The following fields are all attributes within the main `data` object for this feed. Field Name | REQUIRED | Type | Defines ---|---|---|--- `language` | Yes | Language | The language that will be used throughout the rest of the files. It MUST match the value in the [system_information.json](#system_informationjson) file. \- `feeds` | Yes | Array | An array of all of the feeds that are published by this auto-discovery file. Each element in the array is an object with the keys below.  \- `name` | Yes | String | Key identifying the type of feed this is. The key MUST be the base file name defined in the spec for the corresponding feed type (`system_information` for `system_information.json` file, `station_information` for `station_information.json` file).  \- `url` | Yes | URL | URL for the feed. Note that the actual feed endpoints (urls) may not be defined in the `file_name.json` format. For example, a valid feed endpoint could end with `station_info` instead of `station_information.json`. **Example:** ```json { "last_updated": 1640887163, "ttl": 0, "version": "2.3", "data": { "en": { "feeds": [ { "name": "system_information", "url": "https://www.example.com/gbfs/1/en/system_information" }, { "name": "station_information", "url": "https://www.example.com/gbfs/1/en/station_information" } ] }, "fr" : { "feeds": [ { "name": "system_information", "url": "https://www.example.com/gbfs/1/fr/system_information" }, { "name": "station_information", "url": "https://www.example.com/gbfs/1/fr/station_information" } ] } } } ``` ### gbfs_versions.json *(added in v1.1)* Each expression of a GBFS feed describes all of the versions that are available. The following fields are all attributes within the main `data` object for this feed. Field Name | REQUIRED | Type | Defines ---|---|---|--- `versions` | Yes | Array | 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 | The semantic version of the feed in the form `X.Y`. \- `url` | Yes | URL | URL of the corresponding gbfs.json endpoint. **Example:** ```json { "last_updated": 1640887163, "ttl": 0, "version": "2.3", "data": { "versions": [ { "version": "2.0", "url": "https://www.example.com/gbfs/2/gbfs" }, { "version": "2.3", "url": "https://www.example.com/gbfs/3/gbfs" } ] } } ``` ### system_information.json The following fields are all attributes within the main `data` object for this feed. Field Name | REQUIRED | Type | Defines ---|---|---|--- `system_id` | Yes | ID | This is a globally unique identifier for the vehicle share system. It is up to the publisher of the feed to guarantee uniqueness and MUST be checked against existing `system_id` fields in [systems.csv](https://github.com/NABSA/gbfs/blob/master/systems.csv) to ensure this. This value is intended to remain the same over the life of the system.

Each distinct system or geographic area in which vehicles are operated SHOULD have its own `system_id`. System IDs SHOULD be recognizable as belonging to a particular system - for example, `bcycle_austin` or `biketown_pdx` - as opposed to random strings. `language` | Yes | Language | The language that will be used throughout the rest of the files. It MUST match the value in the [gbfs.json](#gbfsjson) file. `name` | Yes | String | Name of the system to be displayed to customers. `short_name` | OPTIONAL | String | OPTIONAL abbreviation for a system. `operator` | OPTIONAL | String | Name of the system operator. `url` | OPTIONAL | URL | The URL of the vehicle share system. `purchase_url` | OPTIONAL | URL | URL where a customer can purchase a membership. `start_date` | OPTIONAL | Date | Date that the system began operations. `phone_number` | OPTIONAL | Phone Number | This OPTIONAL field SHOULD contain a single voice telephone number for the specified system’s customer service department. It can and SHOULD contain punctuation marks to group the digits of the number. Dialable text (for example, Capital Bikeshare’s "877-430-BIKE") is permitted, but the field MUST NOT contain any other descriptive text. `email` | OPTIONAL | Email | This OPTIONAL field SHOULD contain a single contact email address actively monitored by the operator’s customer service department. This email address SHOULD be a direct contact point where riders can reach a customer service representative. `feed_contact_email`
*(added in v1.1)* | OPTIONAL | Email | This OPTIONAL field SHOULD contain a single contact email for feed consumers to report technical issues with the feed. `timezone` | Yes | Timezone | The time zone where the system is located. `license_url` | OPTIONAL | URL | 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) `brand_assets`
*(added in v2.3)* | OPTIONAL | Object | An object where each key defines one of the items listed below. \- `brand_last_modified`
*(added in v2.3)* | Conditionally REQUIRED | Date | REQUIRED if `brand_assets` object is defined. Date that indicates the last time any included brand assets were updated or modified. \- `brand_terms_url`
*(added in v2.3)* | OPTIONAL | URL | A fully qualified URL pointing to the location of a page that defines the license terms of brand icons, colors, or other trademark information. This field MUST NOT take the place of `license_url` or `license_id`. \- `brand_image_url`
*(added in v2.3)* | Conditionally REQUIRED | URL | REQUIRED if `brand_assets` object is defined. A fully qualified URL pointing to the location of a graphic file representing the brand for the service. File MUST be in SVG V1.1 format and MUST be either square or round. \- `brand_image_url_dark`
*(added in v2.3)* | OPTIONAL | URL | A fully qualified URL pointing to the location of a graphic file representing the brand for the service for use in dark mode applications. File MUST be in SVG V1.1 format and MUST be either square or round. \- `color`
*(added in v2.3)* | OPTIONAL | String | Color used to represent the brand for the service expressed as a 6 digit hexadecimal color code in the form #000000. `terms_url`
*(added in v2.3)* | OPTIONAL | URL | A fully qualified URL pointing to the terms of service (also often called "terms of use" or "terms and conditions") for the service. `terms_last_updated`
*(added in v2.3)* |Conditionally REQUIRED | Date | REQUIRED if `terms_url` is defined. The date that the terms of service provided at `terms_url` were last updated. `privacy_url`
*(added in v2.3)*| OPTIONAL | URL | A fully qualified URL pointing to the privacy policy for the service. `privacy_last_updated`
*(added in v2.3)* |Conditionally REQUIRED | Date | REQUIRED if `privacy_url` is defined. The date that the privacy policy provided at `privacy_url` was last updated. `rental_apps`
*(added in v1.1)* | OPTIONAL | Object | Contains rental app information in the `android` and `ios` JSON objects. \- `android`
*(added in v1.1)* | OPTIONAL | Object | Contains rental app download and app discovery information for the Android platform in the `store_uri` and `discovery_uri` fields. See [examples](#examples) of how to use these fields and [supported analytics](#analytics).  - `store_uri`
*(added in v1.1)* | Conditionally REQUIRED | URI | URI where the rental Android app can be downloaded from. Typically this will be a URI to an app store, such as Google Play. If the URI points to an app store, the URI SHOULD follow Android best practices so the viewing app can directly open the URI to the native app store app instead of a website.

REQUIRED if a `rental_uris`.`android` field is populated.

See the [Analytics](#analytics) section for how viewing apps can report the origin of the deep link to rental apps.

Example value: `https://play.google.com/store/apps/details?id=com.example.android`  - `discovery_uri`
*(added in v1.1)* | Conditionally REQUIRED | URI | URI that can be used to discover if the rental Android app is installed on the device (for example, using [`PackageManager.queryIntentActivities()`](https://developer.android.com/reference/android/content/pm/PackageManager.html#queryIntentActivities)). This intent is used by viewing apps to prioritize rental apps for a particular user based on whether they already have a particular rental app installed.

REQUIRED if a `rental_uris`.`android` field is populated.

Example value: `com.example.android://` \- `ios`
*(added in v1.1)* | OPTIONAL | Object | Contains rental information for the iOS platform in the `store_uri` and `discovery_uri` fields. See [examples](#examples) of how to use these fields and [supported analytics](#analytics).  - `store_uri`
*(added in v1.1)* | Conditionally REQUIRED | URI | URI where the rental iOS app can be downloaded from. Typically this will be a URI to an app store, such as the Apple App Store. If the URI points to an app store, the URI SHOULD follow iOS best practices so the viewing app can directly open the URI to the native app store app instead of a website.

REQUIRED if a `rental_uris`.`ios` field is populated.

See the [Analytics](#analytics) section for how viewing apps can report the origin of the deep link to rental apps.

Example value: `https://apps.apple.com/app/apple-store/id123456789`  - `discovery_uri`
*(added in v1.1)* | Conditionally REQUIRED | URI | URI that can be used to discover if the rental iOS app is installed on the device (for example, using [`UIApplication canOpenURL:`](https://developer.apple.com/documentation/uikit/uiapplication/1622952-canopenurl?language=objc)). This intent is used by viewing apps to prioritize rental apps for a particular user based on whether they already have a particular rental app installed.

REQUIRED if a `rental_uris`.`ios` field is populated.

Example value: `com.example.ios://` **Example:** ```json { "last_updated": 1640887163, "ttl": 1800, "version": "2.3", "data": { "system_id": "example_cityname", "language": "en", "name": "Example Bike Rental", "short_name": "Example Bike", "operator": "Example Sharing, Inc", "url": "https://www.example.com", "purchase_url": "https://www.example.com", "start_date": "2010-06-10", "phone_number": "1-800-555-1234", "email": "customerservice@example.com", "feed_contact_email": "datafeed@example.com", "timezone": "America/Chicago", "license_url": "https://www.example.com/data-license.html", "terms_url": "https://www.example.com/terms", "terms_last_updated": "2021-06-21", "privacy_url": "https://www.example.com/privacy-policy", "privacy_last_updated": "2019-01-13", "rental_apps": { "android": { "discovery_uri": "com.example.android://", "store_uri": "https://play.google.com/store/apps/details?id=com.example.android" }, "ios": { "store_uri": "https://apps.apple.com/app/apple-store/id123456789", "discovery_uri": "com.example.ios://" } }, "brand_assets": { "brand_last_modified": "2021-06-15", "brand_image_url": "https://www.example.com/assets/brand_image.svg", "brand_image_url_dark": "https://www.example.com/assets/brand_image_dark.svg", "color": "#C2D32C", "brand_terms_url": "https://www.example.com/assets/brand.pdf" } } } ``` ### vehicle_types.json *(added in v2.1)* REQUIRED of systems that include information about vehicle types in the `free_bike_status.json` file. If this file is not included, then all vehicles in the feed are assumed to be non-motorized bicycles. This file SHOULD be published by systems offering multiple vehicle types for rental, for example pedal bikes and ebikes.
The following fields are all attributes within the main `data` object for this feed. 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.

Current valid values are:
\- `rider_capacity`
*(added in v2.3)* | OPTIONAL | Non-negative integer | The number of riders (driver included) the vehicle can legally accommodate. \- `cargo_volume_capacity`
*(added in v2.3)* | OPTIONAL | Non-negative integer | Cargo volume available in the vehicle, expressed in liters. For cars, it corresponds to the space between the boot floor, including the storage under the hatch, to the rear shelf in the trunk. \- `cargo_load_capacity`
*(added in v2.3)* | OPTIONAL | Non-negative integer | The capacity of the vehicle cargo space (excluding passengers), expressed in kilograms. \- `propulsion_type` | Yes | Enum | The primary propulsion type of the vehicle.

Current valid values are:
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/main/general-information.md#propulsion-types). \- `eco_label`
*(added in v2.3)* | OPTIONAL | Array | Vehicle air quality certificate. Official anti-pollution certificate, based on the information on the vehicle's registration certificate, attesting to its level of pollutant emissions based on a defined standard. In Europe, for example, it is the European emission standard. The aim of this measure is to encourage the use of the least polluting vehicles by allowing them to drive during pollution peaks or in low emission zones.

Each element in the array is an object with the keys below.  \-  `country_code`
*(added in v2.3)* | Conditionally REQUIRED | Country code | REQUIRED if `eco_label` is defined. Country where the `eco_sticker` applies.  \-  `eco_sticker`
*(added in v2.3)* | Conditionally REQUIRED | String | REQUIRED if `eco_label` is defined. Name of the eco label. The name must be written in lowercase, separated by an underscore.

Example of `eco_sticker` in Europe : \- `max_range_meters` | Conditionally REQUIRED | Non-negative float | REQUIRED if the vehicle has a motor (as indicated by having a value other than `human` in the `propulsion_type` field). 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. \- `vehicle_accessories`
*(added in v2.3)* | OPTIONAL | Array | Description of accessories available in the vehicle. These accessories are part of the vehicle and are not supposed to change frequently. Current valid values are: \- `g_CO2_km`
*(added in v2.3)* | OPTIONAL | Non-negative integer | Maximum quantity of CO2, in grams, emitted per kilometer, according to the [WLTP](https://en.wikipedia.org/wiki/Worldwide_Harmonised_Light_Vehicles_Test_Procedure). \- `vehicle_image`
*(added in v2.3)* | OPTIONAL | URL | URL to an image that would assist the user in identifying the vehicle (for example, an image of the vehicle or a logo).
Allowed formats: JPEG, PNG. | \- `make`
*(added in v2.3)*| OPTIONAL| String| The name of the vehicle manufacturer.

Example: | \- `model`
*(added in v2.3)*| OPTIONAL| String| The name of the vehicle model.

Example | \- `color`
*(added in v2.3)*| OPTIONAL| String| The color of the vehicle.

All words must be in lower case, without special characters, quotation marks, hyphens, underscores, commas, or dots. Spaces are allowed in case of a compound name.

Example \- `wheel_count`
*(added in v2.3)* | OPTIONAL | Non-negative Integer | Number of wheels this vehicle type has. \- `max_permitted_speed`
*(added in v2.3)* | 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`
*(added in v2.3)* | OPTIONAL | Non-negative Integer | The rated power of the motor for this vehicle type in watts. \- `default_reserve_time`
*(added in v2.3)* | 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 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_constraint`
*(as of v2.3)*| OPTIONAL | Enum | The conditions for returning the vehicle at the end of the rental.

Current valid values are: