Link Search Menu Expand Document

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/v1 will 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.