The following endpoints describe the use case of fetching vehicles that can be rented during operating hours.

Note that this endpoint still uses non-json-api compatible layout for backwards compatibility.

Vehicle ID (UUID) and Vehicle Code

Like most entities in the TIER system, the vehicle is referred to by UUID. This guarantees that the ID is completely unique and cannot be mistaken with an ID of another entity (such as a rental).

The vehicle code on the other hand is a human-readable identifier that is generated when entering a new scooter into our system. It is both written on the vehicle handlebar and encoded inside the QR code.

You can retrieve the vehicle id (UUID) by vehicle code.

UUID example: 0160376e-d00a-4d47-8419-81c47c8855f3
Vehicle code example: 10050

QR-Code Formats

The QR-Code contains the so-called vehicle code, which is a code made of two letters, followed by multiple numbers, e.g. AB123456. There are multiple ways this vehicle code is encoded in the QR-Code.

There are 2 letters e.g. AB that represents the vehicle type and model, and 123456 is the vehicle number with 5 or more digits.

Currently there are the following QR-Code formats, slightly differing between vehicle types.

QR-Code Formats

Deep linking

Deep links are a type of link that, when clicked on or redirected to, sends users directly into the TIER app. TIER allows deep linking to select a specific vehicle for Android and iOS. Below, you find the encoded version of the deep link which is needed to ensure correct vehicle attribution.

Example deep link https://97uq.adj.st/vehicle/?adjust_t=a4w647e&adjust_deeplink=tier%3A%2F%2Fselect%3Fvehicle_code%3D10273%26vehicle_id%3D1234-45346-fefefefefef-3428743-435437%26attribution%3Dpartner_x

Parts of the URL

Embedded URL

adjust_deeplink contains another URL: tier%3A%2F%2Fselect%3Fvehicle_code%3D10273%26vehicle_id%3D1234-45346-fefefefefef-3428743-435437%26attribution%3Dpartner_x

Parts of the embedded URL

Query Parameters

What happens on Android:

1. User clicks on the deep link
2. Browser opens
3. Request hits Adjust server
4. Adjust server redirects the request to ‘adjust_deeplink’
5. Two scenarios
   1. If the TIER app is not installed on the device the Play Store opens
   2. If the TIER app is installed on the device, the Android system detects that the browser tries to open a tier:// URL
6. TIER app opens with the embedded URL passed to as a parameter

What happens on iOS:

1. User clicks on the deep link
2. The iOS system detects that a URL with host name 97uq.adj.st should be opened
3. Two scenarios
   1. If the TIER app is not installed on the device, the app opens in the App Store
   2. If the TIER app is installed on the device, it opens with the deep link passed to as a parameter

For iOS, TIER is using universal links, not custom URL schemes as strongly recommended by Apple. Find more information here.

Fetching and Caching Vehicles

Rate Limiting

Our vehicle endpoints are rate limited, so we recommend for all integrations to limit the number of requests made instead of hitting the limit. Our general recommendation is to make a maximum of one concurrent request to fetch vehicles per zone. Furthermore it is recommended not to perform more than 1 request per zone per second. This ensures constant load on TIER side instead of bursts of requests.

Caching

All integrations should cache or store vehicle list and zone list information instead of just forwarding the request to the TIER servers directly. For fetching guaranteed up-to-date vehicle details for a single vehicle - e.g. upon user selection on a map screen - forwarding the request to TIER servers is fine.

Get All available Vehicles within a Range

This endpoint gets vehicles by geolocation (latitude and longitude). Vehicles can be from multiple zones in this mode, so you can also filter by zone at the same time (recommended).

Each vehicle has a isRentable flag. If set to true this vehicle is currently available for rental. By default, only vehicles that have isRentable set to true will be returned from the endpoint. However, when requesting individual vehicles from the detail endpoint, every vehicle can be requested, no matter if they have isRentable set to true or not.

HTTP Request

GET https://platform.tier-services.io/v1/vehicle?lat=48.1&lng=16.3&radius=5000

Query Parameters

curl "https://platform.tier-services.io/v1/vehicle?lat=48.1&lng=16.3&radius=5000&zoneId=VIENNA"
  -H "x-api-key: TIER API KEY"

    {
      "data": [
        {
          "type": "vehicle",
          "id": "0160376e-d00a-4d47-8419-81c47c8855f3",
          "attributes": {
            "state": "ACTIVE",
            "lastLocationUpdate": "2019-04-02T14:23:02Z",
            "lastStateChange": "2019-04-02T05:20:47Z",
            "batteryLevel": 95,
            "currentRangeMeters": 10000,
            "lat": 48.213553,
            "lng": 16.382606,
            "maxSpeed": 20,
            "zoneId": "VIENNA",
            "code": 10050,
            "isRentable": true,
            "iotVendor": "okai",
            "licencePlate": "216GXI",
            "vehicleType": "escooter"
          }
        }
      ]
    }

Get All available Vehicles in a Zone

This endpoint retrieves all the vehicles which are currently available for rent. You must provide a zoneId to retrieve vehicles.

The vehicle type emoped and ebicycle is included in /v2/vehicle, however not in /v1/vehicle.

For v2/vehicle, please refer to the documentation of version 2.

ℹ Your API key may be limited to getting vehicles in certain zones only.

HTTP Request

GET https://platform.tier-services.io/v1/vehicle?zoneId=BERLIN

Query Parameters

