Home

Introduction

Welcome to the TOMP-API WIKI pages. This page contains the information for implementing the TOMP-API. The Blueprint describes in free format the idea of how the TOMP API was set up.

The latest released version is Dragonfly - 1.4.1. The OpenApi (former: swagger) file can be found here. The upcoming release might be 2.0 (Q1 2024), but when needed, a version 1.5 can be released in between.

General Roadmap - the roadmap items for upcoming period Website, Blog and LinkedIn page Versions Changes per version - change record Semantic versioning - the TOMP-API uses semantic versioning. What does this mean?

Contribution / implementations Contribution Participants (short descriptions per organisation) Reference implementation - an example Github project with implementations Example implementation - the running environment, just to experiment with a web client as MP. Due to Log4J issues temporarily out of order. Quickstart Operator Information - A docker-based quick start, the Operator Information can be implemented by only supplying some JSON files.

Workflow

The actual workflow of the TOMP-API is simple. The scenario for a planned trip: gather information about the known TOs, create the best routes, propose them to the end user, book and go! Payment as dessert.

If the end user doesn't want to plan ("pick up and go"), the actual activity diagram stays the same, the only thing that changes is that the planning doesn't need to look for availability, but can directly request an offer for an asset, providing the asset it wants to use. This approach is also supported in (version 1.4.0 and above) the 'one-stop-booking' (a.k.a. simplified booking process).

Operator information

Information about the operator. Where does it operate, and what are its opening hours? Most of these endpoints contain static data, except for the available-assets. more...

Planning phase

The planning phase actually consists of 1 endpoint but has 2 modes: one for the routing (returns options, without registering anything) and one for getting offers (creates offers that can be booked, with a generated id for the complete life cycle). Completely controlled by one query parameter: booking-intent.

• In version 1.3 this is split into the endpoints 'inquiry' and 'offer'.
• In version 1.4 the planning phase can be skipped when all booking information is already provided in 'static' information (using Operator Information Module or external data source, like GBFS, NeTEx or like) more...

Booking phase

The booking is a transactional process. The booking scenarios are:

• up to version 1.3: one of the offers of the planning phase is booked (using the generated id).
• after 1.3.0: the 'one-stop-booking' endpoint can be used as well, if offers are not needed (e.g. 'I want bike no. 18').

After all the TOs have responded positively to the bookings, each TO has to be confirmed by a commit. (Even this can be bypassed using the process identifiers). more...

Trip execution phase

Prepare

Before a leg can be started, access data can be needed. In this event, the MP requests access information or just informs the TO that the leg is going to start. This can also be used to open lockers. more...

Start

Starting a booked 'leg' is dependent on the type of transport ('modality'). A taxi company will send start information indirectly to the end user, while opening a bike will be initiated by the end user. more...

En route

While using the asset, there are all kinds of events possible. E.g. the end-user can pause the asset. more...

End

The leg ends, the asset has to be returned, closed, etc. more...

Support

During the trip execution, incidents or accidents may happen. To handle this kind of situation, the support module is added. more...

Payment

To get an overview of the payments, this module offers an endpoint, but also to report the non-fare-based payments (like fines). more...

Points of attention

Per modality

• Bike - a generic scenario description for (shared) bike operators
• Taxi - a generic scenario description for taxi operators
• Moped - a generic scenario description for (shared) micro-mobility operators
• Train - a generic scenario description for PT operators
• Metro - a generic scenario description for PT operators
• Bus - a generic scenario description for PT operators
• Parking facility - a generic scenario description for Parking facilities
• Shared car - a generic scenario description for shared car operators

Other

• Process identifiers - the 'care labels', describing the specific process requirements of the TO
• Specifying locations - how to specify a pick-up or drop-off location
• GDPR - GDPR aspects
• Specify Deeplink - how to use deep links in combination with the TOMP-API
• Specify access information or inspection information - how to communicate tickets or access information
• Offboarding process - how to request off-boarding proof
• Generating code using OpenAPI editor - how to generate code (tips & tricks)
• Cooperation with other standards - like GBFS, GTFS, NeTEx, APDS, ...

Eco system relations

• Discovery service
• Clearing house
• Personal data store
  • Blockchain - Verifiable credentials - How the TOMP-API can be used in verifying credentials.