General BikeShare Feed Specification v3

⚠️ RELEASE CANDIDATE: The version 3.0 of the GBFS API is still in the process of being released. . The documentation is subject to change. for more information please visit the MobilityData GBFS repository

Introduction

This documentation provides the essentials to integrate with GBFS.

The TIER API provides a partial implementation of the GBFS standard.

ℹ Access is limited for different endpoints and zones for each consumer individually.

Versioning

We have 1 supported GBFS version at the moment (also avaialble under /versions endpoints for self-discovery):

Supported authentication methods

We have public and private GBFS feeds. Public feeds can be consumed without credentials provided although for private ones a credential must be present in the request.

OAuth client credentials

GBFS endpoints are using OAuth client credentials flow to authorize the requests which means an access token needs to be used in Authorization: Bearer <Token> header. The token can be requested on our token endpoint in exchange for client ID and secret. Please use HTTP Basic authentication to retrieve the access token from this endpoint with gbfs scope. Note an access token has an expiration time (1 hour), after expired it can not be used (the request will be rejected HTT 401). This case a new access token must be requested from the token endpoint. The response contains the expiration date as well for the token.

🔑 To obtain client id and client secret please ask your TIER contact.

Example token request:

curl -L 'https://auth.tier-services.io/oauth2/aus41nfrunfKbXbOr417/v1/token' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'grant_type=client_credentials' \
-d 'scope=gbfs' \
-d 'client_id=<client_id>' \
-d 'client_secret=<client_secret>'

Example token response:

// success HTTP 200:
{"token_type":"Bearer", "expires_in":3600, "access_token":<TOKEN>, "scope":"gbfs"}
// error HTTP 400:
{"error":"server_error", "error_description":"Unauthorized"}

🚨 Client secret is a secret information you should never share it publicly in any form (e.g including it in a website source-code).

URL structure

The Base URL for private feeds is at https://platform.tier-services.io/data-sharing/tier_<zone-id>/gbfs/<version>.

Public feed base URL: https://data-sharing.tier-services.io/tier_<zone-id>/gbfs/<version> _{example - paris}

This URL works without authentication but only for our public GBFS zones, all the other zones would result in an unauthorised response.

Supported endpoint (can be inspected via consuming https://data-sharing.tier-services.io/data-sharing/gbfs/<version>):

/manifest _{- docs}

Supported endpoints (can be inspected via consuming the base URL):

/vehicle-status _{- docs}
/vehicle-types _{- docs}
/versions _{- docs}
/system-information _{- docs}
/system-pricing-plans _{- docs}
/station-information _{- docs}
/station-status _{- docs}
/geofencing-zones _{- docs}

A (vehicle-status) example request to get vehicles in Vienna:

curl -L -X GET 'https://platform.tier-services.io/data-sharing/tier_vienna/gbfs/3.0/vehicle-status' -H 'Authorization: Bearer <TOKEN>'

Click to expand JSON data response

    {
        "last_updated": 1626254696,
        "ttl": 0,
        "version": "3.0",
        "data": {
            "vehicles": [
                {
                    "vehicle_id": "ghi789",
                    "last_reported": 1609866109,
                    "lat": 12.34,
                    "lon": 56.78,
                    "is_reserved": false,
                    "is_disabled": false,
                    "vehicle_type_id": "abc123"
                }
            ]
        }
    }

FAQ

Stations

Since TIER does not have physical parking docks our station-information and station-status endpoints contain virtual parking zones instead of docks. See is_virtual_station field at the documentation.

Vehicle types

We use separate vehicle types for business areas e.g: escooter_paris. The reason for that in shard-feeds configuration (multiple business zone data included under a single URL) we can avoid overlaps (e.g with zones) by restricting entities to dedicated vehcile types.

Inactive cities

If a city (root zone) is inactive or does not exist, endpoints return 404 error with the inactive zoneId used in the query.