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>
lat
required
number <float>
alt
number <float> >= 0

altitude, in meters above sea level

name
string

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

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
string

reference to /operator/stations

object (TompAddress)
streetAddress
required
string
areaReference
required
string

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

street
string

street, consistent with streetAddress

houseNumber
number <int32> >= 0

house number, consistent with streetAddress

houseNumberAddition
string

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

addressAdditionalInfo
string

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

city
string

specified city or town, consistent with areaReference

province
string

province or region, consistent with areaReference

state
string

state, consistent with areaReference

postalCode
string
country
string = 2 characters

two-letter country codes according to ISO 3166-1

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

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

assetReference
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
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
number <int32> >= 0

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

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

altitude, in meters above sea level

name
string

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

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
string

reference to /operator/stations

object (TompAddress)
streetAddress
required
string
areaReference
required
string

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

street
string

street, consistent with streetAddress

houseNumber
number <int32> >= 0

house number, consistent with streetAddress

houseNumberAddition
string

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

addressAdditionalInfo
string

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

city
string

specified city or town, consistent with areaReference

province
string

province or region, consistent with areaReference

state
string

state, consistent with areaReference

postalCode
string
country
string = 2 characters

two-letter country codes according to ISO 3166-1

required
object
property name*
additional property
any
estimatedDistance
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
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
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
number <int32> >= 1

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

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
boolean

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

age
number <int32>

Age of the traveler, may be approximate

referenceNumber
string

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

Array of objects (TompCardType)

The kind of cards this traveler possesses

Array of objects (TompLicenseType)

The kind of licenses this traveler possesses

object (TompRequirements)
knownIdentifier
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
string

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

useAssets
Array of strings

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

userGroups
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
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
object (TompCustomer)
isValidated
boolean

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

age
number <int32>

Age of the traveler, may be approximate

referenceNumber
string

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

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
string

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

assetClass
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
Array of strings

references to accepting parties, only if applicable

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
string = 2 characters

two-letter country codes according to ISO 3166-1

requirements
object
knownIdentifier
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
string

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

id
string

The identifier that the TO uses to identify this customer.

externalId
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
string

optional reference field to the travelers in the planning request.

initials
string
firstName
string

First name of the customer

lastName
string

Last name of the customer

middleName
string

Middle name of the customer

prefix
string

prefix of the customer, like titles

postfix
string

postfix of the customer, like titles

Array of objects (TompPhone)
Array
preferred
boolean

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

number
string

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

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

the email address of the customer

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

two-letter country codes according to ISO 3166-1

object (TompAddress)
streetAddress
required
string
areaReference
required
string

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

street
string

street, consistent with streetAddress

houseNumber
number <int32> >= 0

house number, consistent with streetAddress

houseNumberAddition
string

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

addressAdditionalInfo
string

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

city
string

specified city or town, consistent with areaReference

province
string

province or region, consistent with areaReference

state
string

state, consistent with areaReference

postalCode
string
country
string = 2 characters

two-letter country codes according to ISO 3166-1

photo
string <byte>

base64 encoded

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
string

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

assetClass
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
Array of strings

references to accepting parties, only if applicable

cardDescription
string

description of the card

cardAdditionalNumber
string

additional number, like CVC code or IBAN code

validUntil
string <date>

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

country
string = 2 characters

two-letter country codes according to ISO 3166-1

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
string = 2 characters

two-letter country codes according to ISO 3166-1

number
string
licenseCode
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
string <date>
required
object

dictionary for extra fields (bilatural agreements)

property name*
additional property
any
callbackUrl
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
number <int32> >= 0

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

object (TompAsset)
id
required
string

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

isReserved
boolean

true indicates the bike is currently reserved for someone else

isReservedFrom
string <date-time>

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

isReservedTo
string <date-time>

optional addition to determine when asset is available in the future

isDisabled
boolean

true indicates the asset is currently disabled (broken)

availableUntil
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
string

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

rentalUrlAndroid
string

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

