GBFS

OTP can also fetch real-time data about vehicle rental networks including the number of vehicles and free parking spaces at each station. We support vehicle rental systems that use the GBFS standard, which can describe a variety of shared mobility services.

OTP has partial support for both GBFS v1, v2.3 and v3.0 (list of known GBFS feeds). Furthermore, support is limited to the following form factors:

bicycle
scooter
car

Config Parameter	Type	Summary	Req./Opt.	Default Value	Since
type = "vehicle-rental"	`enum`	The type of the updater.	Required		1.5
allowKeepingRentedVehicleAtDestination	`boolean`	If a vehicle should be allowed to be kept at the end of a station-based rental.	Optional	`false`	2.1
frequency	`duration`	How often the data should be updated.	Optional	`"PT1M"`	1.5
language	`string`	TODO	Optional		2.1
network	`string`	The name of the network to override the one derived from the source data.	Optional		1.5
overloadingAllowed	`boolean`	Allow leaving vehicles at a station even though there are no free slots.	Optional	`false`	2.2
sourceType	`enum`	What source of vehicle rental updater to use.	Required		1.5
startupRetryPeriod	`duration`	How long to retry loading the vehicle rental data source on startup if it initially fails.	Optional	`"PT0S"`	2.10
url	`string`	The URL to download the data from.	Required		1.5
geofencing	`object`	Configuration for GBFS geofencing-based rental restrictions.	Optional		2.10
businessAreaBorders	`boolean`	Infer an operational area from permissive GBFS geofencing zones and enforce drop-off at its boundary.	Optional	`true`	2.10
enabled	`boolean`	Compute rental restrictions based on GBFS 2.2 geofencing zones.	Optional	`false`	2.10
headers	`map of string`	HTTP headers to add to the request. Any header key, value can be inserted.	Optional		1.5
rentalPickupTypes	`enum set`	This is temporary and will be removed in a future version of OTP. Use this to specify the type of rental data that is allowed to be read from the data source.	Optional		2.7

Parameter details

allowKeepingRentedVehicleAtDestination

Since version: 2.1 ∙ Type: boolean ∙ Cardinality: Optional ∙ Default value: false
Path: /updaters/[1]

If a vehicle should be allowed to be kept at the end of a station-based rental.

In some cases it may be useful to not drop off the rented vehicle before arriving at the destination. This is useful if vehicles may only be rented for round trips, or the destination is an intermediate place.

For this to be possible three things need to be configured:

In the updater configuration allowKeepingRentedVehicleAtDestination should be set to true.
allowKeepingRentedVehicleAtDestination should also be set for each request, either using routing defaults, or per-request.
If keeping the vehicle at the destination should be discouraged, then keepingRentedVehicleAtDestinationCost (default: 0) may also be set in the routing defaults.

network

Since version: 1.5 ∙ Type: string ∙ Cardinality: Optional
Path: /updaters/[1]

The name of the network to override the one derived from the source data.

GBFS feeds must include a system_id which will be used as the default network. These ids are sometimes not helpful so setting this property will override it.

sourceType

Since version: 1.5 ∙ Type: enum ∙ Cardinality: Required
Path: /updaters/[1]
Enum values: gbfs

What source of vehicle rental updater to use.

startupRetryPeriod

Since version: 2.10 ∙ Type: duration ∙ Cardinality: Optional ∙ Default value: "PT0S"
Path: /updaters/[1]

How long to retry loading the vehicle rental data source on startup if it initially fails.

The first time the data source is loaded, OTP will retry for this duration every 5 seconds before giving up. This is useful to handle temporary network failures during OTP startup. Set to PT0S to disable retries.

businessAreaBorders

Since version: 2.10 ∙ Type: boolean ∙ Cardinality: Optional ∙ Default value: true
Path: /updaters/[1]/geofencing

Infer an operational area from permissive GBFS geofencing zones and enforce drop-off at its boundary.

When enabled, GBFS geofencing zones that have no restrictions (no traversal or drop-off bans) are treated as business areas. The router will force a vehicle drop-off when exiting such an area, preventing routes that leave the operator's service area with a rented vehicle.

Requires enabled to also be true.

enabled

Since version: 2.10 ∙ Type: boolean ∙ Cardinality: Optional ∙ Default value: false
Path: /updaters/[1]/geofencing

Compute rental restrictions based on GBFS 2.2 geofencing zones.

This feature is somewhat experimental and therefore turned off by default for the following reasons:

It delays start up of OTP. How long is dependent on the complexity of the zones. For example in Oslo it takes 6 seconds to compute while Portland takes 25 seconds.
It's easy for a malformed or unintended geofencing zone to make routing impossible. If you encounter such a case, please file a bug report.

headers

Since version: 1.5 ∙ Type: map of string ∙ Cardinality: Optional
Path: /updaters/[1]

HTTP headers to add to the request. Any header key, value can be inserted.

rentalPickupTypes

Since version: 2.7 ∙ Type: enum set ∙ Cardinality: Optional
Path: /updaters/[1]
Enum values: station | free-floating

