Link Search Menu Expand Document

⚠️ DRAFT: some endpoints might not be implemented yet or are experimental

This following section describes the geographical representation about how TIER is operating and will describe 3 key concepts:

RootZone

A RootZone identifies a city in which TIER is operating e.g Berlin.

Payload

A RootZone is specified following the GeoJSON Point feature standard.

{
  "id": "40cfe9ed-5844-4e5c-9412-518c51a21201",
  "type": "Feature",
  "geometry": {
    "type": "Point",
    "coordinates": [13.404954, 52.520008]
  },
  "properties": {
    "name": "Berlin",
    "country": "GERMANY",
    "timezone": "Europe/Berlin",
    "legacyId": "BERLIN",
    "createdAt": "2022-03-17T14:17:48.164Z",
    "updatedAt": "2022-08-15T10:01:40.004Z"
  }
}

Properties

Property Description Type Format
id Unique identifier string uuid
geometry Center point object GeoJSON Point
properties.name City name string  
properties.country Country name string  
properties.timezone Time zone string  
properties.legacyId Legacy id from v1 (deprecated) string  
properties.createdAt Creation date string ISO8601
properties.updatedAt Updated date string ISO8601

Get by id

GET https://platform.tier-services.io/v2/zone/root/:id

curl "https://platform.tier-services.io/v2/zone/root/40cfe9ed-5844-4e5c-9412-518c51a21201"
  -H "x-api-key: TIER API KEY"

This endpoint retrieves a RootZone by id.

Path parameters

Parameter Description Type Format
id RootZone identifier string uuid

Responses

Http status Description
200 A RootZone
404 RootZone does not exists

Get all RootZones

GET https://platform.tier-services.io/v2/zone/root

curl "https://platform.tier-services.io/v2/zone/root"
  -H "x-api-key: TIER API KEY"

This endpoint retrieves a feature collection with all the RootZones.

Responses

Http status Description
200 A FeatureCollection of RootZone

Get all RootZones near a specific location

GET https://platform.tier-services.io/v2/zone/root?lat=:lat&lng=:lng

curl "https://platform.tier-services.io/v2/zone/root?lat=52.520008&lng=13.404954"
  -H "x-api-key: TIER API KEY"

This endpoint retrieves a feature collection of RootZone which business area(s) intersect within a radius of 50km of the provided location.
The results given are in descending order starting from the closest to the farthest RootZone related to the provided location.

Query parameters

Parameter Description Type
lat Latitude float
lng Longitude float

Responses

Http status Description
200 A FeatureCollection of RootZone

Geometry

💡 The concept of Geometry is following and extending the MDS Geography specification.

A Geometry is a geographical representation of certain area of a RootZone to describe a certain application in the context of mobility.

Payload

A Geometry is specified following the GeoJSON Polygon feature standard.

{
  "id": "9efa462e-7f66-4358-8d01-0985ba164b7c",
  "type": "Feature",
  "geometry": {
    "type": "Polygon",
    "coordinates": [
      [
        [
          13.412957489490509,
          52.52215685757471
        ],
        [
          13.412697315216064,
          52.52222050562119
        ],
        [
          13.41240495443344,
          52.522029561205
        ],
        [
          13.412447869777678,
          52.521819031784105
        ],
        [
          13.41295212507248,
          52.521794551553384
        ],
        [
          13.413113057613373,
          52.521941432732994
        ],
        [
          13.412957489490509,
          52.52215685757471
        ]
      ]
    ]
  },
  "properties": {
    "name": "Alexanderplatz",
    "rootZoneId": "40cfe9ed-5844-4e5c-9412-518c51a21201",
    "center": [13.371446, 52.532029],
    "type": "business",
    "createdAt": "2022-03-17T14:17:48.164Z",
    "updatedAt": "2022-08-15T10:01:40.004Z"
  }
}

Properties

Property Description Type Format
id Unique identifier string uuid
geometry Polygon object GeoJSON Polygon
properties.name City name string  
properties.rootZoneId RootZone identifier string uuid
properties.center Center point inside the polygon float[] [lng, lat]
properties.type Type string business, policy, warehouse
properties.createdAt Creation date string ISO8601
properties.updatedAt Updated date string ISO8601