rentalUrlIOS
string

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

mileage
number <float> >= 0

the current mileage of the asset

stateOfCharge
number <int32> [ 0 .. 100 ]

percentage of charge available

maxRange
number <int32> [ 0 .. 100 ]

maximum range in meters

licensePlate
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
string

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

homeStationId
string

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

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
string

a short term to describe the damaged part

pictures
Array of strings

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

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
string

free text, should match Content-Language

legId
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>
lat
required
number <float>
alt
number <float> >= 0

altitude, in meters above sea level

name
string

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

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
string

reference to /operator/stations

object (TompAddress)
streetAddress
required
string
areaReference
required
string

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

street
string

street, consistent with streetAddress

houseNumber
number <int32> >= 0

house number, consistent with streetAddress

houseNumberAddition
string

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

addressAdditionalInfo
string

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

city
string

specified city or town, consistent with areaReference

province
string

province or region, consistent with areaReference

state
string

state, consistent with areaReference

postalCode
string
country
string = 2 characters

two-letter country codes according to ISO 3166-1

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

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

assetReference
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
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
number <int32> >= 0

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

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

altitude, in meters above sea level

name
string

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

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
string

reference to /operator/stations

object (TompAddress)
streetAddress
required
string
areaReference
required
string

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

street
string

street, consistent with streetAddress

houseNumber
number <int32> >= 0

house number, consistent with streetAddress

houseNumberAddition
string

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

addressAdditionalInfo
string

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

city
string

specified city or town, consistent with areaReference

province
string

province or region, consistent with areaReference

state
string

state, consistent with areaReference

postalCode
string
country
string = 2 characters

two-letter country codes according to ISO 3166-1

required
object
property name*
additional property
any
estimatedDistance
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
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
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
number <int32> >= 1

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

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
boolean

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

age
number <int32>

Age of the traveler, may be approximate

referenceNumber
string

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

Array of objects (TompCardType)

The kind of cards this traveler possesses

Array of objects (TompLicenseType)

The kind of licenses this traveler possesses

object (TompRequirements)
knownIdentifier
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
string

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

useAssets
Array of strings

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

userGroups
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
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
string

the booking id

supportType
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"
object (TompPlace)
required
object (TompCoordinates)
lng
required
number <float>
lat
required
number <float>
alt
number <float> >= 0

altitude, in meters above sea level

name
string

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

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
string

reference to /operator/stations

object (TompAddress)
streetAddress
required
string
areaReference
required
string

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

street
string

street, consistent with streetAddress

houseNumber
number <int32> >= 0

house number, consistent with streetAddress

houseNumberAddition
string

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

addressAdditionalInfo
string

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

city
string

specified city or town, consistent with areaReference

province
string

province or region, consistent with areaReference

state
string

state, consistent with areaReference

postalCode
string
country
string = 2 characters

two-letter country codes according to ISO 3166-1

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

the priority of the support request.

contactInformationEndUser
string

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

comment
string
requestedResponseTime
number <double> >= 0

time to respond in minutes.

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
string

a short term to describe the damaged part

pictures
Array of strings

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

urls
Array of strings

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

assetId
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
string

free text, should match Content-Language

url
Array of strings

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

userLocation
object
object (TompAsset)
id
required
string

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

isReserved
boolean

true indicates the bike is currently reserved for someone else

isReservedFrom
string <date-time>

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

isReservedTo
string <date-time>

optional addition to determine when asset is available in the future

isDisabled
boolean

true indicates the asset is currently disabled (broken)

availableUntil
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
string

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

rentalUrlAndroid
string

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

rentalUrlIOS
string

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

mileage
number <float> >= 0

the current mileage of the asset

stateOfCharge
number <int32> [ 0 .. 100 ]

percentage of charge available

maxRange
number <int32> [ 0 .. 100 ]

maximum range in meters

licensePlate
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
string

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

homeStationId
string

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

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
string

a short term to describe the damaged part

pictures
Array of strings

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

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"
}