GBFS v3.0
Voi supports the GBFS v3.0 API.
Of the GBFS files specified in here, Voi supports the following files.
gbfs.jsonvehicle_types.jsonvehicle_status.jsonstation_status.jsonstation_information.jsonsystem_information.jsonsystem_pricing_plans.jsongeofencing_zones.jsonsystem_alerts.json(Not used)system_regions.json(Not used)
Common response
Every JSON file presented in this specification contains the same common header information at the top level of the JSON response object:
| Field Name | type | Defines |
|---|---|---|
last_updated | Integer | POSIX timestamp indicating the last time the data in this feed was updated |
ttl | 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 | String | GBFS version number to which the feed confirms, according to the versioning framework. |
data | JSON | JSON hash containing the data fields for this response |
Authentication
Authentication for GBFS v3.0 uses the same API key method as all other Voi APIs. Include your API key in the X-Access-Token request header. See the MDS 2.0 Authentication section for details.
| Key | Value |
|---|---|
| X-Access-Token | your-api-key |
Legacy Authentication (deprecated)
warning
The previous OAuth 2.0 client_credentials authentication method is deprecated. Existing tokens will continue to work, but credentials will not be renewed upon expiration. Please migrate to the API key method described above.
Auto-discovery
A gbfs.json request.
$ curl --location --request GET https://api.voiapp.io/v1/partner-apis/gbfs/{zoneID}/gbfs.json
-H "X-Access-Token: $API_KEY"
Path parameters
| parameter | description | presence |
|---|---|---|
| zoneID | The zone id for the requested status changes | required |
A gbfs.json response.
{
"data": {
"feeds": [
{
"name": "gbfs_versions",
"url": "https://api.voiapp.io/v1/partner-apis/gbfs/{zoneID}/gbfs_versions.json"
},
{
"name": "system_information",
"url": "https://api.voiapp.io/v1/partner-apis/gbfs/{zoneID}/system_information.json"
},
{
"name": "vehicle_types",
"url": "https://api.voiapp.io/v1/partner-apis/gbfs/{zoneID}/vehicle_types.json"
},
{
"name": "station_information",
"url": "https://api.voiapp.io/v1/partner-apis/gbfs/{zoneID}/station_information.json"
},
{
"name": "station_status",
"url": "https://api.voiapp.io/v1/partner-apis/gbfs/{zoneID}/station_status.json"
},
{
"name": "vehicle_status",
"url": "https://api.voiapp.io/v1/partner-apis/gbfs/{zoneID}/vehicle_status.json"
},
{
"name": "system_regions",
"url": "https://api.voiapp.io/v1/partner-apis/gbfs/{zoneID}/system_regions.json"
},
{
"name": "system_pricing_plans",
"url": "https://api.voiapp.io/v1/partner-apis/gbfs/{zoneID}/system_pricing_plans.json"
},
{
"name": "system_alerts",
"url": "https://api.voiapp.io/v1/partner-apis/gbfs/{zoneID}/system_alerts.json"
},
{
"name": "geofencing_zones",
"url": "https://api.voiapp.io/v1/partner-apis/gbfs/{zoneID}/geofencing_zones.json"
}
]
},
"last_updated": "2025-02-17T12:52:04Z",
"ttl": 3600,
"version": "3.0"
}
gbfs.json is an auto-discovery file that links to all of the other files published by the system.
A successful response contains which GBFS endpoints that the user's role can access.
Response
The following fields are all attributes within the main data object for this feed.
| Field Name | type | Defines |
|---|---|---|
language | String | The language that all of the contained files will be published in. This language must match the value in the system_information file |
feeds | Array | An array of all of the feeds that are published by this auto-discovery file |
name | String | Key identifying the type of feed this is (e.g. "system_information", "station_information") |
url | String | Full URL for the feed |
Vehicle Types
A Vehicle Types request.
$ curl --location --request GET https://api.voiapp.io/v1/partner-apis/gbfs/{zoneID}/vehicle_types.json
-H "X-Access-Token: $API_KEY"
Path parameters
| parameter | description | presence |
|---|---|---|
| zoneID | The zone id for the requested status changes | required |
A vehicle_types.json response.
{
"data": {
"vehicle_types": [
{
"color": "coral",
"default_pricing_plan_id": "scooter-pricing-plan-1",
"default_reserve_time": 10,
"description": [],
"eco_labels": [],
"form_factor": "scooter_standing",
"make": [
{
"language": "en",
"text": "Ninebot"
}
],
"max_permitted_speed": 20,
"max_range_meters": 80000,
"model": [
{
"language": "en",
"text": "Voiager_5"
}
],
"name": [
{
"language": "en",
"text": "Voiager_5"
}
],
"pricing_plan_ids": [
"scooter-pricing-plan-1"
],
"propulsion_type": "electric",
"rated_power": 250,
"return_constraint": "hybrid",
"rider_capacity": 1,
"vehicle_assets": {
"icon_last_modified": "2024-01-01",
"icon_url": "https://docs.voi.com/assets/images/icons/scooter.svg"
},
"vehicle_type_id": "172ef7a6-ee84-4320-9337-86235f2f67ac",
"wheel_count": 2
}
]
},
"last_updated": "2025-02-17T12:58:33Z",
"ttl": 30,
"version": "3.0"
}
vehicle_types describes traits of our different vehicles
Response
The data: Payload { "vehicle_types": [] }, is an array of objects with the following structure.
| Field Name | type | Defines |
|---|---|---|
vehicle_type_id | String | Unique identifier of a vehicle type |
color | String | Color of the vehicle |
default_pricing_plan_id | String | Default pricing plan ID for this vehicle (see system_pricing_plans.json) |
default_reserve_time | Number | Default reservation (booking) time in minutes |
make | Array | Make of the vehicle |
max_permitted_speed | Number | Max allowed speed on the vehicle in km/h |
max_range_meters | Number | If engine-driven, furthest travel distance before it needs to be recharged |
model | Array | Public model name of relevant vehicle type |
name | Array | Public name of relevant vehicle type |
pricing_plan_ids | Array | Other pricing plan IDs that relate to the vehicle |
propulsion_type | String | Primary propulsion type of the vehicle |
rated_power | Number | Rated motor power of the vehicle |
return_constraint | String | Conditions for returning the vehicle |
rider_capacity | Number | Number of people allowed on the vehicle (driver included) |
vehicle_assets | Object | Assets such as icons that relate to the vehicle type |
wheel_count | Number | Number of wheels on the vehicle |
Vehicle Status
A Vehicle Status request.
$ curl --location --request GET https://api.voiapp.io/v1/partner-apis/gbfs/{zoneID}/vehicle_status.json
-H "X-Access-Token: $API_KEY"
Path parameters
| parameter | description | presence |
|---|---|---|
| zoneID | The zone id for the requested status changes | required |
A vehicle_status.json response.
{
"data": {
"vehicles": [
{
"current_fuel_percent": 0.47,
"current_range_meters": 37600,
"is_disabled": false,
"is_reserved": false,
"last_reported": "2025-02-17T13:19:04Z",
"lat": 59.33863,
"lon": 18.067764,
"rental_uris": {
"android": "https://voi.com/deeplink?company=voiapp.io&vehicle_qr_code=gzpm",
"ios": "https://voi.com/deeplink?company=voiapp.io&vehicle_qr_code=gzpm"
},
"station_id": "31ecd9f9-7f10-4c32-89bc-7651dd1acbb2",
"vehicle_id": "0858ba28-4404-4efb-a6aa-0dd65c8dce88",
"vehicle_type_id": "172ef7a6-ee84-4320-9337-86235f2f67ac"
}
]
},
"last_updated": "2025-02-17T12:58:33Z",
"ttl": 30,
"version": "3.0"
}
vehicle_status describes the current status of the vehicles in the city
Response
The data: Payload { "vehicles": [] }, is an array of objects with the following structure.
| Field Name | type | Defines |
|---|---|---|
current_fuel_percent | Number | Current battery percentage of the vehicle |
current_range_meters | Number | Current estimated range in meters |
is_disabled | Boolean | Whether the vehicle is currently disabled |
is_reserved | Boolean | Whether the vehicle is currently reserved |
last_reported | String | ISO 8601 timestamp when the vehicle last reported its status |
lat | Number | Latitude of the vehicle's current location |
lon | Number | Longitude of the vehicle's current location |
rental_uris | Object | Contains deeplinks to rent vehicle in Android and iOS apps |
station_id | String | Identifier of the station where vehicle is located (if applicable) (see XXXX) |
vehicle_id | String | Unique identifier of the vehicle |
vehicle_type_id | String | Identifier for the type of vehicle (see vehicle_types.json) |
Station Status
A Station Status request.
$ curl --location --request GET https://api.voiapp.io/v1/partner-apis/gbfs/{zoneID}/station_status.json
-H "X-Access-Token: $API_KEY"
Path parameters
| parameter | description | presence |
|---|---|---|
| zoneID | The zone id for the requested status changes | required |
A station_status.json response.
{
"data": {
"stations": [
{
"is_installed": false,
"is_renting": true,
"is_returning": true,
"last_reported": "2024-08-21T14:30:52Z",
"num_vehicles_available": 1,
"station_id": "746fd4e0-0fc9-4275-9060-e1693c982999",
"vehicle_types_available": [
{
"count": 1,
"vehicle_type_id": "172ef7a6-ee84-4320-9337-86235f2f67ac"
}
]
}
]
},
"last_updated": "2025-02-17T12:58:33Z",
"ttl": 30,
"version": "3.0"
}
station_status describes the current status of our (virtual) parking stations
Response
The data: Payload { "stations": [] }, is an array of objects with the following structure.
| Field Name | type | Defines |
|---|---|---|
station_id | String | Identifier of the station (see station_information.json) |
is_installed | Boolean | Whether the station is physically installed |
is_renting | Boolean | Whether the station is currently renting vehicles |
is_returning | Boolean | Whether the station is accepting vehicle returns |
last_reported | String | ISO 8601 timestamp when the station last reported its status |
num_vehicles_available | Integer | Number of vehicles available for rental at the station |
vehicle_types_available | Array | Array of objects containing count and vehicle_type_id for available types |
Station Information
A Station Information request.
$ curl --location --request GET https://api.voiapp.io/v1/partner-apis/gbfs/{zoneID}/station_information.json
-H "X-Access-Token: $API_KEY"
Path parameters
| parameter | description | presence |
|---|---|---|
| zoneID | The zone id for the requested status changes | required |
A station_information.json response.
{
"data": {
"stations": [
{
"is_virtual_station": true,
"lat": 59.33965,
"lon": 18.038778,
"name": [
{
"language": "en",
"text": "Flygbussarna S:t Eriksplan (B)"
}
],
"station_area": {
"coordinates": [
[
[
[
18.038727,
59.33965
],
[
18.03882,
59.339664
],
[
18.038834,
59.33965
],
[
18.038734,
59.339634
],
[
18.038727,
59.33965
]
]
]
],
"type": "MultiPolygon"
},
"station_id": "1d835625-17bc-4a3a-adfe-4cb6ec85b9b5"
}
]
},
"last_updated": "2025-02-17T12:58:33Z",
"ttl": 3600,
"version": "3.0"
}
station_information describes static information about the parking infrastructure in the city
Response
The data: Payload { "stations": [] }, is an array of objects with the following structure.
| Field Name | type | Defines |
|---|---|---|
is_virtual_station | String | Identifier of the station (see station_information.json) |
lat | Number | Latitude of the center of the parking station |
lon | Number | Longitude of the center of the parking station |
name | String | Name of the station |
station_area | Array | GeoJSON representation of the virtual area of the parking station |
station_id | String | Identifier of the station |
System Information
A System Information request.
$ curl --location --request GET https://api.voiapp.io/v1/partner-apis/gbfs/{zoneID}/system_information.json
-H "X-Access-Token: $API_KEY"
Path parameters
| parameter | description | presence |
|---|---|---|
| zoneID | The zone id for the requested status changes | required |
A system_information.json response.
{
"data": {
"attribution_organization_name": [
{
"language": "en",
"text": "VOI Technology AB"
}
],
"attribution_url": "https://www.voi.com",
"languages": [
"en"
],
"name": [
{
"language": "en",
"text": "VOI"
}
],
"opening_hours": "24/7",
"operator": [
{
"language": "en",
"text": "VOI Technology AB"
}
],
"rental_apps": {
"android": {
"discovery_uri": "voiapp://open",
"store_uri": "https://play.google.com/store/apps/details?id=io.voiapp.voi"
},
"ios": {
"discovery_uri": "voiapp://",
"store_uri": "https://apps.apple.com/us/app/voi-e-scooter-e-bike-hire/id1395921017"
}
},
"system_id": "voi_Stockholm",
"timezone": "Europe/Stockholm"
},
"last_updated": "2025-02-17T12:58:33Z",
"ttl": 3600,
"version": "3.0"
}
system_information describes static information about the system (city).
Response
The data: Payload is an objects with the following structure.
| Field Name | type | Defines |
|---|---|---|
attribution_organization_name | Array | Array of names identifying the organization that operates the system |
attribution_url | String | URL of the organization that operates the system |
email | String | Support email address |
feed_contact_email | String | Contact email for feed-related questions |
languages | Array | Array of supported language codes |
name | Array | Array of name/language pairs identifying the system name |
opening_hours | String | Hours of operation |
operator | Array | Array of name/language pairs identifying the system operator |
rental_apps | Object | Contains discovery and store URIs for Android and iOS rental apps |
system_id | String | Unique identifier for this system (city) |
timezone | String | Timezone where system is located |
System Pricing Plans
A System Pricing Plans request.
$ curl --location --request GET https://api.voiapp.io/v1/partner-apis/gbfs/{zoneID}/system_pricing_plans.json
-H "X-Access-Token: $API_KEY"
Path parameters
| parameter | description | presence |
|---|---|---|
| zoneID | The zone id for the requested status changes | required |
A system_pricing_plans.json response.
{
"data": {
"plans": [
{
"currency": "SEK",
"description": [
{
"language": "en",
"text": "Pay as you go pricing plan with unlock fee and per minute pricing"
}
],
"is_taxable": false,
"name": [
{
"language": "en",
"text": "Pay as you go"
}
],
"per_min_pricing": [
{
"interval": 0,
"rate": 3,
"start": 0
}
],
"plan_id": "scooter-pricing-plan-1",
"price": 10,
"surge_pricing": false
}
]
},
"last_updated": "2025-02-17T13:48:19Z",
"ttl": 3600,
"version": "3.0"
}
system_pricing_plans describes static information about the pricing in the city.
Response
The data: Payload { "plans": [] }, is an array of objects with the following structure.
| Field Name | type | Defines |
|---|---|---|
plan_id | String | Unique identifier for a pricing plan in the system (referred to as pricing_plan_ids in other feeds) |
name | Array | Short name of the pricing plan |
currency | String | Type of currency used in the pricing plan |
price | Number | Fee to start ride |
is_taxable | Boolean | Whether the pricing plan is taxable |
description | Array | Long description of the pricing plan |
per_min_pricing | Array | Array of interval, rate and start pricing |
surge_pricing | Boolean | Whether surge pricing is in effect |
Geofencing Zones
A Geofencing Zones request.
$ curl --location --request GET https://api.voiapp.io/v1/partner-apis/gbfs/{zoneID}/geofencing_zones.json
-H "X-Access-Token: $API_KEY"
Path parameters
| parameter | description | presence |
|---|---|---|
| zoneID | The zone id for the requested status changes | required |
A geofencing_zones.json response.
{
"data": {
"geofencing_zones": {
"features": [
{
"geometry": {
"type": "MultiPolygon",
"coordinates": [
[
[
[
18.069855,
59.34351
],
[
18.069885,
59.343519
],
[
18.069918,
59.343515
],
[
18.069936,
59.343501
],
[
18.06993,
59.343484
],
[
18.069898,
59.343475
],
[
18.069855,
59.34351
]
]
]
]
},
"properties": {
"name": [
{
"language": "en",
"text": "Stockholm - Rådmansgatan 7"
}
],
"rules": [
{
"ride_end_allowed": true,
"ride_start_allowed": true,
"ride_through_allowed": true,
"station_parking": true,
"maximum_speed_kph": 16
}
]
},
"type": "Feature"
}
],
"type": "FeatureCollection"
},
"global_rules": [
{
"maximum_speed_kph": 20,
"ride_end_allowed": false,
"ride_start_allowed": false,
"ride_through_allowed": false,
"station_parking": true,
"vehicle_type_ids": [
"172ef7a6-ee84-4320-9337-86235f2f67ac",
"a71a53fa-ba78-4f7d-8406-840db031830e"
]
}
]
},
"last_updated": "2025-01-29T16:07:01Z",
"ttl": 3600,
"version": "3.0"
}
geofencing_zones Describes geofencing zones and their associated rules and attributes. Geofenced areas are delineated using GeoJSON in accordance with RFC 7946.
Response
The geofencing_zones: Payload { "features": [] }, is an array of objects with the following structure.
| Field Name | type | Defines |
|---|---|---|
type | String | Type of GeoJSON object. |
geometry | Object | GeoJSON geometry object defining the zone boundary |
properties | Object | Properties describing the rules of the zone |
properties.name | Array | Array of name/language pairs identifying the zone |
properties.rules | Array | Array of rule objects defining what is allowed in the zone |
rules.ride_end_allowed | Boolean | Whether rides can end in this zone |
rules.ride_start_allowed | Boolean | Whether rides can start in this zone |
rules.ride_through_allowed | Boolean | Whether vehicles can be ridden through this zone |
rules.station_parking | Boolean | Whether station parking is required in this zone |
rules.maximum_speed_kph | Number | Maximum speed allowed in kilometers per hour |
The global_rules Payload is an array of objects with the following structure
| Field Name | type | Defines |
|---|---|---|
maximum_speed_kph | Number | Maximum speed allowed in kilometers per hour in the city |
ride_end_allowed | Boolean | Whether rides can end anywhere in this city |
ride_start_allowed | Boolean | Whether rides can start anywhere in this city |
ride_through_allowed | Boolean | Whether vehicles can be ridden anywhere this city |
station_parking | Boolean | Whether station parking is required in this city |
vehicle_type_ids | Array | Array of vehicle type IDs that these rules apply to |
System Alerts
A System Alerts request.
$ curl --location --request GET https://api.voiapp.io/v1/partner-apis/gbfs/{zoneID}/system_alerts.json
-H "X-Access-Token: $API_KEY"
Path parameters
| parameter | description | presence |
|---|---|---|
| zoneID | The zone id for the requested status changes | required |
A system_alerts.json response.
{
"data": {
"alerts": []
},
"last_updated": "2025-02-17T14:40:56Z",
"ttl": 0,
"version": "3.0"
}
system_alerts describes any alerts around the city, e.g. temporary station closure
Response
The data: Payload { "alerts": [] }, is an array of objects with the following structure.
| Field Name | type | Defines |
|---|---|---|
alert_id | String | Unique identifier for this alert |
type | String | Type of alert (e.g. station_closure) |
station_ids | Array | Array of station IDs affected by this alert |
times | Array | Array of objects containing start and end times when alert is in effect |
url | Array | Array of objects containing URL and language for more information about alert |
summary | Array | Array of objects containing short summary text and language |
description | Array | Array of objects containing detailed description text and language |
last_updated | String | Timestamp indicating when this alert was last updated |
System Regions
A System Regions request.
$ curl --location --request GET https://api.voiapp.io/v1/partner-apis/gbfs/{zoneID}/system_regions.json
-H "X-Access-Token: $API_KEY"
Path parameters
| parameter | description | presence |
|---|---|---|
| zoneID | The zone id for the requested status changes | required |
A system_regions.json response.
{
"data": {
"regions": []
},
"last_updated": "2025-02-17T14:44:18Z",
"ttl": 3600,
"version": "3.0"
}
system_regions describes any sub-regsion in the city
Response
The data: Payload { "regions": [] }, is an array of objects with the following structure.
| Field Name | type | Defines |
|---|---|---|
region_id | String | Unique identifier for this region (e.g. "3", "4", "5", "6") |
name | Array | Array of objects containing name text (e.g. "North", "East", "South", "West") and language code (e.g. "en") for this region |