TOMP API - CDSM-WG/CDS-M GitHub Wiki
The TOMP-API is being developed by an open source working group with public and private stakeholders, aimed at facilitating the implementation of MaaS and the corresponding exchange of data. The TOMP-API describes a full MaaS journey, including operator information, planning, booking, support, payments and trip execution.
The TOMP contains all concepts that can be found in GBFS as well, because the 'Operator Module' is inspired by GBFS. The other modules contain concepts for planning, booking, trip execution, support, and payment.
In 'Operator Information' This module is inspired by GBFS.
Concept | Remark |
---|---|
General information |
/operator/information: Details including system operator, system location, year implemented, URL, contact info, time zone. /operator/stations: List of all stations, their capacities and locations. /operator/meta/: a self-descriptive endpoint, telling what is implemented and the process behind the complete API. |
Vehicle information/ Availability |
/operator/available-assets: Describes the types of vehicles that system operator has available for rent. When the use case demands also to publish individual assets, they can be shared using this endpoint as well |
Operating times |
/operator/calendar: dates of operation for the system. /operator/hours: Hours of operation for the system. |
Areas | /operator/regions: Regions the system is broken up into and specific areas like low-speed, non-parking zones etc. |
Prices | /operator/pricing-plans: System pricing scheme. |
Other | /operator/alerts: Current system alerts. |
General main concepts
In the TOMP-API a lot of concepts are used, describing them all would become a too large exercise, so the main concepts are enlisted here.
Concept | Remark |
---|---|
planning request/offer request |
/plannings/?booking-intent=false: planning request was done until version 1.2.2 with this endpoint /plannings/?booking-intent=true: an offer request was done until version 1.2.2 with this endpoint /planning/inquiries: planning request is done since version 1.3.0 with this endpoint /planning/offer: an offer request is done since version 1.3.0 with this endpoint |
asset types | Asset types can be referenced at from the operator information (/operator/available-assets), but also in the planning or offer request (to specify the asset type to be booked). In the booking itself, the asset type is referable too. This implies that it can be accessed in PLANNING, BOOKING, TRIP EXECUTION, SUPPORT (and indirectly) also by PAYMENT. The asset type itself can be specified in the specification (e.g. 'yellow city bikes') |
condition | together with the inquiry and offer, the conditions for the returned leg are returned. The condition types are:
|
booking events | To do operations on the booking, like canceling, denying and committing |
leg | A leg is a specific part of a journey, with one asset (mostly made by one traveler). The leg contains detailed information about the asset, the price (fare), the conditions, and access information or tickets. |
departure/arrival | location & times, max wait times, safe travel times etc. |
address | concept with as well address lines (like 'example street 18') and its parts (street, houseNumber). Should be applicable anywhere in the world |
assets | Where asset types can be referenced, assets can be referenced as well. The asset itself has a lot of properties, to facilitate all kinds of transport means. |
personal information | In both the planning and booking request personal information can be distributed or referenced. The 'travelers dictionary' is used to standardize personal needs and ancillaries. Known categories:
|
user groups | In both the planning and booking request user groups can be referenced at |
trip events | To do operations in the trip execution phase, like (request to) open an asset, close it, and pause it. But also events to extend the reserved time of postpone the start of the leg. |
fare | The final price (or estimation), including price parts. In this concept it is also possible to specify price rules, like 'in the first hour, it costs 0.5 CAD per kilometer, in the second hour 0.75 etc.' |
journal entry | Each leg results in one or more journal entries. One for the fare, but others can be added later on, like fines, payment for damage, refunding, additional costs for extra usage, and so on. |
support request | When unforseen things are happening during the trip execution, support can be requested. |
The information above is sometimes altered to apply in other situations, like sharing information between the city and bike operators.
- In available-assets the asset id can be misused, and track where assets are rented and where assets are returned. This conflicts with privacy regulations; people tend to rent the same bike/scooter and their whereabouts are discoverable.
The fields in the JSON are described here, but only those that need explanation. The values in the building block, are fixed, unless they are between square brackets ([]).
name | required | value | description |
---|---|---|---|
version | * | [version] | The allowed version(s), comma separated. Replace this value by f.x. "1.0.0,1.1.0,1.2.2" |
url | * | [url] | The URL where this file (or endpoint) can be found, f.x. "https://tomp.transporter.com/operator/regions/" |
name | value | argumentation |
---|---|---|
privacy | A |
Available-assets: When implemented as described on Github-TOMP-API, with a new ID when a trip ends, it is almost impossible to derive personal movements. Therefore it is marked as an A. When it is misused (fixed IDs), it drops to C. When it is used together with a use case about origin-destination, it fits the purpose, and it can rise again to B. Be aware of the GDPR mitigative actions you have to take! Others: no personal information, A. |
implementationEffort | D | It requires implementing an API, including the authentication/authorization (when applicable of course). The 'operator information' part could be implemented by serving JSON files directly (except for the available-asset endpoint). |
reusability | A |
available-assets: This data can be applied in several domains, to exchange between TO and MPs, towards route planners and to cities. Whenever a modification is made (static ids), it drops directly to E. Others: fully reusable, A |
interoperability | B | This is a well-known standard, with implementations even outside Europe (B). |
domain | B | When applied in the domain city-transport operator, it would be an A, but this standard is made to exchange data in the mobility domain. Not a perfect fit. |