Link Search Menu Expand Document

Zone explanations

Zones define the locations in which vehicles can operate. There are 4 kinds of zones:

  • Root zones
  • Business zones
  • Parking zones
  • Constrained zones
  • Warehouse zones

Each of them are identified by the property zoneType which have different meanings.

Root Zone

  • Is a zone which zoneType is root.
  • A root zone is a container for subzones.
  • A root zone is usually created for a single city, e.g. BERLIN
  • A root zone has a human-readable id that uniquely identifies it, e.g. BERLIN. Note that this id is case-sensitive.
  • A root zone has a center (lat/lng), but no shape (polygon).
  • A root zone has pricing, while the other zones do not. That means that the pricing for a certain area has to be determined using the root zone.
  • A root zone can have several subzones.
  • A root zone does not have a parentId since it is the uppermost container of zone related geo data.

Subzones

Root zones can have several types of subzones.

Subzone are associated with exactly one root zone where parentId is the root zone id.

The 4 subzone types are:

  • Business zone
  • Parking zone
  • Constrained zone
  • Warehouse zone

Business Zone

  • Is a zone which zoneType is business.
  • A business zone is a zone in which vehicles may operate.
  • A business zone has a parkingMode which can be:
    • PARKING_ANYWHERE vehicles can be parked everywhere expect inside noParking constrained zones
    • MANDATORY_PARKING vehicles have to be parked inside parking zones
  • A root zone may contain multiple business zones.
  • Vehicles outside a business zone can be slowed down to 5 km/h.
  • Vehicles cannot be parked outside the business zone, or are suggested to relocation fees.

Parking Zone

  • Is a zone which zoneType is parking.
  • A parking zone is a zone in which vehicles have to park.
  • Customers are not allowed to end their ride outside a parking zone if the underlying business zone parkingMode is MANDATORY_PARKING.

Constrained Zone

  • Is a zone which zoneType is constrained.
  • There are 2 types of constrained zones, identified by the property zoneConstraints:
    • noParking in which customers are not allowed to end their ride if the underlying business zone parkingMode is PARKING_EVERYWHERE.
    • speedReduction in which the speed is getting reduced down to 5km/h.
  • A constrained zone can have zero to many constrains e.g zoneConstraints: ["noParking", "speedReduction"]

Warehouse Zone

  • Is a zone which zoneType is warehouse.
  • Warehouse zones and business zones should not overlap
  • Vehicles inside a warehouse zone are automatically transitioned into the MAINTENANCE state, in which they cannot be rented.

Get All Zones by type

⚠️ DEPRECATED see Get All Subzones

This endpoint retrieves all the zones filtered by type. The provided coordinates describe a polygon.

HTTP Request

GET https://platform.tier-services.io/v1/zone?type=root

Query Parameters

Parameter Description
type possible types are root, business, warehouse, constrained

Types

Parameter Description
root The zone to which all other zone types are attached, e.g. BERLIN
business An area in which customers can rent a vehicle
warehouse An area in which scooters are in MAINTENANCE
constrained An area which may not allow parking or only allow reduced speed or both (may overlap with the business zone)

Your client does not need to implement additional functionality for the constrained zones. These constraints are either enforced by endpoints (e.g. parking is rejected) or by automations (e.g. speed is reduced). It is yet essential to inform your users about those areas to provide a good user experience.

The command to fetch a root zone

curl "https://platform.tier-services.io/v1/zone?type=root"
  -H "x-api-key: TIER API KEY"
Click to expand JSON data response 
    {
      "data": [
        {
          "type": "zone",
          "id": "MADRID",
          "attributes": {
            "name": "MADRID",
            "lng": -3.690478,
            "lat": 40.451744,
            "polygon": [
              {
                "lng": -3.690478,
                "lat": 40.451744
              },
              {
                "lng": -3.690084,
                "lat": 40.451697
              },
              {
                "lng": -3.690389,
                "lat": 40.452475
              },
              {
                "lng": -3.690478,
                "lat": 40.451744
              }
            ],
            "zoneType": "root",
            "parentId": "MADRID",
          }
        }
      ]
    }

The command to fetch a constrained zone

curl "https://platform.tier-services.io/v1/zone?type=constrained"
  -H "x-api-key: TIER API KEY"
Click to expand JSON data response 
      {
          "data": [
            {
                "type": "zone",
                "id": "COPENHAGEN-..",
                "attributes": {
                    "name": "..",
                    "lat": null,
                    "lng": null,
                    "polygon": [
                        {
                            "lng": 12.6127977615475,
                            "lat": 55.6843084501099
                        },
                        {
                            "lng": 12.6131518131375,
                            "lat": 55.684689497812
                        },
                        {
                            "lng": 12.6127333885312,
                            "lat": 55.6856027875078
                        },
                        {
                            "lng": 12.6127977615475,
                            "lat": 55.6843084501099
                        }
                    ],
                    "country": null,
                    "zoneType": "constrained",
                    "parentId": "COPENHAGEN",
                    "zoneConstraints": [
                        "noParking"
                    ]
                }
            }
        ]
    }

Get All Zones near a specific location

