Planning module

Planning a trip

/planning/inquiries

With this endpoint the user can plan the trip by submitting the starting (from) and end (to) location. If there is no useAssets given in the body this endpoint returns all vehicles in 500 meters range in the from location, otherwise it returns only the vehicles specified in the useAssets field (if it is in 50 meters range).

POST https://platform.tier-services.io/data-sharing/tier_utrecht/tomp/planning/inquiries

Request body parameters

Field	Content	Note
from	{“coordinates”: {“lat”: 51.518241, “lng”: -0.126107}}	Required. The location of the customer / start location of the trip.
to	{“coordinates”: {“lat”: 51.518241, “lng”: -0.126107}}	Optional. The end location where the customer want to end the trip. If present and there are mandatory parking zones in the city, it will automatically give back the closest parking spot in the response as a `to` parameter.
useAssets	[“123456”]	Optional. The id visible on the vehicle which the customer wants to rent directly.
radius	25	Optional. Range can be specified in case no useAsset is defined to list vehicles within the desired radius, default radius is 500 meters.

curl --location --request POST 'https://platform.tier-services.io/data-sharing/tier_utrecht/tomp/planning/offers' \
-H 'x-api-key: API_KEY' \
-H 'api-version: 1.3.0' \
-H 'maas-id: 1324A-DFB3482-32ACD' \
-H 'Accept-Language: en' \
--header 'Content-Type: application/json' \
--data-raw '{
    "from": {
        "coordinates": {
            "lat": 51.518241,
            "lng": -0.126107
        }
    },
    "useAssets": ["510467"]
}'

Click to expand JSON data response

{
    "options": [
        {
            "from": {
                "coordinates": {
                    "lng": -0.128995,
                    "lat": 51.520224
                }
            },
            "legs": [
                {
                    "from": {
                        "coordinates": {
                            "lng": -0.128995,
                            "lat": 51.520224
                        }
                    },
                    "assetType": {
                        "id": "tier-escooter",
                        "assetClass": "OTHER",
                        "assetSubClass": "escooter",
                        "sharedProperties": {
                            "propulsion": "ELECTRIC",
                            "fuel": "ELECTRIC"
                        }
                    },
                    "asset": {
                        "id": {vehicle_id},
                        "isDisabled": false,
                        "isReserved": false,
                        "overriddenProperties": {
                            "propulsion": "ELECTRIC",
                            "location": {
                                "coordinates": {
                                    "lat": 51.520224,
                                    "lng": -0.128995
                                }
                            },
                            "stateOfCharge": 49
                        }
                    },
                    "to": {
                        "coordinates": {
                            "lat": 51.517645,
                            "lng": -0.128196
                        }
                    }
                }
            ],
            "to": {
                "coordinates": {
                    "lat": 51.517645,
                    "lng": -0.128196
                }
            }
        },
    ],
    "validUntil": "2022-02-25T09:17:13.170+00:00"
},

Error Responses

When planning a trip by vehicle codes or locations you may encounter a 400 error response.

400 Bad Request Error

400 means that the validation of the request body has failed. For this endpoint we validate the request body for the presence of the from parameter and the length of the useAssets field (cannot have more than 1 item).

Click to expand JSON data response

{
    "message": "body.useAssets should NOT have more than 1 items",
    "errorCode": 2001,
    "statusCode": 400,
    "name": "BadRequestError"
}