API docs by Redocly

Urban Sharing - TOMP API (1.0.0)

Download OpenAPI specification:

Urban Sharing Support: info@urbansharing.com URL: https://www.urbansharing.com

TOMP (Transport Operator Mobility Platform) API - A subset of the TOMP standard endpoints

Bookings

Create One-Stop Booking

Returns a booking for the given travel plan. This endpoint executes POST /planning/offers and POST /booking in one blow, the information provided should lead to only one possible offer, that is booked directly. The returned booking is still in PENDING state, you have to commit it. Unless 'AUTO_COMMIT' process identifier is applied. In that case the booking is in state 'CONFIRMED'.

Authorizations:
bearer
header Parameters
On-Behalf-Of
string

When the request is made from or by an end-user, this header must contain a unique value identifying that end-user.

Presence of this header on all applicable requests - even those that do not require or return user-specific information - is strongly recommended, as it informs traffic shaping and optimizations which will improve your own performance, as well as helping auditing and troubleshooting operations.

It is not a requirement that the value reveals who the end-user is to Urban Sharing, only that it is a unique and stable value per end-user.

Including the header, but with a non-unique value, will negatively impact performance.

Request Body schema: application/json
required
required
object (TompPlace)
required
object (TompCoordinates)
lng
required
number <float> >= 0
lat
required
number <float> >= 0
alt
required
number <float> >= 0

altitude, in meters above sea level

name
required
string

Human readable name of the place, could match Content-Language

required
Array of objects (TompStopReference)
Array
type
required
string
Enum: "GTFS_STOP_ID" "GTFS_STOP_CODE" "GTFS_AREA_ID" "CHB_STOP_PLACE_CODE" "CHB_QUAY_CODE" "NS_CODE"

type of external reference (GTFS, CHB).

id
required
string

this field should contain the complete ID. E.g. NL:S:13121110 or BE:S:79640040

country
required
string = 2 characters

two-letter country codes according to ISO 3166-1

stationId
required
string

reference to /operator/stations

required
object (TompAddress)
streetAddress
required
string
areaReference
required
string

city or town, principal subdivision such as province, state or county, could match Content-Language

street
required
string

street, consistent with streetAddress

houseNumber
required
number <int32> >= 0

house number, consistent with streetAddress

houseNumberAddition
required
string

the additional part of the house number (f.x. 13bis, where 'bis' is the additional part), consistent with streetAddress

addressAdditionalInfo
required
string

additional information to find the address (f.x. just around the corner)

city
required
string

specified city or town, consistent with areaReference

province
required
string

province or region, consistent with areaReference

state
required
string

state, consistent with areaReference

postalCode
required
string
country
required
string = 2 characters

two-letter country codes according to ISO 3166-1

required
object
property name*
additional property
any
required
object (TompConnectedLegInfo)
provider
required
string

the provider of the previous leg (usually a Transport Operator reference)

assetReference
required
string

the identification of the previous asset, like a flight number. This field (in case of a specific asset) or assetTypeReference must be filled.

assetTypeReference
required
string

the identification of the previous asset type, like a discount combi. This field (in case of a specific asset type) or asset reference must be filled.

radius
required
number <int32> >= 0

Maximum distance in meters a user wants to travel to reach the travel option

required
object (TompPlace)
required
object (TompCoordinates)
lng
required
number <float> >= 0
lat
required
number <float> >= 0
alt
required
number <float> >= 0

altitude, in meters above sea level

name
required
string

Human readable name of the place, could match Content-Language

required
Array of objects (TompStopReference)
Array
type
required
string
Enum: "GTFS_STOP_ID" "GTFS_STOP_CODE" "GTFS_AREA_ID" "CHB_STOP_PLACE_CODE" "CHB_QUAY_CODE" "NS_CODE"

type of external reference (GTFS, CHB).

id
required
string

this field should contain the complete ID. E.g. NL:S:13121110 or BE:S:79640040

country
required
string = 2 characters

two-letter country codes according to ISO 3166-1

stationId
required
string

reference to /operator/stations

required
object (TompAddress)
streetAddress
required
string
areaReference
required
string

city or town, principal subdivision such as province, state or county, could match Content-Language

street
required
string

street, consistent with streetAddress

houseNumber
required
number <int32> >= 0

house number, consistent with streetAddress

houseNumberAddition
required
string

the additional part of the house number (f.x. 13bis, where 'bis' is the additional part), consistent with streetAddress

addressAdditionalInfo
required
string

additional information to find the address (f.x. just around the corner)

city
required
string

specified city or town, consistent with areaReference

province
required
string

province or region, consistent with areaReference

state
required
string

state, consistent with areaReference

postalCode
required
string
country
required
string = 2 characters

two-letter country codes according to ISO 3166-1

required
object
property name*
additional property
any
estimatedDistance
required
number <int32> >= 0

instead of using the from/to construct, it is also possible to give an indication of the distance to travel. The process identifier 'USE_ESTIMATED_DISTANCE' is used to indicate this scenario. Also in meters

departureTime
required
string <date-time>

The intended departure time. If left out and no arrivalTime is set, the current time should be assumed. If only the arrival time is specified, this is an implicit request for a guaranteed arrival at that time.

arrivalTime
required
string <date-time>

The intended arrival time, at the to place. If not set, the time the user intends to stop using the asset (implicit request for arrival guarantee).

nrOfTravelers
required
number <int32> >= 1

The number of people that intend to travel, including the customer.

required
Array of objects (TompTraveler)

Extra information about the people that intend to travel if relevant, length must be less than or equal to nrOftravelers.

Array
isValidated
required
boolean

Whether this traveler's identity and properties have been verified by the MaaS provider

age
required
number <int32>

Age of the traveler, may be approximate

referenceNumber
required
string

reference number of the traveler. This number could be used to refer to in the planning result.

required
Array of objects (TompCardType)

The kind of cards this traveler possesses

required
Array of objects (TompLicenseType)

The kind of licenses this traveler possesses

required
object (TompRequirements)
knownIdentifier
required
string