curl "https://platform.tier-services.io/v1/vehicle?zoneId=BERLIN"
  -H "x-api-key: TIER API KEY"

    {
        "data": [
            {
                "type": "vehicle",
                "id": "d08a1672-8718-4c22-851f-6b51a2f9d41c",
                "attributes": {
                    "state": "ACTIVE",
                    "lastLocationUpdate": "2020-04-15T22:59:07Z",
                    "lastStateChange": "2020-04-15T20:34:42Z",
                    "batteryLevel": 97,
                    "currentRangeMeters": 10000,
                    "lat": 52.480153,
                    "lng": 13.416981,
                    "maxSpeed": 20,
                    "zoneId": "BERLIN",
                    "code": 249930,
                    "iotVendor": "okai",
                    "licencePlate": "622WSK",
                    "isRentable": true,
                    "vehicleType": "escooter"
                }
            },
        ]
    }

Get available Vehicles by Code

The vehicle code is the number (currently 5 or 6 digits) that is encoded in the vehicle QR-code which is attached to the handlebar. Use this endpoint to retrieve a vehicle by its code.

HTTP Request

GET https://platform.tier-services.io/v1/vehicle/code/12345

Query Parameters

curl "https://platform.tier-services.io/v1/vehicle/code/10050"
  -H "x-api-key: TIER API KEY"

    {
      "data": [
        {
          "type": "vehicle",
          "id": "0160376e-d00a-4d47-8419-81c47c8855f3",
          "attributes": {
            "state": "ACTIVE",
            "lastLocationUpdate": "2019-04-02T14:23:02Z",
            "lastStateChange": "2019-04-02T05:20:47Z",
            "batteryLevel": 95,
            "currentRangeMeters": 10000,
            "lat": 48.213553,
            "lng": 16.382606,
            "maxSpeed": 20,
            "zoneId": "VIENNA",
            "code": 10050,
            "isRentable": true,
            "iotVendor": "okai",
            "licencePlate": "216GXI",
            "vehicleType": "escooter"
          }
        },
      ]
    }

Get available Vehicles by UUID

The UUID is a randomly generated version 4-UUID in form of a 36 character string. It is the unique identifier that we assign to a vehicle. Use this endpoint to retrieve a vehicle by its UUID.

HTTP Request

GET https://platform.tier-services.io/v1/vehicle/<UUID>

Query Parameters

The UUID is an identifier asserted to a variety of elements, e.g. vehicles or rentals to bind and convey information as the current location or battery level within our services. It is used for all tech-side information transfer and guaranteed to be unique. The vehicle code on the other hand is a human readable identifier that is generated when entering a new scooter into our system. It is both mounted to the vehicle bar and inside the QR code. When retrieving a vehicle by this code, a UUID is generated for this request that does not only entail the vehicle code but also other live data.

Error Responses

When getting vehicles by code or by UUID, you may encounter 403 or 404 error responses, even though you were able to get information about these vehicle before. There are multiple reasons for this:

404 Errors

404 Error codes mean that the vehicle does not exist anymore in the fleet. There are many reasons why a vehicle is not part of the fleet anymore, but the most common ones are the following: It might have been removed because of old age or it might have gotten a replacement IoT, which will register the vehicle under a new code and UUID.

403 Errors

The vehicle was most likely moved to another zone which is not accessible using your API credentials. E.g. a vehicle was existing in BERLIN before is now in LONDON, but your API key may only access BERLIN.

curl "https://platform.tier-services.io/v1/vehicle/0160376e-d00a-4d47-8419-81c47c8855f3"
  -H "x-api-key: TIER API KEY"

    {
      "data": [
        {
          "type": "vehicle",
          "id": "0160376e-d00a-4d47-8419-81c47c8855f3",
          "attributes": {
            "state": "ACTIVE",
            "lastLocationUpdate": "2019-04-02T14:23:02Z",
            "lastStateChange": "2019-04-02T05:20:47Z",
            "batteryLevel": 95,
            "currentRangeMeters": 10000,
            "lat": 48.213553,
            "lng": 16.382606,
            "maxSpeed": 20,
            "zoneId": "VIENNA",
            "code": 10050,
            "isRentable": true,
            "iotVendor": "okai",
            "licencePlate": "216GXI",
            "vehicleType": "escooter"
          }
        },
      ]
    }

Make a vehicle flash and ring

Use this endpoint to make the lights of a vehicle flash and so you can locate it more easily. While using this endpoint you will also activate the ring function of the scooter. Flashing and ringing are always connected. The vehicle id is needed. Note that you may only flash the lights of vehicles that are not currently rented and located in a zone that you may access with your API key. Do not forget to remove the Content-Type header as the request body is empty in this case.

HTTP Request

POST https://platform.tier-services.io/v1/vehicle/<vehicle-id>/flash

Flashing-specific error codes

The Tier API can respond with the following vehicle specific error codes when making a vehicle flash:

Flashing-specific error codes

curl "https://platform.tier-services.io/v1/vehicle/0160376e-d00a-4d47-8419-81c47c8855g3/flash"
  -X POST
  -H "x-api-key: TIER API KEY"

• The command to make a vehicle flash returns a JSON structured like this if you are unauthorized to send this request (click ▶ button )

    {
        "errors": [
            {
                "code": "AuthenticationError",
                "title": "No authentication details provided",
                "status": "401"
            }
        ]
    }

Track scan of vehicle at location

In case a vehicle is assumed to be lost because the GPS location is inaccurate, scanning the code will transfer the current location of the customer or ranger (person that is searching the vehicle for pick-up) to correct the vehicle information.

Using this endpoint, you can track the scan of a vehicle at a certain location.

You must send the location of the user scanning the scooter using the lat and lng parameters.

HTTP Request

POST https://platform.tier-services.io/v1/vehicle/code/<code>/scanned

Request Body

curl "https://platform.tier-services.io/v1/vehicle/code/102988/scanned"
  -X POST
  -H "x-api-key: TIER API KEY"
  -d '{
        lat: 52,
        lng: 13.2,
      }'

The above command returns no body