⚠️ DEPRECATED see Get All Subzones

This endpoint retrieves all the zones that limit the range of the scooter. Outside of a business zone, the speed will automatically be reduced and will only be restored once entering the business zone again. Within a business zone, there are constrained zones that limit the capability of the vehicle like maximum speed and the capability to park the vehicle. The reduced speed is currently fixed and set to 5km/h.

The provided coordinates describe a polygon.

HTTP Request

GET https://platform.tier-services.io/v1/zone?lat=40&lng=-3

Query Parameters

Parameter Description
lat Latitude to search for zones nearby
lng Longitude to search for zones nearby 
curl "https://platform.tier-services.io/v1/zone?lat=40&lng=-3"
  -H "x-api-key: TIER API KEY"
Click to expand JSON data response 
    {
      "data": [
        {
          "type": "zone",
          "id": "MADRID",
          "attributes": {
            "name": "MADRID",
            "lng": -3.690478,
            "lat": 40.451744,
            "polygon": [
              {
                "lng": -3.690478,
                "lat": 40.451744
              },
              {
                "lng": -3.690084,
                "lat": 40.451697
              },
              {
                "lng": -3.690389,
                "lat": 40.452475
              },
              {
                "lng": -3.690478,
                "lat": 40.451744
              }
            ],
            "zoneType": "root",
            "parentId": null,
          }
        }
      ]
    }

Get All Subzones by Root Zone

This endpoint retrieves all the zones for a specific root zone.

HTTP Request

GET https://platform.tier-services.io/v1/zone/BERLIN/subzone

Query Parameters

Parameter Description
type possible types are business, parking, constrained, warehouse
multimodality boolean, default: false

Types

Parameter Description
business An area in which customers can rent a vehicle
warehouse An area in which scooters are in MAINTENANCE
constrained An area which may not allow parking or only allow reduced speed or both (may overlap with the business zone)
parking An area in which a customer can park if the underlying business zone has parkingMode MANDATORY_PARKING

Your client does not need to implement additional functionality for the constrained zones. These constraints are either enforced by endpoints (e.g. parking is rejected) or by automations (e.g. speed is reduced). It is yet essential to inform your users about those areas to provide a good user experience.

By sending ?multimodality?true the Zone attributes will be patched with a vehicleTypes attribute. This attribute can be null in case all modality applies or an array of vehicle types, e.g escooter , ebicycle if a certain modality applies.

curl "https://platform.tier-services.io/v1/zone/BERLIN/subzone?type=constrained"
  -H "x-api-key: TIER API KEY"
Click to expand JSON data response 
    {
        "data": [
            {
                "type": "zone",
                "id": "BERLIN-NO-PARKING-LANDWEHRKANAL-AN-DERTU",
                "attributes": {
                    "country": null,
                    "created": "2019-07-02T00:12:47Z",
                    "isActive": true,
                    "lat": null,
                    "lng": null,
                    "name": "No parking Landwehrkanal an derTU",
                    "parentId": "BERLIN",
                    "parkingMode": null,
                    "zoneConstraints": [
                        "noParking"
                    ],
                    "polygon": [
                        {
                            "lng": 13.33135244050834,
                            "lat": 52.5132380714958
                        },
                        {
                            "lng": 13.331255880983804,
                            "lat": 52.5136037127219
                        },
                        {
                            "lng": 13.33036538759086,
                            "lat": 52.5141782856445
                        },
                        {
                            "lng": 13.33135244050834,
                            "lat": 52.5132380714958
                        }
                    ],
                    "updated": "2019-07-23T19:43:36Z",
                    "zoneType": "constrained"
                }
            },

Retrieving a single zone

This endpoint retrieves a single zone.

HTTP Request

GET https://platform.tier-services.io/v1/zone/BERLIN

curl "https://platform.tier-services.io/v1/zone/BERLIN"
  -H "x-api-key: TIER API KEY"
Click to expand JSON data response 
    {
        "data": {
            "type": "zone",
            "id": "BERLIN",
            "attributes": {
                "name": "BERLIN",
                "lat": 52.5139,
                "lng": 13.4043,
                "polygon": null,
                "country": "Germany",
                "zoneType": "root",
                "parentId": null
            }
        }
    }

Get the opening times of a zone

To provide the highest safety to our customers we maintain our vehicles during certain times of the day. For this purpose the vehicles are made unavailable to the customers at a certain configurable time. The presented times are always local times.

Rentals of vehicles can only be started during business hours. Should a customer have a running rental, the customer will be able to finish their trip without being affected by the opening hours.

HTTP Request

GET https://platform.tier-services.io/v1/zone/BERLIN/business-hours

Path Parameters

Parameter Description
zone the name of the root zone of which the opening times are being request 
curl "https://platform.tier-services.io/v1/zone/BERLIN/business-hours"
  -H "x-api-key: TIER API KEY"
Click to expand JSON data response 
    {
        "data": {
            "type": "businesshours",
            "id": "BERLIN",
            "attributes": {
                "periods": [
                    {
                        "start": "07:00:00",
                        "end": "22:00:00"
                    }
                ]
            }
        }
    }