identifier for this traveler in the personal data store. This identifier can be used to get personal information from the provider specified in the "knownIdentifierProvider"

knownIdentifierProvider
required
string

provider for personal information. Can be a URI or identifier.

useAssets
required
Array of strings

The specific asset(s) the user wishes to receive leg options for

userGroups
required
Array of strings

Id(s) of user groups that the user belongs to. This provides access to exclusive assets that are hidden to the public. Id's are agreed upon by TO and MP.

useAssetTypes
required
Array of strings

The specific asset type(s) the user wishes to receive leg options for

required
object

dictionary for extra fields (bilatural agreements)

property name*
additional property
any
required
object (TompCustomer)
isValidated
required
boolean

Whether this traveler's identity and properties have been verified by the MaaS provider

age
required
number <int32>

Age of the traveler, may be approximate

referenceNumber
required
string

reference number of the traveler. This number could be used to refer to in the planning result.

required
Array of objects (TompCardType)

The kind of cards this traveler possesses

Array
type
required
string
Enum: "ID" "DISCOUNT" "TRAVEL" "BANK" "CREDIT" "PASSPORT" "OTHER"

The broad category of card

subType
required
string

For use in case of OTHER. Can be used in bilateral agreements.

assetClass
required
string
Enum: "AIR" "BUS" "TROLLEYBUS" "TRAM" "COACH" "RAIL" "INTERCITYRAIL" "URBANRAIL" "METRO" "WATER" "CABLEWAY" "FUNICULAR" "TAXI" "SELFDRIVE" "FOOT" "BICYCLE" "MOTORCYCLE" "CAR" "SHUTTLE" "OTHER" "PARKING" "MOPED" "STEP" "FERRY"
acceptors
required
Array of strings

references to accepting parties, only if applicable

required
Array of objects (TompLicenseType)

The kind of licenses this traveler possesses

Array
assetClass
required
string
Enum: "AIR" "BUS" "TROLLEYBUS" "TRAM" "COACH" "RAIL" "INTERCITYRAIL" "URBANRAIL" "METRO" "WATER" "CABLEWAY" "FUNICULAR" "TAXI" "SELFDRIVE" "FOOT" "BICYCLE" "MOTORCYCLE" "CAR" "SHUTTLE" "OTHER" "PARKING" "MOPED" "STEP" "FERRY"
issuingCountry
required
string = 2 characters

two-letter country codes according to ISO 3166-1

requirements
required
object
knownIdentifier
required
string

identifier for this traveler in the personal data store. This identifier can be used to get personal information from the provider specified in the "knownIdentifierProvider"

knownIdentifierProvider
required
string

provider for personal information. Can be a URI or identifier.

id
required
string

The identifier that the TO uses to identify this customer.

externalId
required
string

The identifier that the MP uses to identify this customer. It is not mandatory to store it at the TOs side, since the communication between TO and MP always uses the identifier on TO side.

travelerReference
required
string

optional reference field to the travelers in the planning request.

initials
required
string
firstName
required
string

First name of the customer

lastName
required
string

Last name of the customer

middleName
required
string

Middle name of the customer

prefix
required
string

prefix of the customer, like titles

postfix
required
string

postfix of the customer, like titles

required
Array of objects (TompPhone)
Array
preferred
required
boolean

only one phone in this array can have a true in this property

number
required
string

phone number. In case of international usage, always provide the country code.

kind
required
string
Enum: "LANDLINE" "MOBILE"
type
required
string
Enum: "PRIVATE" "BUSINESS" "OTHER"
email
required
string

the email address of the customer

birthDate
required
string <date>
placeOfBirth
required
string <date>
countryOfBirth
required
string = 2 characters

two-letter country codes according to ISO 3166-1

required
object (TompAddress)
streetAddress
required
string
areaReference
required
string

city or town, principal subdivision such as province, state or county, could match Content-Language

street
required
string

street, consistent with streetAddress

houseNumber
required
number <int32> >= 0

house number, consistent with streetAddress

houseNumberAddition
required
string

the additional part of the house number (f.x. 13bis, where 'bis' is the additional part), consistent with streetAddress

addressAdditionalInfo
required
string

additional information to find the address (f.x. just around the corner)

city
required
string

specified city or town, consistent with areaReference

province
required
string

province or region, consistent with areaReference

state
required
string

state, consistent with areaReference

postalCode
required
string
country
required
string = 2 characters

two-letter country codes according to ISO 3166-1

photo
required
string <byte>

base64 encoded

required
Array of objects (TompCard)
Array
type
required
string
Enum: "ID" "DISCOUNT" "TRAVEL" "BANK" "CREDIT" "PASSPORT" "OTHER"

The broad category of card

cardNumber
required
string

number of the card, like ID number, credit card or bank account number

subType
required
string

For use in case of OTHER. Can be used in bilateral agreements.

assetClass
required
string
Enum: "AIR" "BUS" "TROLLEYBUS" "TRAM" "COACH" "RAIL" "INTERCITYRAIL" "URBANRAIL" "METRO" "WATER" "CABLEWAY" "FUNICULAR" "TAXI" "SELFDRIVE" "FOOT" "BICYCLE" "MOTORCYCLE" "CAR" "SHUTTLE" "OTHER" "PARKING" "MOPED" "STEP" "FERRY"
acceptors
required
Array of strings

references to accepting parties, only if applicable

cardDescription
required
string

description of the card

cardAdditionalNumber
required
string

additional number, like CVC code or IBAN code

validUntil
required
string <date>

the enddate of the card. Mandatory in case of a credit card or ID card.

country
required
string = 2 characters

two-letter country codes according to ISO 3166-1

required
Array of objects (TompLicense)
Array
assetClass
required
string
Enum: "AIR" "BUS" "TROLLEYBUS" "TRAM" "COACH" "RAIL" "INTERCITYRAIL" "URBANRAIL" "METRO" "WATER" "CABLEWAY" "FUNICULAR" "TAXI" "SELFDRIVE" "FOOT" "BICYCLE" "MOTORCYCLE" "CAR" "SHUTTLE" "OTHER" "PARKING" "MOPED" "STEP" "FERRY"
issuingCountry
required
string = 2 characters