Types

  • business describes an area where TIER is operating
  • policy describes an area where GeoRules could be in effect
  • warehouse describes an area where vehicles are put into maintenance

Get all Geometry of a RootZone

GET https://platform.tier-services.io/v2/zone/root/:id/geometry

curl "https://platform.tier-services.io/v2/zone/root/40cfe9ed-5844-4e5c-9412-518c51a21201/geometry"
  -H "x-api-key: TIER API KEY"

This endpoint retrieves a FeatureCollection of Geometry for a given RootZone.

Path parameters

Parameter Description Type Format
id Unique identifier string uuid

Query parameters

Parameter Description Type Format
type (optional) Filter by type string business, policy, warehouse

Responses

Http status Description
200 A FeatureCollection of Geometry

Get a Geometry by id

GET https://platform.tier-services.io/v2/zone/geometry/:id

curl "https://platform.tier-services.io/v2/zone/geometry/9efa462e-7f66-4358-8d01-0985ba164b7c"
  -H "x-api-key: TIER API KEY"

This endpoint retrieve a single Geometry.

Path parameters

Parameter Description Type Format
id Unique identifier string uuid

Responses

Http status Description
200 A Geometry
404 Geometry does not exists

GeoRule

💡 The concept of GeoRule is following and extending the MDS Policy specification.

A GeoRule defines the application context of a Geometry and applies to a certain set of vehicle types.
A GeoRule is assigned to only one Geometry and RootZone.
A Geometry can have zero to many GeoRule.

Payload

A GeoRule is specified following the JSONApi standard.

{
  "id": "f7eea649-93ae-4f0f-b30a-1f5b378c2a14",
  "type": "geo-rule",
  "attributes": {
    "name": "Parking rule for Alexanderplatz",
    "geometryId": "9efa462e-7f66-4358-8d01-0985ba164b7c",
    "rootZoneId": "40cfe9ed-5844-4e5c-9412-518c51a21201",
    "spec": "parking",
    "vehicleTypes": null,
    "value": null,
    "minimum": null,
    "maximum": null,
    "createdAt": "2022-02-24T10:47:29.402Z",
    "updatedAt": "2022-02-24T10:47:29.402Z"
  }
}

Common properties

Property Description Type Format
id Unique identifier string uuid
attributes.name Rule name string  
attributes.geometryId Geometry identifier string uuid
attributes.rootZoneId RootZone identifier string uuid
attributes.spec Specification string  
attributes.vehicleTypes Vehicle types null or string[] ["escooter", "ebicycle"]
attributes.createdAt Creation date string ISO8601
attributes.updatedAt Updated date string ISO8601

Vehicle Types

The property vehicleTypes outputs which vehicle type a GeoRule is applied to:

  • applies to all vehicle types if the value is null e.g. "vehicleTypes": null
  • applies to a certain set of vehicle types if specified e.g. "vehicleTypes": ["escooter", "ebicycle"]

Specs

Parking

A GeoRule of spec parking defines an area where a vehicle is allowed to park.
The property maximum, defines the maximum capacity of an area allowing a certain maximum amount of vehicles to be parked inside.
Customers are allowed to end their ride only in those specific areas.
Applies to Geometry of type policy only.

Example

{
  "id": "f7eea649-93ae-4f0f-b30a-1f5b378c2a14",
  "type": "geo-rule",
  "attributes": {
    "name": "Parking rule for Alexanderplatz",
    "geometryId": "9efa462e-7f66-4358-8d01-0985ba164b7c",
    "rootZoneId": "40cfe9ed-5844-4e5c-9412-518c51a21201",
    "spec": "parking",
    "vehicleTypes": null,
    "value": null,
    "minimum": null,
    "maximum": 5,
    "createdAt": "2022-02-24T10:47:29.402Z",
    "updatedAt": "2022-02-24T10:47:29.402Z"
  }
}

No Parking

A GeoRule of spec no-parking defines an area where a vehicle cannot be parked.
Customers are not allowed to end their ride in these specific areas.
Applies to Geometry of type policy only.

Example

