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 3 supported GBFS version at the moment (also avaialble under /versions endpoints for self-discovery):

• 2.1 (deprecated)
• 2.2
• 2.3

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).

API keys - !deprecated!

⚠️ API keys are deprecated and eventually stop being supported by TIER. Please use OAuth client credentials mode!

This is a shared secret authentication setup in which the consumer needs to pass their private api key with the requests. If the key matches our records we’ll consider the request authenticated. Note API keys do not have expiration time, they valid until revoked manually.

Example request with api key:

curl -L 'https://platform.tier-services.io/data-sharing/tier_<zone-id>/gbfs/<version>'  --header "x-api-key: {API_KEY}"

🚨 API keys are confidential information please do not share them with 3rd parties or publicly. May only be used in secure backend services.

Terms & Conditions

Please find our current Terms & Conditions here: https://www.tier.app/terms-and-conditions-unbranded/

Users have to accept these Terms & Conditions before using our services.

URL structure

The Base URL for private feeds is at https://platform.tier-services.io/data-sharing/tier_<zone-id>/gbfs/<version>, all the other feeds are available from this link.

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 endpoints (can be inspected via consuming the base URL):

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

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

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

    {
        "last_updated": 1626254696,
        "ttl": 0,
        "version": "2.2",
        "data": {
            "bikes": [
                {
                    "bike_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 vehicle 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.