This is temporary and will be removed in a future version of OTP. Use this to specify the type of rental data that is allowed to be read from the data source.

station Stations are imported.
free-floating Free-floating vehicles are imported.

Example configuration

// router-config.json
{
  "updaters" : [
    {
      "type" : "vehicle-rental",
      "network" : "socialbicycles_coast",
      "sourceType" : "gbfs",
      "language" : "en",
      "frequency" : "1m",
      "allowKeepingRentedVehicleAtDestination" : false,
      "geofencing" : {
        "enabled" : false
      },
      "url" : "http://coast.socialbicycles.com/opendata/gbfs.json",
      "headers" : {
        "Auth" : "<any-token>",
        "<key>" : "<value>"
      }
    }
  ]
}

Shared network configuration

The vehicle rental service directory discovers its feeds from a GBFS manifest and takes its per-network settings from the gbfs section of otp-config.json, keyed by the GBFS system_id.

These values are not embedded in the graph, so otp-config.json must be present in the deployment directory when the graph is served as well as when it is built.

defaults is applied per field: a listed network overrides only the fields it names and inherits the rest. includeUnlistedNetworks is a separate switch so that adding defaults to avoid repetition cannot silently widen which networks OTP loads.

// otp-config.json
{
  "gbfs" : {
    "defaults" : {
      "applyGeofencingZones" : "off",
      "requireDropOffInsideBusinessArea" : true,
      "allowKeepingVehicleAtDestination" : false
    },
    "includeUnlistedNetworks" : true,
    "networks" : [
      { "network" : "oslobysykkel", "applyGeofencingZones" : "realtime", "allowKeepingVehicleAtDestination" : true }
    ]
  }
}

Config Parameter	Type	Summary	Req./Opt.	Default Value	Since
includeUnlistedNetworks	`boolean`	Whether networks in the GBFS manifest but absent from `networks` are loaded.	Optional	`false`	2.10
defaults	`object`	Values applied to every network that does not set them itself.	Optional		2.10
allowKeepingVehicleAtDestination	`boolean`	Whether a vehicle rented from a station may be kept at the destination.	Optional	`false`	2.10
applyGeofencingZones	`enum`	When this network's geofencing zones are computed and applied.	Optional	`"off"`	2.10
requireDropOffInsideBusinessArea	`boolean`	Whether a rented vehicle must be dropped off before leaving the business area.	Optional	`true`	2.10
networks	`object[]`	Per-network overrides, keyed by the GBFS `system_id`.	Optional		2.10
allowKeepingVehicleAtDestination	`boolean`	Whether a vehicle rented from a station may be kept at the destination.	Optional	`false`	2.10
applyGeofencingZones	`enum`	When this network's geofencing zones are computed and applied.	Optional	`"off"`	2.10
network	`string`	The GBFS `system_id` of the network these values apply to.	Required		2.10
requireDropOffInsideBusinessArea	`boolean`	Whether a rented vehicle must be dropped off before leaving the business area.	Optional	`true`	2.10

Parameter details

includeUnlistedNetworks

Since version: 2.10 ∙ Type: boolean ∙ Cardinality: Optional ∙ Default value: false
Path: /gbfs

Whether networks in the GBFS manifest but absent from networks are loaded.

When false such a network is skipped with a warning, so networks acts as a whitelist. When true it is loaded with defaults applied.

defaults

Since version: 2.10 ∙ Type: object ∙ Cardinality: Optional
Path: /gbfs

Values applied to every network that does not set them itself.

A network listed in networks overrides only the fields it names and inherits the rest from here. Setting defaults does not by itself widen which networks are loaded - see includeUnlistedNetworks.

allowKeepingVehicleAtDestination

Since version: 2.10 ∙ Type: boolean ∙ Cardinality: Optional ∙ Default value: false
Path: /gbfs/defaults

Whether a vehicle rented from a station may be kept at the destination.

When disabled a vehicle rented from a station must be returned to another station, so an itinerary can only end with the vehicle parked at one.

applyGeofencingZones

Since version: 2.10 ∙ Type: enum ∙ Cardinality: Optional ∙ Default value: "off"
Path: /gbfs/defaults
Enum values: realtime | off

When this network's geofencing zones are computed and applied.

realtime The vehicle rental updater loads and applies the zones.
off The zones are not processed for this network. Use this to opt a single network out of a defaults block that enables them.

requireDropOffInsideBusinessArea

Since version: 2.10 ∙ Type: boolean ∙ Cardinality: Optional ∙ Default value: true
Path: /gbfs/defaults

Whether a rented vehicle must be dropped off before leaving the business area.

A business area is inferred from geofencing zones whose ride and traversal rules are all permissive. When enabled, the router forces a drop-off at the border of that area, preventing itineraries that leave the operator's service area with a rented vehicle.

Has no effect when applyGeofencingZones is off.

networks

Since version: 2.10 ∙ Type: object[] ∙ Cardinality: Optional
Path: /gbfs

Per-network overrides, keyed by the GBFS system_id.