{
  "id": "f7eea649-93ae-4f0f-b30a-1f5b378c2a14",
  "type": "geo-rule",
  "attributes": {
    "name": "No parking rule for Alexanderplatz",
    "geometryId": "9efa462e-7f66-4358-8d01-0985ba164b7c",
    "rootZoneId": "40cfe9ed-5844-4e5c-9412-518c51a21201",
    "spec": "no-parking",
    "vehicleTypes": null,
    "value": null,
    "minimum": 0,
    "maximum": 0,
    "createdAt": "2022-02-24T10:47:29.402Z",
    "updatedAt": "2022-02-24T10:47:29.402Z"
  }
}

Reduced Speed

A GeoRule of spec reduced-speed defines an area where vehicles are allowed to ride up to a certain speed.
The property maximum defines the maximum speed.
Applies to Geometry of type policy only.

Example

{
  "id": "f7eea649-93ae-4f0f-b30a-1f5b378c2a14",
  "type": "geo-rule",
  "attributes": {
    "name": "Reduced speed rule for Alexanderplatz",
    "geometryId": "9efa462e-7f66-4358-8d01-0985ba164b7c",
    "rootZoneId": "40cfe9ed-5844-4e5c-9412-518c51a21201",
    "spec": "reduced-speed",
    "vehicleTypes": null,
    "value": null,
    "minimum": null,
    "maximum": 5,
    "createdAt": "2022-02-24T10:47:29.402Z",
    "updatedAt": "2022-02-24T10:47:29.402Z"
  }
}

No Go / Prohibited

A GeoRule of spec no-go defines an area where a vehicle is not allowed to ride.
Customers are not allowed to park in these areas and the speed is reduced to the absolute minimum supported by the vehicle’s IoT.
Only applies to Geometry of type policy.

Example

{
  "id": "f7eea649-93ae-4f0f-b30a-1f5b378c2a14",
  "type": "geo-rule",
  "attributes": {
    "name": "No go rule for Alexanderplatz",
    "geometryId": "9efa462e-7f66-4358-8d01-0985ba164b7c",
    "rootZoneId": "40cfe9ed-5844-4e5c-9412-518c51a21201",
    "spec": "no-go",
    "vehicleTypes": null,
    "value": null,
    "minimum": null,
    "maximum": 2,
    "createdAt": "2022-02-24T10:47:29.402Z",
    "updatedAt": "2022-02-24T10:47:29.402Z"
  }
}

Parking Mode

A GeoRule of spec parking-mode identifies the parking mode of the business area:

  • anywhere: customers are allowed to end their rides everywhere except for inside no-parking areas.
  • mandatory: customers have to end their rides inside parking areas.

Only applies to Geometry of type business.

Example

{
  "id": "f7eea649-93ae-4f0f-b30a-1f5b378c2a14",
  "type": "geo-rule",
  "attributes": {
    "name": "Parking rule for Alexanderplatz",
    "geometryId": "9efa462e-7f66-4358-8d01-0985ba164b7c",
    "rootZoneId": "40cfe9ed-5844-4e5c-9412-518c51a21201",
    "spec": "parking-mode",
    "vehicleTypes": null,
    "value": "anywhere",
    "minimum": null,
    "maximum": null,
    "createdAt": "2022-02-24T10:47:29.402Z",
    "updatedAt": "2022-02-24T10:47:29.402Z"
  }
}

Get all GeoRules of a RootZone

GET https://platform.tier-services.io/v2/zone/root/:id/geo-rule

curl "https://platform.tier-services.io/v2/zone/root/40cfe9ed-5844-4e5c-9412-518c51a21201/geo-rule"
  -H "x-api-key: TIER API KEY"

This endpoint retrieve a list of GeoRule for a given RootZone.

Path parameters

Parameter Description Type Format
id RootZone identifier string uuid

Query parameters

Parameter Description Type Format
spec (optional) Filter by spec string parking, no-parking, reduced-speed, no-go, parking-mode

Responses

Http status Description
200 A list of GeoRule

Get all GeoRules of a Geometry

GET https://platform.tier-services.io/v2/zone/geometry/:id/geo-rule

