Link Search Menu Expand Document

Last update: 25/10/2022

Introduction

Welcome

Welcome to the TIER MDS Version 1.2.

This documentation provides the essentials to integrate with TIER’s MDS 1.2.

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

Format

The TIER API is using the JSON:API standard.

Versioning

The MDS APIs handle requests for specific versions of the specification from clients.

Clients must specify the version they are targeting through the Accept header. For example:

Accept: application/vnd.mds+json;version=1.2

Backwards-Compatible Minor Updates

We will only break backwards compatibility in new API versions. That means that all actions or resources will remain backwards compatible as long as your integration allows for the following changes to be made on our side:

  • An endpoint resource might return new fields, e.g. {"foo": "bar"} might be {"foo": "bar", "baz": 123} tomorrow
  • An endpoint might accept new optional data or parameters
  • An endpoint might ignore previously required data while providing same functionality

🚨 Please keep in mind that v1.2 will NOT break our previous v1.0 backwards compatibility.

FAQs

Please find the Frequently Asked Questions (FAQs) for TIER Mobility here.

Supported authentication methods

To access our MDS endpoints you need to authenticate the requests using the following method

🚨 Please keep that from v1.2 only OAuth method is supported.

OAuth client credentials

MDS 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 mds scope. Note for MDS a separate access token needed for every cities, so the same token can not be used for multiple cities. To indicate this please pass the name of the city as a scope parameter in a following format: city-{name}.

Note an access token has an expiration time (2 hours), 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. Every relevant access details will be shared.

Example token request:

curl -L -X POST 'https://auth.tier-services.io/oauth2/aus41nfrunfKbXbOr417/v1/token'  \
    --header "Authorization: Basic $(base64 <(echo -n '<clientID>:<clientSecret>'))" \
    --data 'grant_type=client_credentials&scope=mds city-paris'

Example token response:

// success HTTP 200:
{"token_type":"Bearer", "expires_in":3600, "access_token":<TOKEN>, "scope":"mds city-paris"}
// 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).

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.


Mobility Data Specification (MDS) - v1.2 endpoints

The TIER API provides a subset of the MDS 1.2 Provider API.

The following endpoints are available, fully conformant to the 1.2 version of the specification, meaning the endpoint can parameterised as described in the official documentation, and the response is also the same.

Trips

View related MDS 1.2 Trips Specification

Example:

curl -L -X GET 'https://platform.tier-services.io/data-sharing/mds/trips?end_time=2021-07-16T04' -H 'Authorization: Bearer <access token>' -H 'Content-Type: application/vnd.mds.provider+json;version=1.2' -H 'Accept: application/vnd.mds.provider+json;version=1.2'
Click to expand JSON data response
{
    "version": "1.2",
    "data": {
        "trips": [
            {
                "vehicle_id": "295896",
                "route": {
                    "type": "FeatureCollection",
                    "features": [
                        {
                            "type": "Feature",
                            "properties": {
                                "timestamp": 1622709915000
                            },
                            "geometry": {
                                "type": "Point",
                                "coordinates": [
                                    51.524099,
                                    0.003282
                                ]
                            }
                        },
                        {
                            "type": "Feature",
                            "properties": {
                                "timestamp": 1622709927000
                            },
                            "geometry": {
                                "type": "Point",
                                "coordinates": [
                                    51.524071,
                                    0.003224
                                ]
                            }
                        },
                    ]
                },
                "vehicle_type": "scooter",
                "trip_distance": 372,
                "accuracy": 1,
                "start_time": 1622709915000,
                "propulsion_types": [
                    "electric"
                ],
                "trip_id": "801f3fa8-8ebc-48ce-b1db-5064821c2842",
                "provider_id": "264aad41-b47c-415d-8585-0208d436516e",
                "trip_duration": 2418,
                "device_id": "dc7a36a3-c2db-41b1-8cd3-919dca62af70",
                "end_time": 1622712333000,
                "provider_name": "Tier"
            }
        ]
    }
}

Events

View related MDS 1.2 Events Specification

curl -L -X GET 'https://platform.tier-services.io/data-sharing/mds/events?start_time=1626263724479&end_time=1626363724479' -H 'Authorization: Bearer <access token>' -H 'Content-Type: application/vnd.mds.provider+json;version=1.2' -H 'Accept: application/vnd.mds.provider+json;version=1.2'

Status Changes

View related MDS 1.2 Status Changes Specification

Example:

curl -L -X GET 'https://platform.tier-services.io/data-sharing/mds/status_changes?event_time=2021-06-11T08' -H 'Authorization: Bearer <access token>' -H 'Content-Type: application/vnd.mds.provider+json;version=1.2' -H 'Accept: application/vnd.mds.provider+json;version=1.2'
Click to expand JSON data response
{
    "version": "1.2",
    "data": {
        "status_changes": [
            {
                "vehicle_id": "284366",
                "event_location": {
                    "type": "Feature",
                    "properties": {
                        "timestamp": 1622710800078
                    },
                    "geometry": {
                        "type": "Point",
                        "coordinates": [
                            51.483336,
                            -0.039034
                        ]
                    }
                },
                "vehicle_type": "scooter",
                "event_time": 1622710800078,
                "propulsion_types": [
                    "electric"
                ],
                "provider_id": "264aad41-b47c-415d-8585-0208d436516e",
                "device_id": "6fbe8c78-59d3-4ee5-83c6-33b1a94af3c6",
                "battery_pct": 0,
                "event_types": [
                    "battery_low"
                ],
                "provider_name": "Tier",
                "vehicle_state": "non_operational"
            }
    ]
}

Vehicles (Beta)

⚠️ Beta Please note that this feature is still in beta mode).

View related MDS 1.2 Vehicles Specification

Example:

curl -L -X GET 'https://platform.tier-services.io/data-sharing/mds/vehicles' -H 'Authorization: Bearer <access token>' -H 'Content-Type: application/vnd.mds.provider+json;version=1.2' -H 'Accept: application/vnd.mds.provider+json;version=1.2'
Click to expand JSON data response
{
    "version": "1.2",
    "ttl": 0,
    "last_updated": 1666700439000,
    "data": {
        "vehicles": [
            {
                "battery_pct": 0.84,
                "device_id": "4849af8c-2dac-402e-8337-704a790380f9",
                "last_event_location": {
                    "type": "Feature",
                    "geometry": {
                        "coordinates": [
                            13.32197,
                            52.514443
                        ],
                        "type": "Point"
                    },
                    "properties": {
                        "timestamp": 1666700439000
                    }
                },
                "last_event_time": 1666700439000,
                "last_event_types": [
                    "trip_end"
                ],
                "last_vehicle_state": "available",
                "propulsion_types": [
                    "electric"
                ],
                "provider_id": "264aad41-b47c-415d-8585-0208d436516e",
                "provider_name": "Tier",
                "vehicle_id": "164702",
                "vehicle_type": "scooter"
            },
        ]
    }
}