This document explains the types of files and data that comprise the General Bikeshare Feed Specification (GBFS) and defines the fields used in all of those files.
This documentation refers to version 1.1. For past and upcoming versions see the README.
- Revision History
- Introduction
- Files
- File Requirements
- Field Definitions
- Deep Links - Analytics and Examples (added in v1.1)
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
Historical data, including station details and ride data is to be provided by a more compact specification designed specifically for such archival purposes. The data in the specification contained in this document is intended for consumption by clients intending to provide real-time (or semi-real-time) transit advice and is designed as such.
The version of the GBFS specification to which a feed conforms is declared in the version field in all files. See Output Format.
GBFS Best Practice defines that:
GBFS producers should provide endpoints that conform to both the current specification long term support (LTS) branch as well as the latest release branch within at least 3 months of a new spec MAJOR or MINOR 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
GBFS consumers should, at a minumum, support the current LTS branch. It highly recommended that GBFS consumers support later releases.
Default GBFS feed URLs, e.g. https://www.example.com/data/gbfs.json or https://www.example.com/data/fr/system_information.json must direct consumers to the feed that conforms to the current LTS documentation branch.
This specification defines the following files along with their associated content:
| 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 (added in v1.1) |
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 |
| 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. |
| system_hours.json | Optional | Describes the hours of operation for the system |
| system_calendar.json | Optional | Describes the days of operation for the system |
| system_regions.json | Optional | Describes the regions the system is broken up into |
| system_pricing_plans.json | Optional | Describes the system pricing |
| system_alerts.json | Optional | Describes current system alerts |
- All files should be valid JSON
- All data should be UTF-8 encoded
- Line breaks should be represented by unix newline characters only (\n)
- All URIs must be a fully qualified URI that includes the scheme (e.g., http:// or https://), and any special characters in the URI must be correctly escaped. See http://www.w3.org/Addressing/URL/4_URI_Recommentations.html for a description of how to create fully qualified URI values.
- This specification does not dictate the implementation details around the distribution of the JSON data files
- If the publisher intends to distribute as individual HTTP endpoints then:
- Required files must not 404 - they should return a properly formatted JSON file as defined in Output Format
- Optional files may 404 - a 404 of an optional file should not be considered an error, it just indicates that the publisher has chosen not to publish this data
- Auto-Discovery:
- This specification supports auto-discovery
- The location of the auto-discovery file will be provided in the HTML area of the bikeshare landing page hosted at the URL specified in the url field of the system_infomation.json file
- This is referenced via a link tag with the following format:
<link rel="gbfs" type="application/json" href="https://www.example.com/data/gbfs.json" />
- Reference:
- 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
- Time stamp fields must be represented as integers in POSIX time (i.e., the number of seconds since January 1st 1970 00:00:00 UTC)
- ID fields in the document should be represented as strings that identify that particular object. They:
- must be unique within like fields (bike_id must be unique among bikes)
- do not have to be globally unique
- must not contain spaces
- should be persistent for a given object (station, plan, etc)
- Text fields can only contain text - they must not contain any formatting codes (including HTML) other than newlines
- Enumerable values should be expected to change over time. Values will not be removed, but new valid values may be added as business requirements change and consumers should be designed to handle these changes
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 | Defines |
|---|---|---|
| last_updated | Yes | Integer POSIX timestamp indicating the last time the data in this feed was updated |
| ttl | Yes | Integer representing the number of seconds before the data in this 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 confirms, according to the versioning framework. |
| data | Yes | JSON hash containing the data fields for this response |
Example:
{
"last_updated": 1434054678,
"ttl": 3600,
"version": "1.1",
"data": {
"name": "Citi Bike",
"system_id": "citibike_com"
}
}The following fields are all attributes within the main "data" object for this feed.
| Field Name | Required | Defines |
|---|---|---|
| language | Yes | The language that all of the contained files will be published in. This language must match the value in the system_information file |
| - feeds | Yes | An array of all of the feeds that are published by this auto-discovery file |
| - name | Yes | Key identifying the type of feed this is (e.g. "system_information", "station_information") |
| - url | Yes | Full URL for the feed |
Example:
{
"last_updated": 1434054678,
"ttl": 0,
"version": "1.1",
"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"
}
]
}
}
}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 | 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. |
{
"last_updated": 1434054678,
"ttl": 0,
"version": "1.1",
"data": {
"versions": [
{
"version":"1.0",
"url":"https://www.example.com/gbfs/1/gbfs"
},
{
"version":"1.1",
"url":"https://www.example.com/gbfs/2/gbfs"
}
]
}
}The following fields are all attributes within the main "data" object for this feed.
| Field Name | Required | Defines |
|---|---|---|
| system_id | Yes | ID field - identifier for this bike share system. This should be globally unique (even between different systems) and it is currently up to the publisher of the feed to guarantee uniqueness. In addition, this value is intended to remain the same over the life of the system |
| language | Yes | An IETF language tag indicating the language that will be used throughout the rest of the files. This is a string that defines a single language tag only. See https://tools.ietf.org/html/bcp47 and https://en.wikipedia.org/wiki/IETF_language_tag for details about the format of this tag |
| name | Yes | Full name of the system to be displayed to customers |
| short_name | Optional | Optional abbreviation for a system |
| operator | Optional | Name of the operator of the system |
| url | Optional | The URL of the bike share system. The value must be a fully qualified URL that includes http:// or https://, and any special characters in the URL must be correctly escaped. See http://www.w3.org/Addressing/URL/4_URI_Recommentations.html for a description of how to create fully qualified URL values |
| purchase_url | Optional | A fully qualified URL where a customer can purchase a membership or learn more about purchasing memberships |
| start_date | Optional | String in the form YYYY-MM-DD representing the date that the system began operations |
| phone_number | Optional | A single voice telephone number for the specified system. This field is a string value that presents the telephone number as typical for the system's service area. 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 |
| Optional | A single contact email address for customers to address questions about the system | |
| feed_contact_email (added in v1.1) |
Optional | A single contact email address for consumers of this feed to report technical issues |
| 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) |
| rental_apps (added in v1.1) |
Optional | A JSON object that contains rental app information in the android and ios JSON objects. |
| - android (added in v1.1) |
Optional | A JSON object that contains rental app download and app discovery information for the Android platform in the store_uri and discovery_uri fields. See examples of how to use these fields and supported analytics. |
| - store_uri (added in v1.1) |
Conditionally Required | A 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 such as Google Play, 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. If a rental_uris.android field is populated then this field is required, otherwise it is optional. See the 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.abcrental.android |
| - discovery_uri (added in v1.1) |
Conditionally Required | A URI that can be used to discover if the rental Android app is installed on the device (e.g., using PackageManager.queryIntentActivities()). This intent is used by viewing apps prioritize rental apps for a particular user based on whether they already have a particular rental app installed. This field is required if a rental_uris.android field is populated, otherwise it is optional. Example value: com.abcrental.android:// |
| - ios (added in v1.1) |
Optional | A JSON object that contains rental information for the iOS platform in the store_uri and discovery_uri fields. See examples of how to use these fields and supported analytics. |
| - store_uri (added in v1.1) |
Conditionally Required | A 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 such as the Apple 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. If a rental_uris.ios field is populated then this field is required, otherwise it is optional. See the 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 | A URI that can be used to discover if the rental iOS app is installed on the device (e.g., using UIApplication canOpenURL:). This intent is used by viewing apps prioritize rental apps for a particular user based on whether they already have a particular rental app installed. This field is required if a rental_uris.ios field is populated, otherwise it is optional. Example value: com.abcrental.ios:// |
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.
| 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 Field Definitions above for ID field requirements |
| - name | Yes | Public name of the station |
| - short_name | No | Short name or other type of identifier, as used by the data publisher |
| - lat | Yes | The latitude of station. 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 |
| - lon | Yes | The longitude of station. The field value must be a valid WGS 84 longitude in decimal degrees format. See: http://en.wikipedia.org/wiki/World_Geodetic_System, https://en.wikipedia.org/wiki/Decimal_degrees |
| - address | Optional | Valid street number and name where station is located. This field is intended to be an actual address, not a free form text description (see "cross_street" below) |
| - cross_street | Optional | Cross street of where the station is located. This field is intended to be a descriptive field for human consumption. In cities, this would be a cross street, but could also be a description of a location in a park, etc. |
| - region_id | Optional | ID of the region where station is located (see system_regions.json) |
| - post_code | Optional | Postal code where station is located |
| - rental_methods | Optional | Array of enumerables containing the payment methods accepted at this station. Current valid values (in CAPS) are:
|
| - capacity | Optional | Number of total docking points installed at this station, both available and unavailable |
| - rental_uris (added in v1.1) |
Optional | A JSON object that contains rental URIs for Android, iOS, and web in the android, ios, and web fields. See examples of how to use these fields and supported analytics. |
| - android (added in v1.1) |
Optional | The URI that can be passed to an Android app with an android.intent.action.VIEW Android intent to support Android Deep Links (https://developer.android.com/training/app-links/deep-linking). Please use Android App Links (https://developer.android.com/training/app-links) if possible so viewing apps don’t need to manually manage the redirect of the user to the app store if the user doesn’t have the application installed. This URI should be a deep link specific to this station, and should not be a general rental page that includes information for more than one station. The deep link should take users directly to this station, without any prompts, interstitial pages, or logins. Make sure that users can see this station even if they never previously opened the application. If this field is empty, it means deep linking isn’t supported in the native Android rental app. Note that URIs do not necessarily include the station_id for this station - other identifiers can be used by the rental app within the URI to uniquely identify this station. See the Analytics section for how viewing apps can report the origin of the deep link to rental apps. Android App Links example value: https://www.abc.com/app?sid=1234567890&platform=android Deep Link (without App Links) example value: com.abcrental.android://open.abc.app/app?sid=1234567890 |
| - ios (added in v1.1) |
Optional | The URI that can be used on iOS to launch the rental app for this station. More information on this iOS feature can be found here. Please use iOS Universal Links (https://developer.apple.com/ios/universal-links/) if possible so viewing apps don’t need to manually manage the redirect of the user to the app store if the user doesn’t have the application installed. This URI should be a deep link specific to this station, and should not be a general rental page that includes information for more than one station. The deep link should take users directly to this station, without any prompts, interstitial pages, or logins. Make sure that users can see this station even if they never previously opened the application. If this field is empty, it means deep linking isn’t supported in the native iOS rental app. Note that the URI does not necessarily include the station_id - other identifiers can be used by the rental app within the URL to uniquely identify this station. See the Analytics section for how viewing apps can report the origin of the deep link to rental apps. iOS Universal Links example value: https://www.abc.com/app?sid=1234567890&platform=ios Deep Link (without Universal Links) example value: com.abcrental.ios://open.abc.app/app?sid=1234567890 |
| - web (added in v1.1) |
Optional | A URL that can be used by a web browser to show more information about renting a vehicle at this station. This URL should be a deep link specific to this station, and should not be a general rental page that includes information for more than one station. The deep link should take users directly to this station, without any prompts, interstitial pages, or logins. Make sure that users can see this station even if they never previously opened the application. If this field is empty, it means deep linking isn’t supported for web browsers. Example value: https://www.abc.com/app?sid=1234567890 |
| 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_disabled | Optional | Number of disabled bikes at the station. Vendors who do not want to publicize the number of disabled bikes 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/bikes can be inferred (though not specifically whether the decreased capacity is a broken bike or dock) |
| - num_docks_available | Yes | Number of docks accepting bike returns |
| - 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 backend |
Describes bikes that are not at a station and are not currently in the middle of an active ride.
| Field Name | Required | Defines |
|---|---|---|
| bikes | Yes | Array that contains one object per bike that is currently docked/stopped outside of the system as defined below |
| - bike_id | Yes | Unique identifier of a bike |
| - lat | Yes | Latitude 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 |
| - 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) |
| - rental_uris (added in v1.1) |
Optional | A JSON object that contains rental URIs for Android, iOS, and web in the android, ios, and web fields. See examples of how to use these fields and supported analytics. |
| - android (added in v1.1) |
Optional | The URI that can be passed to an Android app with an android.intent.action.VIEW Android intent to support Android Deep Links (https://developer.android.com/training/app-links/deep-linking). Please use Android App Links (https://developer.android.com/training/app-links) if possible so viewing apps don’t need to manually manage the redirect of the user to the app store if the user doesn’t have the application installed. This URI should be a deep link specific to this bike, and should not be a general rental page that includes information for more than one bike. The deep link should take users directly to this bike, without any prompts, interstitial pages, or logins. Make sure that users can see this bike even if they never previously opened the application. If this field is empty, it means deep linking isn’t supported in the native Android rental app. Note that URIs do not necessarily include the bike_id for this bike - other identifiers can be used by the rental app within the URI to uniquely identify this bike. See the Analytics section for how viewing apps can report the origin of the deep link to rental apps. Android App Links example value: https://www.abc.com/app?sid=1234567890&platform=android Deep Link (without App Links) example value: com.abcrental.android://open.abc.app/app?sid=1234567890 |
| - ios (added in v1.1) |
Optional | The URI that can be used on iOS to launch the rental app for this bike. More information on this iOS feature can be found here: https://developer.apple.com/documentation/uikit/core_app/allowing_apps_and_websites_to_link_to_your_content/communicating_with_other_apps_using_custom_urls?language=objc. Please use iOS Universal Links (https://developer.apple.com/ios/universal-links/) if possible so viewing apps don’t need to manually manage the redirect of the user to the app store if the user doesn’t have the application installed. This URI should be a deep link specific to this bike, and should not be a general rental page that includes information for more than one bike. The deep link should take users directly to this bike, without any prompts, interstitial pages, or logins. Make sure that users can see this bike even if they never previously opened the application. If this field is empty, it means deep linking isn’t supported in the native iOS rental app. Note that the URI does not necessarily include the bike_id - other identifiers can be used by the rental app within the URL to uniquely identify this bike. See the Analytics section for how viewing apps can report the origin of the deep link to rental apps. iOS Universal Links example value: https://www.abc.com/app?sid=1234567890&platform=ios Deep Link (without Universal Links) example value: com.abcrental.ios://open.abc.app/app?sid=1234567890 |
| - web (added in v1.1) |
Optional | A URL that can be used by a web browser to show more information about renting a vehicle at this bike. This URL should be a deep link specific to this bike, and should not be a general rental page that includes information for more than one bike. The deep link should take users directly to this bike, without any prompts, interstitial pages, or logins. Make sure that users can see this bike even if they never previously opened the application. If this field is empty, it means deep linking isn’t supported for web browsers. Example value: https://www.abc.com/app?sid=1234567890 |
Describes the system hours of operation. A JSON array of hours defined as follows:
| Field Name | Required | Defines |
|---|---|---|
| rental_hours | Yes | Array of hour objects as defined below. Can contain a minimum of one object identifying hours for all days of the week or a maximum of fourteen hour objects are allowed (one for each day of the week for each "member" or "nonmember" user type) |
| - user_types | Yes | An array of "member" and "nonmember" values. This indicates that this set of rental hours applies to either members or non-members only. |
| - days | Yes | An array of abbreviations (first 3 letters) of English names of the days of the week that this hour object applies to (i.e. ["mon", "tue"]). Each day can only appear once within all of the hours objects in this feed. |
| - start_time | Yes | Start time for the hours of operation of the system in the time zone indicated in system_information.json (00:00:00 - 23:59:59) |
| - end_time | Yes | End time for the hours of operation of the system in 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 (i.e. 23:30-47:00) |
Example:
{
"last_updated": 1434054678,
"ttl": 0,
"version": "1.1",
"data": {
"rental_hours": [
{
"user_types": [ "member" ],
"days": ["sat", "sun"],
"start_time": "00:00:00",
"end_time": "23:59:59"
},
{
"user_types": [ "nonmember" ],
"days": ["sat", "sun"],
"start_time": "05:00:00",
"end_time": "23:59:59"
},
{
"user_types": [ "member", "nonmember" ],
"days": ["mon", "tue", "wed", "thu", "fri"],
"start_time": "00:00:00",
"end_time": "23:59:59"
}
]
}
}Describes the operating calendar for a system. An array of year objects defined as follows (if start/end year are omitted, then assume the start and end months do not change from year to year).
| Field Name | Required | Defines |
|---|---|---|
| calendars | Yes | Array of year objects describing the system operational calendar. A minimum of one calendar object is required, which could indicate a general calendar, or multiple calendars could be present indicating arbitrary start and end dates |
| - start_month | Yes | Starting month for the system operations (1-12) |
| - start_day | Yes | Starting day for the system operations (1-31) |
| - start_year | Optional | Starting year for the system operations |
| - end_month | Yes | Ending month for the system operations (1-12) |
| - end_day | Yes | Ending day for the system operations (1-31) |
| - end_year | Optional | Ending year for the system operations |
Describe regions for a system that is broken up by geographic or political region. It is defined as a separate feed to allow for additional region metadata (such as shape definitions).
| Field Name | Required | Defines |
|---|---|---|
| regions | Yes | Array of region objects as defined below |
| - region_id | Yes | Unique identifier for the region |
| - name | Yes | Public name for this region |
Describe pricing for the system. This scheme does not currently factor in lost bike fees as it seems outside of the scope of this specification, but they could be added. It is an array of pricing objects defined as follows:
| Field Name | Required | Defines |
|---|---|---|
| plans | Yes | Array of any number of plan objects as defined below: |
| - plan_id | Yes | String - a unique identifier for this plan in the system |
| - url | Optional | String - a fully qualified URL where the customer can learn more about this particular scheme |
| - name | Yes | Name of this pricing scheme |
| - currency | Yes | Currency this pricing is in (ISO 4217 code: http://en.wikipedia.org/wiki/ISO_4217) |
| - price | Yes | Fee for this pricing scheme. This should be in the base unit as defined by the ISO 4217 currency code with the appropriate number of decimal places and omitting the currency symbol. e.g. if the price is in US Dollars the price would be 9.95 |
| - is_taxable | Yes | 1/0 value:
|
| - description | Yes | Text field describing the particular pricing plan in human readable terms. This should include the duration, price, conditions, etc. that the publisher would like users to see. This is intended to be a human-readable description and should not be used for automatic calculations |
This feed is intended to inform customers about changes to the system that do not fall within the normal system operations. For example, system closures due to weather would be listed here, but a system that only operated for part of the year would have that schedule listed in the system_calendar.json feed.
This file is an array of alert objects defined as below. Obsolete alerts should be removed so the client application can safely present to the end user everything present in the feed. The consumer could use the start/end information to determine if this is a past, ongoing or future alert and adjust the presentation accordingly.
| Field Name | Required | Defines |
|---|---|---|
| alerts | Yes | Array - alert objects each indicating a separate system alert as defined below |
| - alert_id | Yes | ID - unique identifier for this alert |
| - type | Yes | Enumerable - valid values are:
|
| - times | Optional | Array of hashes with the keys "start" and "end" indicating when the alert is in effect (e.g. when the system or station is actually closed, or when it is scheduled to be moved). If this array is omitted then the alert should be displayed as long as it is in the feed. |
| - start | Yes | Integer POSIX timestamp - required if container "times" key is present |
| - end | Optional | Integer POSIX timestamp - if there is currently no end time planned for the alert, this key can be omitted indicating that there is no currently scheduled end time for the alert |
| - station_ids | Optional | Array of strings - If this is an alert that affects one or more stations, include their ids, otherwise omit this field. If both station_ids and region_ids are omitted, assume this alert affects the entire system |
| - region_ids | Optional | Array of strings - If this system has regions, and if this alert only affects certain regions, include their ids, otherwise, omit this field. If both station_ids and region_ids are omitted, assume this alert affects the entire system |
| - url | Optional | String - URL where the customer can learn more information about this alert, if there is one |
| - summary | Yes | String - A short summary of this alert to be displayed to the customer |
| - description | Optional | String - Detailed text description of the alert |
| - last_updated | Optional | Integer POSIX timestamp indicating the last time the info for the particular alert was updated |
Deep links to iOS, Android, and web apps are supported via URIs in the system_information.json, station_information.json, and free_bike_status.json files. The following sections describe how analytics can be added to these URIs, as well as some examples.
In all of the rental URI fields, a viewing app can report the origin of a deep link to request to a rental app by appending the client_id (added in v1.1) parameter to the URI along with the domain name for the viewing app.
For example, if Google is the viewing app, it can append:
client_id=google.com
...to the URI field to report that Google is the originator of the deep link request. If the Android URI is:
com.abcrental.android://open.abc.app/stations?id=1234567890
...then the URI used by Google would be: com.abcrental.android://open.abc.app/stations?id=1234567890&client_id=google.com
Other supported parameters include:
ad_id(added in v1.1) - Advertising ID issued to the viewing app (e.g., IFDA on iOS)token(added in v1.1) - A token identifier that was issued by the rental app to the viewing app.
system_information.json
{
"last_updated": 1572447999,
"data": {
"system_id": "1000",
"short_name": "ABC Bike Rental",
"rental_apps": {
"android": {
"discovery_uri": "com.abcrental.android://"
},
"ios": {
"discovery_uri": "com.abcrental.ios://"
}
}
...
station_information.json
"stations": [
{
"station_id": 425,
"name": "Coppertail",
"lat": 27.9563335328521,
"lon": -82.430436084371,
"rental_uris": {
"android": "https://www.abc.com/app?sid=1234567890&platform=android",
"ios": "https://www.abc.com/app?sid=1234567890&platform=ios"
}
},
...
Note that the Android URI and iOS Universal Link URLs don’t necessarily use the same identifier as the station_id.
Example 2 - App Links are not supported on Android and Universal Links are not supported on iOS, but deep links are still supported on Android and iOS:
system_information.json
{
"last_updated": 1572447999,
"data": {
"system_id": "1000",
"short_name": "ABC Bike Rental",
"rental_apps": {
"android": {
"discovery_uri": "com.abcrental.android://"
"store_uri": "https://play.google.com/store/apps/details?id=com.abcrental.android",
},
"ios": {
"store_uri": "https://apps.apple.com/app/apple-store/id123456789",
"discovery_uri": "com.abcrental.ios://"
}
},
...
station_information.json
"stations": [
{
"station_id": 425,
"name": "Coppertail",
"lat": 27.9563335328521,
"lon": -82.430436084371,
"rental_uris": {
"android": "com.abcrental.android://open.abc.app/app?sid=1234567890",
"ios": "com.abcrental.ios://open.abc.app/app?sid=1234567890"
}
},
...
station_information.json
"stations": [
{
"station_id":425,
"name":"Coppertail",
"lat":27.9563335328521,
"lon":-82.430436084371,
"rental_uris": {
"web":"https://www.abc.com/app?sid=1234567890",
}
},
...
Apple Pay, PayPass and other third-party product and service names are trademarks or registered trademarks of their respective owners.
Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 3.0 License.