Last update: 02/12/2020
Introduction
Welcome
Welcome to the TIER API Version 0.3.
This documentation provides the essentials to integrate with TIER’s Mobility API Version 1.
ℹ Access is limited for different endpoints and zones for each API key individually.
Format
The TIER API is using the JSON:API standard.
Versioning
The API is versioned using a prefix in the URL, e.g. /v2 for the second version. There are still some unversioned (deprecated) endpoints. If you are using these, please note that they will stop working in future releases of this API.
Please always use the newest API version and contact us when there is a reason why you cannot switch to a newer version.
Please find the documentation for /v1 here: https://documentation.tier-services.io
Backwards-Compatible Minor Updates
We will only break backwards compatibility in new API versions, which have their own URL prefix. 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
FAQs
Please find the Frequently Asked Questions (FAQs) for TIER Mobility here.
Production and staging URLs
Please note that there are 2 different URLs for our staging and for our production environment.
Our production environment is accessible via https://platform.tier-services.io/v1.
ℹ Please note that we have currently disabled our staging environment. Your requests to
https://platform.tier-staging.io/v1will not get any responses as of now.
ℹ Note that production and staging environments do have different API keys.
Authentication
You must replace TIER API KEY with your personal API key.
TIER is using an API Keys and JSON Web Token (JWT) based authentication, depending on the endpoint. To register for an API key please ask your TIER contact. Each API key is bound to certain permissions that determine which zones and endpoints you can access.
🚨 Do not include the API key in your Mobile or Web client, as they are very powerful! The API Key may only be used in secured backend services, hidden from your customers.
Mobility Data Specification (MDS) - v0.3 - deprecated
The TIER API provides the possibility to get data about trips following the Mobility Data Specification (MDS). This data standard for mobility as a service providers defines a RESTful API for municipalities to access on-demand.
Trips
A trip represents a journey taken by a TIER customer with a geo-tagged start and stop point.
HTTP Request
GET https://platform.tier-services.io/mds/<zone-id>/trips
Query Parameters
| Parameter | Description |
|---|---|
| zoneId | The zone identifier |
| device_id | Vehicle UUID |
| vehicle_id | Vehicle code |
| min_end_time | filters for trips where end_time occurs at or after the given time |
| max_end_time | filters for trips where end_time occurs before the given time |
curl "https://platform.tier-services.io/mds/HAMBURG/trips"
-H "x-api-key: TIER API KEY"
Click to expand JSON data response
{
"version": "0.3.0",
"data": {
"trips": [
{
"provider_id": "264aad41-b47c-415d-8585-0208d436516e",
"provider_name": "Tier",
"device_id": "ad98ca0e-a37f-499f-9a05-4ec01943d7d5",
"vehicle_id": "113376",
"vehicle_type": "scooter",
"propulsion_type": [
"electric"
],
"trip_id": "78ea85c5-e49c-4fbb-aa16-fd9f09e6fc9c",
"trip_duration": 3,
"trip_distance": 900,
"route": {
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"properties": {
"timestamp": 1561185522000
},
"geometry": {
"type": "Point",
"coordinates": [
53.590923,
9.905196
]
}
},
{
"type": "Feature",
"properties": {
"timestamp": 1561185677000
},
"geometry": {
"type": "Point",
"coordinates": [
53.590606,
9.90561
]
}
}
]
},
"accuracy": 20,
"start_time": 1561185512000,
"end_time": 1561185647000
}
]
}
}
Click to expand JSON data response
{
"version": "0.3.0",
"data": {
"trips": [
{
"provider_id": "264aad41-b47c-415d-8585-0208d436516e",
"provider_name": "Tier",
"device_id": "ad98ca0e-a37f-499f-9a05-4ec01943d7d5",
"vehicle_id": "113376",
"vehicle_type": "scooter",
"propulsion_type": [
"electric"
],
"trip_id": "78ea85c5-e49c-4fbb-aa16-fd9f09e6fc9c",
"trip_duration": 3,
"trip_distance": 900,
"route": {
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"properties": {
"timestamp": 1561185522000
},
"geometry": {
"type": "Point",
"coordinates": [
53.590923,
9.905196
]
}
},
{
"type": "Feature",
"properties": {
"timestamp": 1561185677000
},
"geometry": {
"type": "Point",
"coordinates": [
53.590606,
9.90561
]
}
}
]
},
"accuracy": 20,
"start_time": 1561185512000,
"end_time": 1561185647000
}
]
}
}
Click to expand JSON data response
{
"version": "0.3.0",
"data": {
"trips": [
{
"provider_id": "264aad41-b47c-415d-8585-0208d436516e",
"provider_name": "Tier",
"device_id": "ad98ca0e-a37f-499f-9a05-4ec01943d7d5",
"vehicle_id": "113376",
"vehicle_type": "scooter",
"propulsion_type": [
"electric"
],
"trip_id": "78ea85c5-e49c-4fbb-aa16-fd9f09e6fc9c",
"trip_duration": 3,
"trip_distance": 900,
"route": {
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"properties": {
"timestamp": 1561185522000
},
"geometry": {
"type": "Point",
"coordinates": [
53.590923,
9.905196
]
}
},
{
"type": "Feature",
"properties": {
"timestamp": 1561185677000
},
"geometry": {
"type": "Point",
"coordinates": [
53.590606,
9.90561
]
}
}
]
},
"accuracy": 20,
"start_time": 1561185512000,
"end_time": 1561185647000
}
]
}
}
Status Changes
The status of the inventory of vehicles available for customer use.
The status changes endpoint allows a user to query the historical availability for a system within a time range.
HTTP Request
GET https://platform.tier-services.io/mds/<zone-id>/status_changes
Query Parameters
| Parameter | Description |
|---|---|
| provider_id | A UUID for the Provider, unique within MDS |
| provider_name | The public-facing name of the Provider |
| device_id | A unique device ID in UUID format |
| vehicle_id | The Vehicle Identification Number visible on the vehicle itself |
| vehicle_type | see vehicle types table |
| propulsion_type | Array of propulsion types; allows multiple values |
| event_type | See event types table |
| event_type_reason | Reason for status change, allowable values determined by event type |
| event_time | Date/time that event occurred, based on device clock |
| event_location | |
| battery_pct | Percent battery charge of device, expressed between 0 and 1 |
| associated_trip | Trip UUID (foreign key to Trips API) required if event_type_reason is user_pick_up or user_drop_off |
Event Types
| Parameter | Description | Reason |
|---|---|---|
| available | A device becomes available for customer use | service_start |
| User ends reservation | user_drop_off | |
| Device moved for rebalancing | rebalance_drop_off | |
| Device introduced into service after being removed for maintenance | maintenance_drop_off | |
| reserved | A customer reserves a device (even if trip has not started yet) | user_pick_up |
| unavailable | A device is on the street but becomes unavailable for customer use | maintenance |
| A device is no longer available due to insufficient battery | low_battery | |
| removed | A device is removed from the street and unavailable for customer use | service_end |
| Device removed from street and will be placed at another location to rebalance service | rebalance_pick_up | |
| Device removed from street so it can be worked on | maintenance_pick_up | |
| Percent battery charge of device, expressed between 0 and 1 | battery_pct |
curl "https://platform.tier-services.io/mds/HELSINKI/status_changes?start_time=1599800103066&end_time=1599810183066&page[size]=5"
-H "x-api-key: TIER API KEY"
Click to expand JSON data response
{
"version":"0.3.0",
"data":
{"status_changes":[
{
"provider_id":"264aad41-b47c-415d-8585-0208d436516e",
"provider_name":"Tier",
"propulsion_type":
["electric"
],
"vehicle_type":"scooter",
"device_id":"cf83b844-8e9a-4176-8043-b354fe89a46e",
"vehicle_id":"265904",
"associated_trip":"815f69a5-4fdc-5fd9-a97b-c6b953569960",
"event_time":1599800119000,
"event_location": {
"type":"Feature",
"geometry":
{"type":"Point",
"coordinates":
[24.918236,60.174682]},
"properties":{
"timestamp":1599800119000}},
"event_type":"reserved",
"event_type_reason":"user_pick_up"
}
]
},
"links":{
"next":"https://platform.tier-services.io/mds/HELSINKI/status_changes?start_time=1599800119000&end_time=1599810183066&page[size]=1"
}
}
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.