two-letter country codes according to ISO 3166-1

number
required
string
licenseCode
required
string

in most countries a driver license has also a code. As TO you can exactly verify, based on this code if the license allows to operate it's assets, if the assetType too generic.

validUntil
required
string <date>
required
object

dictionary for extra fields (bilatural agreements)

property name*
additional property
any
callbackUrl
required
string

The callback URL of the Maas Provider, to use as base url for callback, f.x. the POST legs/{id}/events and POST /bookings/{id}/events. Only to be provided when this deviates from standard or agreed URL.

Responses

Request samples

Content type
application/json
{
  • "from": {
    },
  • "previousLegInfo": {
    },
  • "radius": 0,
  • "to": {
    },
  • "estimatedDistance": 0,
  • "departureTime": "2019-08-24T14:15:22Z",
  • "arrivalTime": "2019-08-24T14:15:22Z",
  • "nrOfTravelers": 1,
  • "travelers": [
    ],
  • "useAssets": [
    ],
  • "userGroups": [
    ],
  • "useAssetTypes": [
    ],
  • "extraInfo": { },
  • "customer": {
    },
  • "callbackUrl": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "from": { },
  • "callbackUrl": "string",
  • "to": { },
  • "customer": { },
  • "extraInfo": { },
  • "state": "NEW",
  • "legs": [
    ],
  • "pricing": { },
  • "departureTime": "2019-08-24T14:15:22Z",
  • "arrivalTime": "2019-08-24T14:15:22Z",
  • "actualDepartureTime": "2019-08-24T14:15:22Z",
  • "actualArrivalTime": "2019-08-24T14:15:22Z",
  • "mainAssetType": {
    },
  • "userCommunication": [
    ],
  • "memo": "string",
  • "extraData": {
    }
}

Get Booking

Returns the booking. See (3.5.2) in the process flow - booking. In the 'meta'-field the digital tickets can be returned (see (3.3) in the process flow - booking)

Authorizations:
bearer
path Parameters
id
required
string

Booking identifier

header Parameters
On-Behalf-Of
string

When the request is made from or by an end-user, this header must contain a unique value identifying that end-user.

Presence of this header on all applicable requests - even those that do not require or return user-specific information - is strongly recommended, as it informs traffic shaping and optimizations which will improve your own performance, as well as helping auditing and troubleshooting operations.

It is not a requirement that the value reveals who the end-user is to Urban Sharing, only that it is a unique and stable value per end-user.

Including the header, but with a non-unique value, will negatively impact performance.

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "from": { },
  • "callbackUrl": "string",
  • "to": { },
  • "customer": { },
  • "extraInfo": { },
  • "state": "NEW",
  • "legs": [
    ],
  • "pricing": { },
  • "departureTime": "2019-08-24T14:15:22Z",
  • "arrivalTime": "2019-08-24T14:15:22Z",
  • "actualDepartureTime": "2019-08-24T14:15:22Z",
  • "actualArrivalTime": "2019-08-24T14:15:22Z",
  • "mainAssetType": {
    },
  • "userCommunication": [
    ],
  • "memo": "string",
  • "extraData": {
    }
}

General

Send Booking Notification

Notification between MaaS provider and Transport operator in case of user no-show or if specific asset is not available or some other event occurs not covered by other API calls.

Authorizations:
bearer
path Parameters
id
required
string

Booking identifier

header Parameters
On-Behalf-Of
string

When the request is made from or by an end-user, this header must contain a unique value identifying that end-user.

Presence of this header on all applicable requests - even those that do not require or return user-specific information - is strongly recommended, as it informs traffic shaping and optimizations which will improve your own performance, as well as helping auditing and troubleshooting operations.

It is not a requirement that the value reveals who the end-user is to Urban Sharing, only that it is a unique and stable value per end-user.

Including the header, but with a non-unique value, will negatively impact performance.

Request Body schema: application/json
required
type
required
string
Enum: "VEHICLE_NOT_AVAILABLE" "USER_NO_SHOW" "ETA" "MESSAGE_TO_DRIVER" "MESSAGE_TO_END_USER" "USER_OUT_OF_LIMITS" "OTHER"
minutes
required
number <int32> >= 0

in case of ETA, the number of minutes until arrival at the pickup location

required
object (TompAsset)
id
required
string

Identifier of an asset. Whenever used in Operator Information changed after every trip (GDPR).

isReserved
required
boolean

true indicates the bike is currently reserved for someone else

isReservedFrom
required
string <date-time>

optional addition to determine if an asset is reserved in the future

isReservedTo
required
string <date-time>

optional addition to determine when asset is available in the future

isDisabled
required
boolean

true indicates the asset is currently disabled (broken)

availableUntil
required
string <date-time>

The date and time when any rental of the vehicle must be completed. The vehicle must be returned and made available for the next user by this time. If this field is empty, it indicates that the vehicle is available indefinitely. This field SHOULD be published by carsharing or other mobility systems where vehicles can be booked in advance for future travel.

rentalUrl
required
string

deep-linking option from GBFS+. Only added to be consistent with GBFS 2.0

rentalUrlAndroid
required
string

deep-linking option from GBFS 2.0. Only added to be consistent with GBFS 2.0

rentalUrlIOS
required
string

deep-linking option from GBFS 2.0. Only added to be consistent with GBFS 2.0

mileage
required
number <float> >= 0

the current mileage of the asset

stateOfCharge
required
number <int32> [ 0 .. 100 ]

percentage of charge available

maxRange
required
number <int32> [ 0 .. 100 ]

maximum range in meters

licensePlate
required
string

the usage of this field requires a secure environment. When assets are published in available-assets, this field can be used to track assets. Be aware of this.

stationId
required
string

reference to station_id in /operator/stations, station where it is located

homeStationId
required
string

reference to station_id in /operator/stations, station where it is assigned to

required
Array of objects (TompDamage)

