April 9, 2024 11:54 pm

🛠️ How-to Upgrade to GBFS v3.0

Your GBFS v3.0 Implementation Starter Guide

We recently published a blog post to introduce GBFS v3.0 and why we think you’ll love it. Now, with GBFS v3.0 officially part of the standard, we wanted to help kickstart your transition to v3.0! In this article you will see how changes look in v3.0 with examples of GBFS v3.0 feeds. If you haven’t reviewed the full specification already, you can read all about it here.

Let’s not waste any time and get right to the details.

Versioning

First up, let’s talk about versioning. It’s recommended that producers maintain the previous version of their feeds alongside the latest v3.0 feed for one year. This gives time for all consumers to migrate to the latest major version.

Producers should populate gbfs_versions.json with the supported versions (and manifest.json if applicable). They should also update the systems.csv catalog with the latest official version of their feeds.

To help with the migration to v3.0, we have worked with Entur to publish GBFS types in TypeScript (NPM package) and Java (Maven Central package). They are automatically generated from the official GBFS JSON Schemas. So when the specification changes, your data model evolves with it. You can find generator tools for many programming languages at json-schema.org.

gbfs_versions.json

				
					{
  "last_updated": "2023-07-17T13:34:13+02:00",
  "ttl": 0,
  "version": "3.0",
  "data": {
  "versions": [{
      "version": "2.3",
      "url": "https://www.example.com/gbfs/2/gbfs"
    },
    {
      "version": "3.0",
      "url": "https://www.example.com/gbfs/3/gbfs"
    }
  ]}
}
				
			

Example of gbfs_versions.json listing the different versions of the same feed.

Protects Publishers & Riders

With GBFS v3.0, some changes were made to better protect the privacy of riders and publishers. Check out this table to see what the changes are and how they look now in v3.0

Change v2.3 and Below v3.0

Static vehicle IDs compromised
the riders privacy in vehicles[ ].rental_uris (eg: com.example.ios://open.example.app/app?sid=001)

Vehicle IDs MUST be rotated after each rental to avoid unintentionally exposing private trip origins and destinations in vehicles[ ].rental_uris (eg: com.example.ios://open.example.app/app?sid=952dcab50889)

license_url (system_information.json) was optional. 

license_id OR license_url (system_information.json) are now required. If both fields are blank or omitted, this indicates that the feed is provided under the Creative Commons Universal Public Domain Dedication.

New fields: 
attribution_organization_name and attribution_url useful if the feed license requires attribution.

feed_contact_email (system_information.json) was optional.

feed_contact_email (system_information.json) is now required.

This new endpoint called manifest.json is an index, required for publishers of feeds for multiple cities.

Reduce Implementation Costs

GBFS was already an easy to use standard, but the community came together to make implementation even easier with GBFS v3.0.

Geofencing Made Simple

Change v2.3 and Below v3.0

A clockwise arrangement of points defined the area enclosed by the polygon, while a counterclockwise order defined the area outside the polygon (right-hand rule).

Global rules define restrictions that apply everywhere and specific rules are defined inside polygons.

Fig. 1. Visualize the geofencing rules with the GBFS Validator.

In-line Translations

Change v2.3 and Below v3.0

The whole dataset was duplicated for each supported language.

A single dataset with in-line translations.

system_pricing_plans.json

				
					{
  "last_updated": "2023-07-17T13:34:13+02:00",
  "ttl": 0,
  "version": "3.0",
  "data": {
    "plans": [{
      "plan_id": "plan1",
      "name": [
        {
          "text": "One-Way",
          "language": "en"
        },
        {
          "text": "Aller simple",
          "language": "fr"
        }
      ],
      ... more details about the pricing plan
    }]
  }
}
				
			

Example of system_pricing_plans.json listing in-line translations of a pricing plan name

Standardized Data Types

Change v2.3 and Below v3.0

Timestamps were integers in POSIX time (eg: 1706100760).

Timestamps MUST be strings in RFC3339 format, (eg: 2024-01-24T12:52:40+01:00)

IDs could contain special characters (eg: éØp~1).

IDs MUST be in the ASCII printable character range, space excluded, and SHOULD be restricted to A-Z, a-z, 0-9 and .@:/_- (eg: D9:N_c).

Enum values could be of any case (eg: BICYCLE).

Enum values MUST be lowercase (eg: bicycle).

Opening hours were optional and defined in system_hours.json and system_calendar.json.
These files were removed.

Opening hours are required and defined in system_hours.json in the OpenStreetMap format
(eg: 24/7 or Apr 1 - Nov 3 00:00-24:00).

Phone numbers were not standard (eg: 877-430-BIKE).

Phone numbers MUST be in
E.164 format (eg: +18005551234).

Prices in system_pricing_plans.json could be strings (eg: ”$1.50”).

Prices in system_pricing_plans.json MUST be Non-Negative Floats (eg: 1.50)

The Spec is More Intuitive

Shared mobility isn’t just about bikes anymore and GBFS v3.0 reflects that by replacing the word “bike” with “vehicle”. This change better reflects the use cases of GBFS today while still being broad enough to cover any future changes as well.

Change v2.3 and Below v3.0

Endpoint was free_bikes_status.json.

Previous field names:
bikes
bike_id
num_bikes_available
num_bikes_disabled

Endpoint is now vehicle_status.json.

New field names:
vehicles
vehicle_id
num_vehicles_available
num_vehicles_disabled

Previous field names and types:
vehicle_type_capacity: {}
vehicle_capacity: {}

New field names and types:
vehicle_docks_capacity: []
vehicle_types_capacity: []

Corrected field names here and there

Previous field names:
vehicle_type_id (geofencing_zones.json) eco_label (vehicle_types.json)

New field names:
vehicle_type_ids (geofencing_zones.json) eco_labels (vehicle_types.json)

Improved Rider Experience

This major new change allows producers to add descriptions for vehicles, including their special features, how-tos, or any other information important to share with riders. It also adds the cargo bike and seated scooters form factors and warns users of a permanent shutdown of the service.

Change v2.3 and Below v3.0

Vehicle types had no description.

Vehicle types can have a free -form text description in vehicle_types[].description (eg: Extra comfortable seat).

cargo_bicycle and scooter_seated form factors were not supported.

cargo_bicycle and scooter_seated form factors are supported. scooter becomes scooter_standing.
New fields:
wheel_count
maximum_permitted_speed rated_power.

Data sources could become
unavailable to consuming
applications without notice.

New field:
termination_date (system_information.json) to notify data consumers of a permanent (non-seasonal) shutdown of the feeds. 

You Can Upgrade to GBFS v3.0 Today

GBFS v3.0 is a more secure and intuitive version of the specification and you can implement these new changes now! You can also check out some examples of GBFS v3.0 feeds that have already been published: Check, ENTUR, Flamingo and TIER.

To further assist with the transition to v3.0, be sure to check out our recommended resources by going to the Implementation Guide for GBFS Producers. If you want to learn even more about the spec, click here.

If your v3.0 feed is ready to go, then make sure to paste your feed URL into the GBFS online validator and select version 3.0 to validate your new feed.

Use the GBFS Validator to validate your new v3.0 feed

Let’s Keep Improving GBFS Together

To participate in discussions around GBFS and suggest changes and additions to the specification, join the public GBFS Slack channel and the Github repository!

Questions can be addressed to the community via the public GBFS Slack channel or to the Shared Mobility team at MobilityData: sharedmobility@mobilitydata.org.