curl "https://platform.tier-services.io/v2/zone/geometry/9efa462e-7f66-4358-8d01-0985ba164b7c/geo-rule"
  -H "x-api-key: TIER API KEY"

This endpoint retrieves a list of GeoRule for a given Geometry.

Path parameters

Parameter Description Type Format
id Geometry identifier string uuid

Query parameters

Parameter Description Type Format
spec (optional) Filter by spec string parking, no-parking, reduced-speed, no-go, parking-mode

Responses

Http status Description
200 A list of GeoRule

Geometry + GeoRule

It is possible to retrieve a Geometry combined with its GeoRule

Get all Geometry + GeoRule of a RootZone

GET https://platform.tier-services.io/v2/zone/root/:id/geometry+rule

curl "https://platform.tier-services.io/v2/zone/root/40cfe9ed-5844-4e5c-9412-518c51a21201/geometry+rule"
  -H "x-api-key: TIER API KEY"

This endpoint retrieve a FeatureCollection of Geometry for a given RootZone.

Path parameters

Parameter Description Type Format
id RootZone identifier string uuid

Query parameters

Parameter Description Type Format
type (optional) Filter by type string business, policy, …
spec (optional) Filter by spec string parking, no-parking, …

Responses

Http status Description
200 A FeatureCollection of geometries+rules

Payload 

{
  "type": "Feature",
  "geometry": {
    "type": "Polygon",
    "coordinates": [
      [
        [
          13.412957489490509,
          52.52215685757471
        ],
        [
          13.412697315216064,
          52.52222050562119
        ],
        [
          13.41240495443344,
          52.522029561205
        ],
        [
          13.412447869777678,
          52.521819031784105
        ],
        [
          13.41295212507248,
          52.521794551553384
        ],
        [
          13.413113057613373,
          52.521941432732994
        ],
        [
          13.412957489490509,
          52.52215685757471
        ]
      ]
    ]
  },
  "properties": {
    "id": "9efa462e-7f66-4358-8d01-0985ba164b7c",
    "name": "Alexanderplatz",
    "rootZoneId": "40cfe9ed-5844-4e5c-9412-518c51a21201",
    "center": [13.371446, 52.532029],
    "type": "business",
    "rules": [
      {
        "id": "f7eea649-93ae-4f0f-b30a-1f5b378c2a14",
        "type": "geo-rule",
        "attributes": {
          "name": "No parking rule for Alexanderplatz",
          "geometryId": "9efa462e-7f66-4358-8d01-0985ba164b7c",
          "rootZoneId": "40cfe9ed-5844-4e5c-9412-518c51a21201",
          "spec": "no-parking",
          "vehicleTypes": null,
          "value": null,
          "minimum": 0,
          "maximum": 0,
          "createdAt": "2022-02-24T10:47:29.402Z",
          "updatedAt": "2022-02-24T10:47:29.402Z"
        }
      }
    ],
    "createdAt": "2022-03-17T14:17:48.164Z",
    "updatedAt": "2022-08-15T10:01:40.004Z"
  }
}

Migration

from /v1/zone to /v2/zone

Get all zones by location

In /v1 it was possible to get all zones by location: GET https://platform.tier-services.io/v1/zone?lat=40&lng=-3.

With /v2 you have to first resolve the RootZone by location, then you can get all Geometry or GeoRule by root zone id.

  1. GET https://platform.tier-services.io/v2/zone/root?lat=40&lng=-3
  2. GET https://platform.tier-services.io/v2/zone/root/40cfe9ed-5844-4e5c-9412-518c51a21201/geometry
  3. GET https://platform.tier-services.io/v2/zone/root/40cfe9ed-5844-4e5c-9412-518c51a21201/geo-rule
  4. OR GET https://platform.tier-services.io/v2/zone/root/40cfe9ed-5844-4e5c-9412-518c51a21201/geometry+rule

v1 VS v2 payload

RootZone

v1

{
  "id": "BERLIN",
  "type": "zone",
  "attributes": {
    "name": "Berlin",
    "country": "GERMANY",
    "lat": 52.520008,
    "lng": 13.404954,
    "polygon": null,
    "parentId": null,
    "parkingMode": null,
    "zoneConstraints": null,
    "zoneType": "root"
  }
}