List of known vehicle damages.

Array
vehicleComponent
required
string
Enum: "FRONT" "REAR" "LEFT" "RIGHT" "TOP" "BOTTOM" "INTERIOR" "TIRE" "ANCILLARY" "OTHER"

Part/Component of the vehicle affected. If OTHER is specified the description needs to provide more detail as to what part/component is affected.

description
required
string

Description of the damage.

vehicleComponentName
required
string

a short term to describe the damaged part

pictures
required
Array of strings

URL where pictures of the damage can be accessed. Any special characters in the URL must be correctly escaped.

required
object (TompAssetProperties)
name
required
string

name of asset (type), required in either assetType or asset, should match Content-Language

location
required
object
brand
required
string

brand of the asset

model
required
string
buildingYear
required
number <int32>
colour
required
string

colour of the asset, should match Content-Language

maxSpeed
required
number <int32>

the maximum allowed speed for this asset (in km/h)

wheelCount
required
number <int32> >= 0

the number of wheels

image
required
string

Link to an image of the asset

icon
required
string

Link to an icon of the asset

accessMethods
required
Array of strings
Items Enum: "DEEPLINK" "QR" "AZTEC" "TOMP-API" "AXA-EKEY-OTP" "PHYSICAL-KEY" "BARCODE" "PDF" "HTML" "OVC" "EMV" "NONE"

access method for trip execution. Data will be delivered in the response of /booking/{id}/events - COMMIT or /leg/{id}/events - PREPARE (preferred) or GET /bookings/{id}.

fuel
required
string
Enum: "NONE" "GASOLINE" "DIESEL" "ELECTRIC" "HYBRID_GASOLINE" "HYBRID_DIESEL" "HYBRID_GAS" "HYDROGEN" "GAS" "BIO_MASS" "KEROSINE" "OTHER"
propulsion
required
string
Enum: "MUSCLE" "ELECTRIC" "GASOLINE" "DIESEL" "HYBRID" "LPG" "HYDROGEN"

way in which the asset is powered

energyLabel
required
string
Enum: "A" "B" "C" "D" "E"

Energy efficiency

required
Array of objects (TompAssetPropertiesEcoLabelInner)
co2PerKm
required
number <float> >= 0
gears
required
number <int32>

number of gears of the asset

gearbox
required
string
Enum: "MANUAL" "AUTOMATIC" "SEMIAUTOMATIC"

type of gearbox

airConditioning
required
boolean

airconditioning available

cabrio
required
boolean

cabrio model

towingHook
required
boolean

towing hook available

winterTires
required
boolean

winter tires applied

nrOfDoors
required
number <int32>

the number of doors of the vehicle. Return only when applicable

nrOfHelmets
required
number <int32>

the number of available helmets. Return only when applicable

navigation
required
boolean

navigation available

cruiseControl
required
boolean

cruise control available

persons
required
number <int32> >= 1

number of persons able to use the asset

infantSeat
required
boolean

true indicates infant seat is supplied

pets
required
boolean

true indicates pets are allowed on asset

smoking
required
boolean

true indicates smoking is allowed on asset

easyAccessibility
required
string
Enum: "LIFT" "ESCALATOR" "GROUND_LEVEL" "SIGHTIMPAIRMENT" "HEARINGIMPAIRMENT" "WHEELCHAIR"

describes if asset is or needs to be easily accessible

required
Array of objects (TompRequirement)
regionId
required
string

the region where this asset or assetType is used.

cargo
required
string

describes options to carry cargo, should match Content-Language

cargoVolume
required
number <int32>

the volume in liters of the cargo

cargoLoad
required
number <int32>

the weight in kilograms of the cargo

travelAbroad
required
boolean

true indicates asset is allowed to travel abroad

undergroundParking
required
boolean

true indicates underground parking is allowed with asset

helmetRequired
required
boolean

is a helmet required to operate this asset

defaultReserveTime
required
number <int32> >= 0

Maximum time in minutes that a vehicle can be reserved before a rental begins. When a vehicle is reserved by a user, the vehicle remains locked until the rental begins. During this time the vehicle is unavailable and cannot be reserved or rented by other users. The vehicle status in free_bike_status.json MUST be set to is_reserved = true. If the value of default_reserve_time elapses without a rental beginning, the vehicle status MUST change to is_reserved = false. If default_reserve_time is set to 0, the vehicle type cannot be reserved.

other
required
string

free text to describe asset, should match Content-Language

required
object

