Transport Operator MaaS Provider API API Reference

An API between MaaS providers and transport operators for booking trips and corresponding assets.

The documentation (examples, process flows and sequence diagrams) can be found at github.

Version: 1.0.0

Paths

TO

POST /plannings/

Returns plannings 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.

In the final check, just before presenting the alternatives to the user, a call should be made using booking-intent, requesting the TO to provide booking IDs to reference to during communication with the MP.

see (2.1) in the process flow - planning

booking-intent: object
in query

Specifies whether IDs should be returned for the leg options that can be referred to when booking

Accept-Language: object
in header

A list of the languages/localizations the user would like to see the results in. For user privacy and ease of use on the TO side, this list should be kept as short as possible, ideally just one language tag from the list in operator/information

Api: object
in header

API description, can be TOMP or maybe other (specific/derived) API definitions

Api-Version: object
in header

Version of the API.

201 Created

Available transport methods matching the given query parameters. If no transport methods are available, an empty array is returned.

202 Accepted

Request was successfully accepted for processing but has not yet completed.

400 Bad Request

Bad request. See https://github.com/TOMP-WG/TOMP-API/wiki/Error-handling-in-TOMP for further explanation of error code.

401 Unauthorized

Authorization error (invalid API key) or insufficient access rights given current authorization. See https://github.com/TOMP-WG/TOMP-API/wiki/Error-handling-in-TOMP for further explanation of error code.

Response Headers (201 Created)
Location

The URI where the most up to date version of the created planning result can be found. Not required.

object
Content-Language

The language/localization of user-facing content

object
Response Headers (202 Accepted)
Location

The URI where the created or updated resource will eventually be found.

object
TO

POST /bookings/

Creates a new Booking for the TO in Pending state. The ID of the posted booking should be the ID provided in the previous step (planning).

The Booking may be modified in the response, e.g. location being adjusted for a more suitable pick-up location. In addition, the service may contain a meta attribute for arbitrary TO metadata that the TO needs later, and token attribute depicting how long the current state is valid.

The optional webhook can be used to post updates from TO to MP. If it isn't used, the subscription possibility in this API can be used or the events can be posted directly.

see (3.2) in the process flow - booking

Accept-Language: object
in header

A list of the languages/localizations the user would like to see the results in. For user privacy and ease of use on the TO side, this list should be kept as short as possible, ideally just one language tag from the list in operator/information

Api: object
in header

API description, can be TOMP or maybe other (specific/derived) API definitions

Api-Version: object
in header

Version of the API.

201 Created

A new booking was succesfully created, status pending

202 Accepted

Request was successfully accepted for processing but has not yet completed.

400 Bad Request

Bad request. See https://github.com/TOMP-WG/TOMP-API/wiki/Error-handling-in-TOMP for further explanation of error code.

401 Unauthorized

Authorization error (invalid API key) or insufficient access rights given current authorization. See https://github.com/TOMP-WG/TOMP-API/wiki/Error-handling-in-TOMP for further explanation of error code.

404 Not Found

The requested resources does not exist or the requester is not authorized to see it or know it exists.

Response Headers (201 Created)
Content-Language

The language/localization of user-facing content

object
Expires

The result is valid until this timestamp. The pending booking is expired after this timestamp. This option can be used, but there is also a facility to use the webhook, mentioned in '#/component/schemas/booking'.

object
Response Headers (202 Accepted)
Location

The URI where the created or updated resource will eventually be found.

object
TO

POST /bookings/{id}/events

This endpoint must be used to alter the state of a booking:
- The operation 'CANCEL' Cancels the booking (see <4> in the process flow - booking),
- the operation 'EXPIRE' informs that the booking-option is expired (seel <5> in the process flow - booking) and
- the 'COMMIT' actually makes this booking option a real confirmed booking. (see also (3.2) in process flow - booking). This event should also be used to commit in the 'postponed-commit' scenario.
- 'DENY' tells the MP that the leg is cancelled in the post-commit scenario.

CANCEL - Cancels a confirmed booking. Cancelling twice should still return 204.
EXPIRE - Typically for sending back a signal from TO to MP to tell the pending state is expired. Expiring twide should return 204. Expiring a booking in a non-pending state will result in 403.
COMMIT - Turns the booking in a confirmed state, after all legs are in state pending. Committing twice will result in 204. If the booking is in state CANCELLED or EXPIRED, a commit will result a 403.
DENY - Used for the 'postponed-commit' scenario. Whenever a TO cannot give garantees directly to fullfil a booking, it can return a 'COMMIT', but the state of the booking object should be 'POSTPONED-COMMIT'. In the conditions returned in the planning phase is stated until when this phase can be. After this time it will be come expired. Otherwise it can be commmitted when the leg is confirmed or denied (using this event).

Accept-Language: object
in header

A list of the languages/localizations the user would like to see the results in. For user privacy and ease of use on the TO side, this list should be kept as short as possible, ideally just one language tag from the list in operator/information

Api: object
in header

API description, can be TOMP or maybe other (specific/derived) API definitions

Api-Version: object
in header

Version of the API.

id: object
in path

Leg identifier

200 OK

The modified booking

204 No Content

Request was successful, no content to return.

400 Bad Request

Bad request. See https://github.com/TOMP-WG/TOMP-API/wiki/Error-handling-in-TOMP for further explanation of error code.

401 Unauthorized

Authorization error (invalid API key) or insufficient access rights given current authorization. See https://github.com/TOMP-WG/TOMP-API/wiki/Error-handling-in-TOMP for further explanation of error code.

403 Forbidden

The request will not be fulfilled, because the request is not legal in the current state. Authorization will not help. See https://github.com/TOMP-WG/TOMP-API/wiki/Error-handling-in-TOMP for further explanation of error code.

404 Not Found

The requested resources does not exist or the requester is not authorized to see it or know it exists.

410 Gone

The requested resource is no longer available. This is permanent.

Response Headers (200 OK)
Content-Language

The language/localization of user-facing content

object