v2

{
  "id": "40cfe9ed-5844-4e5c-9412-518c51a21201",
  "type": "Feature",
  "geometry": {
    "type": "Point",
    "coordinates": [13.404954, 52.520008]
  },
  "properties": {
    "name": "Berlin",
    "country": "GERMANY",
    "timezone": "Europe/Berlin",
    "legacyId": "BERLIN",
    "createdAt": "2019-05-21T10:00:29.000Z",
    "updatedAt": "2022-08-29T10:34:57.130Z"
  }
}

Business Zone

v1

{
  "type": "zone",
  "id": "BERLIN-BA-MAIN-SUMMER-2021-PART-7",
  "attributes": {
    "name": "BA Main Summer 2021 Part 7",
    "country": null,
    "lat": 52.511199,
    "lng": 13.378132,
    "polygon": [
      { "lng": 13.39515, "lat": 52.439812 }
      // ... 
    ],
    "parentId": "BERLIN",
    "parkingMode": "PARKING_ANYWHERE",
    "zoneConstraints": null,
    "zoneType": "business"
  }
}

v2

{
  "id": "396c7274-c160-49a9-b7b0-fd21b977b056",
  "type": "Feature",
  "geometry": {
    "type": "Polygon",
    "coordinates": [[
      [13.39515, 52.439812]
      // ...
    ]]
  },
  "properties": {
    "name": "BA Main Summer 2021 Part 7",
    "rootZoneId": "40cfe9ed-5844-4e5c-9412-518c51a21201",
    "center": [13.3781324357149, 52.51119909179856],
    "type": "business",
    "createdAt": "2021-06-23T13:48:25.000Z",
    "updatedAt": "2022-09-07T00:58:48.547Z",
    "rules": [
      {
        "id": "edcdba8c-bd99-4899-887d-b27d4f74eadf",
        "name": "Parking mode rule for BA Main Summer 2021 Part 7",
        "spec": "parking-mode",
        "geometryId": "396c7274-c160-49a9-b7b0-fd21b977b056",
        "rootZoneId": "40cfe9ed-5844-4e5c-9412-518c51a21201",
        "value": "anywhere",
        "vehicleTypes": ["ebicycle", "emoped", "escooter"],
        "minimum": null,
        "maximum": null,
        "createdAt": "2022-02-24T11:01:24.546Z",
        "updatedAt": "2022-09-07T00:58:48.590Z"
      }
    ]
  }
}

Parking zone

v1

{
  "id": "BERLIN-HUFELANDWEGVIRCHOWWEG-PARKPLATZ-10117-BERLIN",
  "type": "zone",
  "attributes": {
    "name": "Hufelandweg/Virchowweg (Parkplatz), 10117 Berlin",
    "country": null,
    "lat": 52.527819,
    "lng": 13.376627,
    "polygon": [
      { "lng": 13.376308, "lat": 52.527868 }
      // ...
    ],
    "parentId": "BERLIN",
    "parkingMode": null,
    "zoneConstraints": null,
    "zoneType": "parking"
  }
}

v2

{
"id": "c69d7328-b5d8-4e1a-8b90-78425351dacf",
  "type": "Feature",
  "geometry": {
    "type": "Polygon",
    "coordinates": [[
      [13.376308, 52.527868]
      // ..
    ]]
  },
  "properties": {
    "name": "Hufelandweg/Virchowweg (Parkplatz), 10117 Berlin",
    "rootZoneId": "40cfe9ed-5844-4e5c-9412-518c51a21201",
    "center": [13.376627, 52.5278185],
    "type": "policy",
    "createdAt": "2022-02-24T10:47:21.386Z",
    "updatedAt": "2022-04-13T12:54:10.562Z",
    "rules": [
      {
        "id": "c51b9603-c78a-4d7a-9d6d-be488fcaa148",
        "name": "Parking rule for Hufelandweg/Virchowweg (Parkplatz), 10117 Berlin",
        "spec": "parking",
        "geometryId": "c69d7328-b5d8-4e1a-8b90-78425351dacf",
        "rootZoneId": "40cfe9ed-5844-4e5c-9412-518c51a21201",
        "value": null,
        "vehicleTypes": null,
        "minimum": null,
        "maximum": null,
        "createdAt": "2022-02-24T10:47:21.550Z",
        "updatedAt": "2022-02-24T10:47:21.550Z"
      }
    ]
  }
}