this object can contain extra information about the type of asset. For instance values from the 'Woordenboek Reizigerskenmerken'. [https://github.com/efel85/TOMP-API/issues/17]. These values can also be used in the planning.

comment
required
string

free text, should match Content-Language

legId
required
string

whenever the booking contains multiple legs, this field is mandatory and contain the id of the leg related to the notification.

Responses

Request samples

Content type
application/json
{
  • "type": "VEHICLE_NOT_AVAILABLE",
  • "minutes": 0,
  • "asset": {
    },
  • "comment": "string",
  • "legId": "string"
}

Response samples

Content type
application/json
{
  • "errorcode": 0,
  • "type": "string",
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "instance": "string"
}

Operator Information

Describes the running implementations

All versions that are implemented on this URL are described in the result of this endpoint. It contains all versions and per version the endpoints, their status and the supported scenarios.

Authorizations:
bearer
header Parameters
On-Behalf-Of
string

When the request is made from or by an end-user, this header must contain a unique value identifying that end-user.

Presence of this header on all applicable requests - even those that do not require or return user-specific information - is strongly recommended, as it informs traffic shaping and optimizations which will improve your own performance, as well as helping auditing and troubleshooting operations.

It is not a requirement that the value reveals who the end-user is to Urban Sharing, only that it is a unique and stable value per end-user.

Including the header, but with a non-unique value, will negatively impact performance.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Available assets

Returns a list of available assets grouped by vehicle category.

Authorizations:
bearer
header Parameters
On-Behalf-Of
string

When the request is made from or by an end-user, this header must contain a unique value identifying that end-user.

Presence of this header on all applicable requests - even those that do not require or return user-specific information - is strongly recommended, as it informs traffic shaping and optimizations which will improve your own performance, as well as helping auditing and troubleshooting operations.

It is not a requirement that the value reveals who the end-user is to Urban Sharing, only that it is a unique and stable value per end-user.

Including the header, but with a non-unique value, will negatively impact performance.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Planning

Get Planning Offers

Returns bookable offers for the given travel plan. Start time can be defined, but is optional. If startTime is not provided, but required by the third party API, a default value of "Date.now()" is used. [from MaaS-API /listing]. During the routing phase this service can be used to check availability without any state changes. see (2.1) in the process flow - planning

Authorizations:
bearer
header Parameters
On-Behalf-Of
string

When the request is made from or by an end-user, this header must contain a unique value identifying that end-user.

Presence of this header on all applicable requests - even those that do not require or return user-specific information - is strongly recommended, as it informs traffic shaping and optimizations which will improve your own performance, as well as helping auditing and troubleshooting operations.

It is not a requirement that the value reveals who the end-user is to Urban Sharing, only that it is a unique and stable value per end-user.

Including the header, but with a non-unique value, will negatively impact performance.

Request Body schema: application/json
required
required
object (TompPlace)
required
object (TompCoordinates)
lng
required
number <float> >= 0
lat
required
number <float> >= 0
alt
required
number <float> >= 0

altitude, in meters above sea level

name
required
string

Human readable name of the place, could match Content-Language

required
Array of objects (TompStopReference)
Array
type
required
string
Enum: "GTFS_STOP_ID" "GTFS_STOP_CODE" "GTFS_AREA_ID" "CHB_STOP_PLACE_CODE" "CHB_QUAY_CODE" "NS_CODE"

type of external reference (GTFS, CHB).

id
required
string

this field should contain the complete ID. E.g. NL:S:13121110 or BE:S:79640040

country
required
string = 2 characters

two-letter country codes according to ISO 3166-1

stationId
required
string

reference to /operator/stations

required
object (TompAddress)
streetAddress
required
string
areaReference
required
string

city or town, principal subdivision such as province, state or county, could match Content-Language

street
required
string

street, consistent with streetAddress

houseNumber
required
number <int32> >= 0

house number, consistent with streetAddress

houseNumberAddition
required
string

the additional part of the house number (f.x. 13bis, where 'bis' is the additional part), consistent with streetAddress

addressAdditionalInfo
required
string

additional information to find the address (f.x. just around the corner)

city
required
string

specified city or town, consistent with areaReference

province
required
string

province or region, consistent with areaReference

state
required
string

state, consistent with areaReference

postalCode
required
string
country
required
string = 2 characters

two-letter country codes according to ISO 3166-1

required
object
property name*
additional property
any
required
object (TompConnectedLegInfo)
provider
required
string

the provider of the previous leg (usually a Transport Operator reference)

assetReference
required
string

the identification of the previous asset, like a flight number. This field (in case of a specific asset) or assetTypeReference must be filled.

assetTypeReference
required
string

the identification of the previous asset type, like a discount combi. This field (in case of a specific asset type) or asset reference must be filled.

radius
required
number <int32> >= 0

Maximum distance in meters a user wants to travel to reach the travel option

required
object (TompPlace)
required
object (TompCoordinates)
lng
required
number <float> >= 0
lat
required
number <float> >= 0
alt
required
number <float> >= 0

altitude, in meters above sea level

name
required
string

Human readable name of the place, could match Content-Language

required
Array of objects (TompStopReference)
Array
type
required
string
Enum: "GTFS_STOP_ID" "GTFS_STOP_CODE" "GTFS_AREA_ID" "CHB_STOP_PLACE_CODE" "CHB_QUAY_CODE" "NS_CODE"

type of external reference (GTFS, CHB).

id
required
string

this field should contain the complete ID. E.g. NL:S:13121110 or BE:S:79640040

country
required
string = 2 characters

two-letter country codes according to ISO 3166-1

stationId
required
string

reference to /operator/stations

required
object (TompAddress)
streetAddress
required
string
areaReference
required
string

city or town, principal subdivision such as province, state or county, could match Content-Language

street
required
string

street, consistent with streetAddress

houseNumber
required
number <int32> >= 0

house number, consistent with streetAddress

houseNumberAddition
required
string

the additional part of the house number (f.x. 13bis, where 'bis' is the additional part), consistent with streetAddress

addressAdditionalInfo
required
string

additional information to find the address (f.x. just around the corner)

city
required
string

specified city or town, consistent with areaReference

province
required
string

province or region, consistent with areaReference

state
required
string

state, consistent with areaReference

postalCode
required
string
country
required
string = 2 characters

two-letter country codes according to ISO 3166-1

required
object
property name*
additional property
any
estimatedDistance
required
number <int32> >= 0

instead of using the from/to construct, it is also possible to give an indication of the distance to travel. The process identifier 'USE_ESTIMATED_DISTANCE' is used to indicate this scenario. Also in meters

departureTime
required
string <date-time>

The intended departure time. If left out and no arrivalTime is set, the current time should be assumed. If only the arrival time is specified, this is an implicit request for a guaranteed arrival at that time.

arrivalTime
required
string <date-time>

The intended arrival time, at the to place. If not set, the time the user intends to stop using the asset (implicit request for arrival guarantee).

nrOfTravelers
required
number <int32> >= 1

The number of people that intend to travel, including the customer.

required
Array of objects (TompTraveler)

Extra information about the people that intend to travel if relevant, length must be less than or equal to nrOftravelers.

Array
isValidated
required
boolean

Whether this traveler's identity and properties have been verified by the MaaS provider

age
required
number <int32>

Age of the traveler, may be approximate

referenceNumber
required
string

reference number of the traveler. This number could be used to refer to in the planning result.

required
Array of objects (TompCardType)

The kind of cards this traveler possesses

required
Array of objects (TompLicenseType)

The kind of licenses this traveler possesses

required
object (TompRequirements)
knownIdentifier
required
string

identifier for this traveler in the personal data store. This identifier can be used to get personal information from the provider specified in the "knownIdentifierProvider"

knownIdentifierProvider
required
string

provider for personal information. Can be a URI or identifier.

useAssets
required
Array of strings

The specific asset(s) the user wishes to receive leg options for

userGroups
required
Array of strings

Id(s) of user groups that the user belongs to. This provides access to exclusive assets that are hidden to the public. Id's are agreed upon by TO and MP.

useAssetTypes
required
Array of strings

The specific asset type(s) the user wishes to receive leg options for

required
object

dictionary for extra fields (bilatural agreements)

property name*
additional property
any

Responses

Request samples

Content type
application/json
{
  • "from": {
    },
  • "previousLegInfo": {
    },
  • "radius": 0,
  • "to": {
    },
  • "estimatedDistance": 0,
  • "departureTime": "2019-08-24T14:15:22Z",
  • "arrivalTime": "2019-08-24T14:15:22Z",
  • "nrOfTravelers": 1,
  • "travelers": [
    ],
  • "useAssets": [
    ],
  • "userGroups": [
    ],
  • "useAssetTypes": [
    ],
  • "extraInfo": { }
}

Response samples

Content type
application/json
{
  • "validUntil": "2019-08-24T14:15:22Z",
  • "options": [
    ]
}

Support

Create Support Request

Creates a request for support from end user via MP

Authorizations:
bearer
header Parameters
On-Behalf-Of
string

When the request is made from or by an end-user, this header must contain a unique value identifying that end-user.

Presence of this header on all applicable requests - even those that do not require or return user-specific information - is strongly recommended, as it informs traffic shaping and optimizations which will improve your own performance, as well as helping auditing and troubleshooting operations.

It is not a requirement that the value reveals who the end-user is to Urban Sharing, only that it is a unique and stable value per end-user.

Including the header, but with a non-unique value, will negatively impact performance.

Request Body schema: application/json
required
id
required
string

the booking id

supportType
required
string
Enum: "BROKEN_DOWN" "NOT_AT_LOCATION" "MISSING_AFTER_PAUSE" "NOT_CLEAN" "NOT_AVAILABLE" "UNABLE_TO_OPEN" "UNABLE_TO_CLOSE" "API_TECHNICAL" "API_FUNCTIONAL" "ACCIDENT" "OTHER"
required
object (TompPlace)
required
object (TompCoordinates)
lng
required
number <float> >= 0
lat
required
number <float> >= 0
alt
required
number <float> >= 0

altitude, in meters above sea level

name
required
string

Human readable name of the place, could match Content-Language

required
Array of objects (TompStopReference)
Array
type
required
string
Enum: "GTFS_STOP_ID" "GTFS_STOP_CODE" "GTFS_AREA_ID" "CHB_STOP_PLACE_CODE" "CHB_QUAY_CODE" "NS_CODE"

type of external reference (GTFS, CHB).

id
required
string

this field should contain the complete ID. E.g. NL:S:13121110 or BE:S:79640040

country
required
string = 2 characters

two-letter country codes according to ISO 3166-1

stationId
required
string

reference to /operator/stations

required
object (TompAddress)
streetAddress
required
string
areaReference
required
string

city or town, principal subdivision such as province, state or county, could match Content-Language

street
required
string

street, consistent with streetAddress

houseNumber
required
number <int32> >= 0

house number, consistent with streetAddress

houseNumberAddition
required
string

the additional part of the house number (f.x. 13bis, where 'bis' is the additional part), consistent with streetAddress

addressAdditionalInfo
required
string

additional information to find the address (f.x. just around the corner)

city
required
string

specified city or town, consistent with areaReference

province
required
string

province or region, consistent with areaReference

state
required
string

state, consistent with areaReference

postalCode
required
string
country
required
string = 2 characters

two-letter country codes according to ISO 3166-1

required
object
property name*
additional property
any
time
required
string <date-time>
priority
required
string
Enum: "ERROR_CANNOT_CONTINUE" "ERROR_CAN_CONTINUE" "DISTURBING_ISSUE" "QUESTION" "OTHER"

the priority of the support request.

contactInformationEndUser
required
string

contact information of the end user in case of direct response requests, like phone number

comment
required
string
requestedResponseTime
required
number <double> >= 0

time to respond in minutes.

required
object (TompDamage)
vehicleComponent
required
string
Enum: "FRONT" "REAR" "LEFT" "RIGHT" "TOP" "BOTTOM" "INTERIOR" "TIRE" "ANCILLARY" "OTHER"

Part/Component of the vehicle affected. If OTHER is specified the description needs to provide more detail as to what part/component is affected.

description
required
string

Description of the damage.

vehicleComponentName
required
string

a short term to describe the damaged part

pictures
required
Array of strings

URL where pictures of the damage can be accessed. Any special characters in the URL must be correctly escaped.

urls
required
Array of strings

urls to clarify the support request e.g. pictures showing damage

assetId
required
string

the (visual) ID on the asset, to report damage on an asset that hasn't been booked.

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "supportType": "BROKEN_DOWN",
  • "location": {
    },
  • "time": "2019-08-24T14:15:22Z",
  • "priority": "ERROR_CANNOT_CONTINUE",
  • "contactInformationEndUser": "string",
  • "comment": "string",
  • "requestedResponseTime": 0.1,
  • "damage": {
    },
  • "urls": [
    ],
  • "assetId": "string"
}

