TOMP‐API v2.0 Functionalities

Two-Wheeled Shared Vehicles

** Functionalities

• direct booking of assets on the street
• usable with bikes published in GBFS
• book assets in the (near) future
• serves station based and free-floating setups. Even dynamic setups.
• 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.
• facilitates any support scenario, even replacement of the asset
• allows to adjust the rental until the start of the trip
• offers functionalities for different payment methods
• possible to different prices based on pause status
• deliver proof (photos) of correct parking

The TOMP-API v2.0 offers a comprehensive operational interface for shared two-wheeled vehicles (bikes, scooters, steps), designed for easy integration and a short return on investment [1].

Key functionalities include:

• Offer and Purchase Flows: The API supports various purchase entry points, including selecting a vehicle directly from a map or street, purchasing offers based on journey planning, or acquiring products like subscriptions or day passes [2]. Purchase options range from immediately confirmed with a cancellation window, to auto-confirmed pending packages, or a two-phase purchase requiring explicit confirmation [2].
• Execution Flow: This module is particularly unique for two-wheeled vehicles as the traveler is in control [2]. It encompasses actions such as starting, ending, pausing, and resuming a leg [2]. It also handles the assignment of assets and ancillaries and can be extended for direct asset operations like opening a helmet box [1]. The API can publish free-floating areas, no-go zones, and parking zones [2].
• Support Flow: Designed for managing unusual situations like flat tires, this flow requires the MaaS Provider (MP) to implement the notification module to receive callbacks from the Transport Operator (TO) [1, 2].
• Payment and After-Sales: The API facilitates reporting balances, requesting deposits (a financial guarantee), handling immediate payments upon leg completion, and managing subscriptions [2]. The after-sales module supports redress options, including refunds or replacements [1, 2].
• Special Cases Handling: The API provides mechanisms for managing aspects specific to two-wheeled vehicles, such as communication with manual locks via instructional links, defining (non-)parking and return zones using GeoJSON, and providing operational instructions or warnings to travelers through the notification module [2].
• Modularity and Scalability: The TOMP-API is modular, allowing implementation to start small and extend functionality over time based on business opportunities [1]. It emphasizes compliance with existing technical standards like OpenAPI 3, (Geo)JSON, OAuth2, and builds upon established data sets to avoid redundant efforts [1].

Shared Cars

The TOMP-API v2.0 provides a comprehensive operational API for shared cars, designed for straightforward integration and a short return on investment [1].

Key functionalities include:

• Offer and Pre-sales Flows: The API supports common offer and pre-sales flows, allowing for the delivery and modification of offers (e.g., adding services, child seats, or insurance). This also includes adjusting start/end times and locations [3].
• Purchase Flows: The API offers two main starting points for purchasing shared cars: selecting a vehicle directly from a map or external data sources, or purchasing offers based on journey planning, where each offer represents an available asset. It also supports purchasing 'products' like subscriptions or trip packages. Purchase flavors include immediately confirmed, auto-confirmed pending, or two-phase pending purchases [3].
• Execution Flow: This module manages the lifecycle of car usage, including starting, ending, pausing, and resuming the vehicle. Information required for vehicle operation and status changes are communicated to the MaaS Provider (MP) via the notification module. An operation-asset facility is available for direct actions like opening a trunk or unlocking a side door [3].
• Support Flow: Designed to handle unusual situations, such as flat tires, this flow requires the MP to implement the notification module for callbacks from the Transport Operator (TO) [3].
• Payment and After-Sales: The API supports reporting balances, requesting deposits (as a financial guarantee), and managing direct payments once a leg is completed. The after-sales module also provides redress options, such as refunds or replacements [3].
• Special Cases Handling: The API addresses specifics for shared cars, including defining (non-)parking and return zones, providing operational instructions to the traveler via links, and sending warnings or information through the notification module [3].
• Modularity and Scalability: The TOMP-API is modular, enabling incremental implementation based on business needs [1]. It emphasizes compliance with existing technical standards like OpenAPI 3, (Geo)JSON, OAuth2, and leverages available datasets to avoid duplicating efforts [1].

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].