Constrained

v1

{
  "id": "BERLIN-40-NP-JUNGERNSTEG-KANAL",
  "type": "zone",
  "attributes": {
    "name": "4.0 NP Jungernsteg Kanal",
    "country": null,
    "lat": 52.532468,
    "lng": 13.297757,
    "polygon": [
      { "lng": 13.306356, "lat": 52.531581 }
      // ..
    ],
    "zoneType": "constrained",
    "parentId": "BERLIN",
    "parkingMode": null,
    "zoneConstraints": ["noParking"]
  }
}

v2

{
  "id": "b915b081-ce52-450f-9884-7501c4d3bec8",
  "type": "Feature",
  "geometry": {
    "type": "Polygon",
    "coordinates": [[
      [13.306356, 52.531581]
      // ...
    ]]
  },
  "properties": {
    "name": "4.0 NP Jungernsteg Kanal",
    "rootZoneId": "40cfe9ed-5844-4e5c-9412-518c51a21201",
    "center": [13.297757, 52.532468],
    "type": "policy",
    "createdAt": "2020-08-19T14:54:03.000Z",
    "updatedAt": "2022-06-14T10:01:38.420Z",
    "rules": [
      {
        "id": "b48a8beb-d6a4-4d93-b105-6461c96043c6",
        "name": "No parking rule for 4.0 NP Jungernsteg Kanal",
        "spec": "no-parking",
        "geometryId": "b915b081-ce52-450f-9884-7501c4d3bec8",
        "rootZoneId": "40cfe9ed-5844-4e5c-9412-518c51a21201",
        "value": null,
        "vehicleTypes": null,
        "minimum": 0,
        "maximum": 0,
        "createdAt": "2022-02-24T10:46:53.428Z",
        "updatedAt": "2022-02-24T10:46:53.428Z"
      }
    ]
  }
}

Warehouse

v1

{
  "type": "zone",
  "id": "BERLIN-HSH-WH",
  "attributes": {
    "name": "Berlin_Warehouse HSH",
    "country": null,
    "lat": 52.545151,
    "lng": 13.515941,
    "polygon": [
      { "lng": 13.515234, "lat": 52.545439 }
      // ...
    ],
    "parentId": "BERLIN",
    "parkingMode": null,
    "zoneConstraints": null,
    "zoneType": "warehouse"
  }
}

v2

{
  "id": "3ce28e51-b0cf-4270-9003-b81bdc629afc",
  "type": "Feature",
  "geometry": {
    "type": "Polygon",
    "coordinates": [[
      [13.515234474940485, 52.54543910794118]
      // ...
    ]]
  },
  "properties": {
    "name": "Berlin_Warehouse HSH",
    "rootZoneId": "40cfe9ed-5844-4e5c-9412-518c51a21201",
    "center": [13.515941095733183, 52.54515077613715],
    "type": "warehouse",
    "createdAt": "2020-05-05T16:59:24.000Z",
    "updatedAt": "2022-08-04T21:10:48.826Z",
    "rules": []
  }
}

Get all zones by types

Business

To get all business zones you have to request GET https://platform.tier-services.io/v2/zone/root/:id/geometry?type=business.

To get the parkingMode of a business area you can request the geo rules GET https://platform.tier-services.io/v2/zone/geometry/:id/geo-rule or the combined endpoint GET https://platform.tier-services.io/v2/zone/root/:id/geometry+rule?type=business.

Parking

To get all parking zones you have to request GET https://platform.tier-services.io/v2/zone/root/:id/geometry+rule?type=policy&spec=parking.

Constrained

To get all constrained zones you have to request GET https://platform.tier-services.io/v2/zone/root/:id/geometry+rule?type=policy&spec=no-parking,reduced-speed.

Warehouse

To get all warehouse zones you have to request GET https://platform.tier-services.io/v2/zone/root/:i1/geometry?type=warehouse.