Response samples

Content type
application/json
{
  • "status": "PROCESSING",
  • "timeToResolution": 9,
  • "order": 0,
  • "comment": "string",
  • "id": "string",
  • "supportType": "BROKEN_DOWN",
  • "location": {
    },
  • "time": "2019-08-24T14:15:22Z",
  • "priority": "ERROR_CANNOT_CONTINUE",
  • "contactInformationEndUser": "string",
  • "requestedResponseTime": 0.1,
  • "damage": {
    },
  • "urls": [
    ],
  • "assetId": "string"
}

Get Support Status

Gets the status report of the support request. Last status (highest order number) is the current status

Authorizations:
bearer
path Parameters
id
required
string

Booking identifier

header Parameters
On-Behalf-Of
string

When the request is made from or by an end-user, this header must contain a unique value identifying that end-user.

Presence of this header on all applicable requests - even those that do not require or return user-specific information - is strongly recommended, as it informs traffic shaping and optimizations which will improve your own performance, as well as helping auditing and troubleshooting operations.

It is not a requirement that the value reveals who the end-user is to Urban Sharing, only that it is a unique and stable value per end-user.

Including the header, but with a non-unique value, will negatively impact performance.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Trips

Alter Leg State

This endpoint must be used to alter the state of a leg. Operations: PREPARE the TO can send a message telling the MP that he is preparing the booked leg [To be implemented by the MP] (see (7.2) in the process flow - trip execution), ASSIGN_ASSET can assign an asset to a leg. Can be to assign an asset in case there is still an asset type assigned [Optionally implementable by the MP]. See (4.7) in the process flow - trip execution SET_IN_USE will activate the leg or resume the leg [TO and MP] (see (4.6) in process flow), TIME_EXTEND will be used to request an extension in time; the end user wants to use the asset longer, the time field contains the new end time, TIME_POSTPONE will be used to request a delay in the departure time, the end user wants to depart later, the time field contains the new departure time, PAUSE will pause the leg [TO and MP] (see (4.6) in process flow), OPEN_TRUNK request the TO to open up the trunk (of the scooter), e.g. to store the helmet START_FINISHING will start the end-of-leg [Optionally implementable by TO and MP], FINISH will end this leg (see (4.6) in process flow) [TO and MP]

