Last update: 17/06/2022
Introduction
Welcome
Welcome to the TIER MDS Version 1.0.
This documentation provides the essentials to integrate with TIER’s MDS 1.0.
ℹ 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.0
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.0 will break our previous v0.3 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 one of the following method
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 'https://auth.tier-services.io/oauth2/aus41nfrunfKbXbOr417/v1/token' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'grant_type=client_credentials' \
-d 'scope=mds city-paris' \
-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":"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).
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/mds/trips?end_time=2021-07-16T04' --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/
Users have to accept these Terms & Conditions before using our services.
Mobility Data Specification (MDS) - v1.0 endpoints
The TIER API provides a subset of the MDS 1.0 Provider API.
The following endpoints are available, fully conformant to the 1.0 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.0 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.0' -H 'Accept: application/vnd.mds.provider+json;version=1.0'
Click to expand JSON data response
{
"version": "1.0",
"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.0 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.0' -H 'Accept: application/vnd.mds.provider+json;version=1.0'
Status Changes
View related MDS 1.0 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.0' -H 'Accept: application/vnd.mds.provider+json;version=1.0'
Click to expand JSON data response
{
"version": "1.0",
"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"
}
]
}