TOMP‐API v2.0 Functionalities

Two-wheeled shared vehicles

Setup

• serves both station-based and free-floating setups. Even dynamic setups.

Offering & booking

• direct booking of assets on the street AND search for assets
• use GBFS's published vehicles
• book assets in the (near) future
• use deposits
• Purchase products, like monthly cards, subscriptions or multi-ride vouchers
• Usable with external route planners

Execute the trip

• can be used to open locks of any kind.
• can be used to open lockers and chargers
• copes with helmets and helmet boxes
• start, stop, pause and resume trips
• deliver proof (photos) of correct parking

Support the traveler

• facilitates any support scenario, even the replacement of the asset
• allows for adjusting the rental until the start of the trip
• reuse existing published data, like MDS policies: (no-)parking zones, speed limits, etc.

Payment & after sales

• offers functionalities for different payment methods
• charge different prices based on pause status
• request payment directly after the trip has finished

Shared cars

Setup

• serves both station-based, free-floating and round-trip setups.

Offering & booking

• Search for offers, but also book a car on the street
• In case of offerings, adjust the offer (additional services, child seats, insurance, ..) and specify traveler's details (e.g. driver's license)
• Purchase products, like monthly cards, subscriptions or multi-ride vouchers
• Usable with external route planners

Execute the trip

• can be used to open garage doors
• start, stop, pause and resume trips
• deliver proof (photos) of correct parking
• custom functionality to operate the car, charging equipment or garage doors
• publish on-street and off-street parking locations

Support the traveler

• reporting incidents, flat tires, etc
• request to extend the usage time
• request location of parked vehicle
• formalized process to replace the (broken) vehicle
• warn the traveler based on MDS policy-zones
• inform the traveler (time left, operational instructions)

Payment & after sales

• Report the balance
• Request immediate payment after the trip
• Redress options, like refunding
• Handling fines

DRT & Taxis

The TOMP-API v2.0 provides a comprehensive operational API for Demand Responsive Transport (DRT) and Taxi services, designed for straightforward integration and a short return on investment. Key functionalities include: * **Offer Flows:** The API facilitates finding possible offers based on pick-up and drop-off locations, timestamps, number of travelers, and other user requirements. These offers are initially non-binding, allowing users to select and then purchase a single offer [1]. * **Purchase Flows:** The API supports various purchase methods: * **Offer-based:** Purchasing an offer generated from journey planning [1]. * **Product-based:** Booking a single ride directly, such as a "call a cab" service [1]. * **Additional Products:** Selling products like monthly cards, day cards, or multi-ride packages [1]. The purchase can be "immediate confirmed" (status 'CONFIRMED') or "delayed confirmed" (initially 'PENDING' until operator planning is complete and then confirmed via notification module) [1]. * **Execution Flow:** This module manages the lifecycle of a DRT or Taxi ride after it is confirmed. It includes phases such as ride preparation (PREPARING), passenger boarding (IN USE), and passenger alighting (ENDED) [1]. The Transport Operator (TO) informs the MaaS Provider (MP) about state changes using the notification module [1]. This also covers scenarios like no-shows, user-requested changes to locations or times, and connection protection between fixed route and DRT services [1]. * **Support Flow:** Designed for unusual situations, such as when a user cannot locate the vehicle at the pick-up spot [1]. The MP can forward such issues to the TO via the support module, which requires the MP to implement the notification module for callbacks [1]. * **Payment and After-Sales:** The API supports several payment models, including fixed price upfront, estimated price upfront, pay-afterwards, and batch payments for multiple trips [1]. The after-sales module allows the MP to request current cancellation options and conditions for a booked ride and to confirm redress options, including refunds or compensations [1]. * **Special Cases Handling:** While not yet supporting ride series or providing a straightforward solution for reviews, the API is designed to be extensible for future functionalities like tips [1]. * **Modularity and Scalability:** The TOMP-API is modular, enabling incremental implementation based on business needs [2]. It emphasizes compliance with existing technical standards like OpenAPI 3, (Geo)JSON, OAuth2, and leverages available datasets to avoid duplicating efforts [2].

Public Transport

The TOMP-API v2.0 provides a comprehensive operational API for Public Transport, designed for straightforward integration and a short return on investment. Key functionalities include: * **Offer and Pre-sales Flows:** The API supports searching for offers based on criteria like start/end location and time [3]. It also includes a pre-sales module that allows combining multiple offers, modifying them (e.g., adjusting start/end times/locations, assigning seats), and adding/removing ancillary products or traveler information before purchase [3]. Offers resulting from `search-offers` are non-binding; however, selecting offers using the pre-sales module makes them binding, requiring a `release-package` call to abort the process [3]. * **Purchase Flows:** The API enables purchasing offers (from the offer module), packages (from the pre-sales module), or products like weekly cards, day cards, or predefined tickets [3]. Purchase processes can be "immediate confirmed," "auto-confirm" (pending until an expiry date), or a "2-phase purchase" (requiring explicit confirmation of a pending package) [3]. After purchase, the digital travel document (ticket) must be retrievable for inspection or gate access [3]. * **Execution Flow:** While often less critical for traditional public transport, this module comes into play for new travel methods [3]. It manages the package lifecycle from CONFIRMED to STARTED (when the first leg is executed) and eventually ENDED [3]. At the leg level, options include assigning seats and ancillaries when a leg is in NOT STARTED state [3]. For scenarios like swipe-on/off or be-in/out, `activate-product` is used [3]. The Transport Operator (TO) should inform the MaaS Provider (MP) about status changes via the notification module [3]. * **Support Flow:** This module allows travelers to request support or deliver proof of malperformance (e.g., for claiming refunds) [3]. This includes requesting assistance, such as help getting into a train [3]. * **Payment and After-Sales:** The API supports upfront payments and managing subscriptions [3]. The after-sales module includes redress options like refunds (money back) or replacements (e.g., another package) [3]. The MP can request valid redress options for specific legs, ancillaries, or packages [3]. * **Special Cases Handling:** For public transport, specific considerations include providing instructions via links for manual locks, defining (non)-parking and return areas, and sending warnings or information to the traveler through the notification module [3]. The API does not have a straightforward answer for non-standardized Bluetooth locks [3]. * **Modularity and Scalability:** The TOMP-API is modular, enabling incremental implementation based on business needs [2]. It emphasizes compliance with existing technical standards like OpenAPI 3, (Geo)JSON, OAuth2, and leverages available datasets to avoid duplicating efforts [2].