Authorizations:
bearer
path Parameters
id
required
string

Leg identifier

header Parameters
On-Behalf-Of
string

When the request is made from or by an end-user, this header must contain a unique value identifying that end-user.

Presence of this header on all applicable requests - even those that do not require or return user-specific information - is strongly recommended, as it informs traffic shaping and optimizations which will improve your own performance, as well as helping auditing and troubleshooting operations.

It is not a requirement that the value reveals who the end-user is to Urban Sharing, only that it is a unique and stable value per end-user.

Including the header, but with a non-unique value, will negatively impact performance.

Request Body schema: application/json
required
time
required
string <date-time>
event
required
string
Enum: "PREPARE" "ASSIGN_ASSET" "SET_IN_USE" "PAUSE" "OPEN_TRUNK" "START_FINISHING" "FINISH" "TIME_EXTEND" "TIME_POSTPONE" "CANCEL"
comment
required
string

free text, should match Content-Language

url
required
Array of strings

urls to support the event e.g. pictures justifying the exit conditions

userLocation
required
object
required
object (TompAsset)
id
required
string

Identifier of an asset. Whenever used in Operator Information changed after every trip (GDPR).

isReserved
required
boolean

true indicates the bike is currently reserved for someone else

isReservedFrom
required
string <date-time>

optional addition to determine if an asset is reserved in the future

isReservedTo
required
string <date-time>

optional addition to determine when asset is available in the future

isDisabled
required
boolean

true indicates the asset is currently disabled (broken)

availableUntil
required
string <date-time>

The date and time when any rental of the vehicle must be completed. The vehicle must be returned and made available for the next user by this time. If this field is empty, it indicates that the vehicle is available indefinitely. This field SHOULD be published by carsharing or other mobility systems where vehicles can be booked in advance for future travel.

rentalUrl
required
string

deep-linking option from GBFS+. Only added to be consistent with GBFS 2.0

rentalUrlAndroid
required
string

deep-linking option from GBFS 2.0. Only added to be consistent with GBFS 2.0

rentalUrlIOS
required
string

deep-linking option from GBFS 2.0. Only added to be consistent with GBFS 2.0

mileage
required
number <float> >= 0

the current mileage of the asset

stateOfCharge
required
number <int32> [ 0 .. 100 ]

percentage of charge available

maxRange
required
number <int32> [ 0 .. 100 ]

maximum range in meters

licensePlate
required
string

the usage of this field requires a secure environment. When assets are published in available-assets, this field can be used to track assets. Be aware of this.

stationId
required
string

reference to station_id in /operator/stations, station where it is located

homeStationId
required
string

reference to station_id in /operator/stations, station where it is assigned to

required
Array of objects (TompDamage)

List of known vehicle damages.

Array
vehicleComponent
required
string
Enum: "FRONT" "REAR" "LEFT" "RIGHT" "TOP" "BOTTOM" "INTERIOR" "TIRE" "ANCILLARY" "OTHER"

Part/Component of the vehicle affected. If OTHER is specified the description needs to provide more detail as to what part/component is affected.

description
required
string

Description of the damage.

vehicleComponentName
required
string

a short term to describe the damaged part

pictures
required
Array of strings

URL where pictures of the damage can be accessed. Any special characters in the URL must be correctly escaped.

required
object (TompAssetProperties)
name
required
string

name of asset (type), required in either assetType or asset, should match Content-Language

location
required
object
brand
required
string

brand of the asset

model
required
string
buildingYear
required
number <int32>
colour
required
string

colour of the asset, should match Content-Language

maxSpeed
required
number <int32>

the maximum allowed speed for this asset (in km/h)

wheelCount
required
number <int32> >= 0

the number of wheels

image
required
string

Link to an image of the asset

icon
required
string

Link to an icon of the asset

accessMethods
required
Array of strings
Items Enum: "DEEPLINK" "QR" "AZTEC" "TOMP-API" "AXA-EKEY-OTP" "PHYSICAL-KEY" "BARCODE" "PDF" "HTML" "OVC" "EMV" "NONE"

access method for trip execution. Data will be delivered in the response of /booking/{id}/events - COMMIT or /leg/{id}/events - PREPARE (preferred) or GET /bookings/{id}.

fuel
required
string
Enum: "NONE" "GASOLINE" "DIESEL" "ELECTRIC" "HYBRID_GASOLINE" "HYBRID_DIESEL" "HYBRID_GAS" "HYDROGEN" "GAS" "BIO_MASS" "KEROSINE" "OTHER"
propulsion
required
string
Enum: "MUSCLE" "ELECTRIC" "GASOLINE" "DIESEL" "HYBRID" "LPG" "HYDROGEN"

way in which the asset is powered

energyLabel
required
string
Enum: "A" "B" "C" "D" "E"

Energy efficiency

required
Array of objects (TompAssetPropertiesEcoLabelInner)
co2PerKm
required
number <float> >= 0
gears
required
number <int32>

number of gears of the asset

gearbox
required
string
Enum: "MANUAL" "AUTOMATIC" "SEMIAUTOMATIC"

type of gearbox

airConditioning
required
boolean

airconditioning available

cabrio
required
boolean

cabrio model

towingHook
required
boolean

towing hook available

winterTires
required
boolean

winter tires applied

nrOfDoors
required
number <int32>

the number of doors of the vehicle. Return only when applicable

nrOfHelmets
required
number <int32>

the number of available helmets. Return only when applicable

navigation
required
boolean

navigation available

cruiseControl
required
boolean

cruise control available

persons
required
number <int32> >= 1

number of persons able to use the asset

infantSeat
required
boolean

true indicates infant seat is supplied

pets
required
boolean

true indicates pets are allowed on asset

smoking
required
boolean

true indicates smoking is allowed on asset

easyAccessibility
required
string
Enum: "LIFT" "ESCALATOR" "GROUND_LEVEL" "SIGHTIMPAIRMENT" "HEARINGIMPAIRMENT" "WHEELCHAIR"

describes if asset is or needs to be easily accessible

required
Array of objects (TompRequirement)
regionId
required
string

the region where this asset or assetType is used.

cargo
required
string

describes options to carry cargo, should match Content-Language

cargoVolume
required
number <int32>

the volume in liters of the cargo

cargoLoad
required
number <int32>

the weight in kilograms of the cargo

travelAbroad
required
boolean

true indicates asset is allowed to travel abroad

undergroundParking
required
boolean

true indicates underground parking is allowed with asset

helmetRequired
required
boolean

is a helmet required to operate this asset

defaultReserveTime
required
number <int32> >= 0

Maximum time in minutes that a vehicle can be reserved before a rental begins. When a vehicle is reserved by a user, the vehicle remains locked until the rental begins. During this time the vehicle is unavailable and cannot be reserved or rented by other users. The vehicle status in free_bike_status.json MUST be set to is_reserved = true. If the value of default_reserve_time elapses without a rental beginning, the vehicle status MUST change to is_reserved = false. If default_reserve_time is set to 0, the vehicle type cannot be reserved.

other
required
string

free text to describe asset, should match Content-Language

required
object

this object can contain extra information about the type of asset. For instance values from the 'Woordenboek Reizigerskenmerken'. [https://github.com/efel85/TOMP-API/issues/17]. These values can also be used in the planning.

Responses

Request samples

Content type
application/json
{
  • "time": "2019-08-24T14:15:22Z",
  • "event": "PREPARE",
  • "comment": "string",
  • "url": [
    ],
  • "userLocation": { },
  • "asset": {
    }
}

Response samples

Content type
application/json
{
  • "from": { },
  • "id": "string",
  • "to": { },
  • "departureTime": "2019-08-24T14:15:22Z",
  • "arrivalTime": "2019-08-24T14:15:22Z",
  • "actualArrivalTime": "2019-08-24T14:15:22Z",
  • "actualDepartureTime": "2019-08-24T14:15:22Z",
  • "travelerReferenceNumbers": [
    ],
  • "assetType": {
    },
  • "legSequenceNumber": 0,
  • "asset": {
    },
  • "pricing": { },
  • "suboperator": { },
  • "conditions": [
    ],
  • "state": "NOT_STARTED",
  • "departureDelay": 11112,
  • "arrivalDelay": 11112,
  • "distance": 7250,
  • "progressGeometry": { },
  • "ticket": { },
  • "assetAccessData": { },
  • "allAssetAccessData": [
    ],
  • "userCommunication": [
    ],
  • "memo": "string"
}

Get Leg

Retrieves the latest summary of the leg, being the execution of a portion of a journey travelled using one asset (vehicle). Every leg belongs to one booking, every booking has at least one leg. Where the booking describes the agreement between user/MP and TO, the leg describes the journey as it occurred. See (4.3) in the flow chart - trip execution

Authorizations:
bearer
path Parameters
id
required
string

Leg identifier

header Parameters
On-Behalf-Of
string

When the request is made from or by an end-user, this header must contain a unique value identifying that end-user.

Presence of this header on all applicable requests - even those that do not require or return user-specific information - is strongly recommended, as it informs traffic shaping and optimizations which will improve your own performance, as well as helping auditing and troubleshooting operations.

It is not a requirement that the value reveals who the end-user is to Urban Sharing, only that it is a unique and stable value per end-user.

Including the header, but with a non-unique value, will negatively impact performance.

Responses

Response samples

Content type
application/json
{
  • "from": { },
  • "id": "string",
  • "to": { },
  • "departureTime": "2019-08-24T14:15:22Z",
  • "arrivalTime": "2019-08-24T14:15:22Z",
  • "actualArrivalTime": "2019-08-24T14:15:22Z",
  • "actualDepartureTime": "2019-08-24T14:15:22Z",
  • "travelerReferenceNumbers": [
    ],
  • "assetType": {
    },
  • "legSequenceNumber": 0,
  • "asset": {
    },
  • "pricing": { },
  • "suboperator": { },
  • "conditions": [
    ],
  • "state": "NOT_STARTED",
  • "departureDelay": 11112,
  • "arrivalDelay": 11112,
  • "distance": 7250,
  • "progressGeometry": { },
  • "ticket": { },
  • "assetAccessData": { },
  • "allAssetAccessData": [
    ],
  • "userCommunication": [
    ],
  • "memo": "string"
}