Transport operator guide

This is a guide for how transport operators can make their products available for sale through the Entur Sales Platform.

All transport operators who wish to make their products available for sale through our platform must support the TOMP API standard.

1. TOMP: A Europeen API standard
   1. What is the TOMP standard
   2. Why did we choose this standard
   3. Why Integrating with the TOMP Standard is a Smart Business Move
      1. Why the TOMP Standard is the Right Choice and What It Offers
2. Our reference application
3. Realtime data
4. Implementation
   1. Get meta data (describes the running implementations)
   2. Get vehicleId/assetId (GBFS) given QR-code
   3. Create a booking
   4. Change the state of a leg
   5. Get a leg, a booking or all bookings

TOMP: A Europeen API standard

TOMP = Transport Operator MaaS Provider.

What is the TOMP standard

TOMP (Transport Operator to Mobility-as-a-Service Provider) is a European API standard designed to enable seamless integration and communication between transport operators and Mobility-as-a-Service (MaaS) providers. It allows for functions like booking, payment, and real-time data sharing, helping to create a unified, user-friendly mobility experience across Europe by connecting various transport services within a single application.

• Read more about TOMP here: https://github.com/TOMP-WG
• The TOMP swagger doc: https://app.swaggerhub.com/apis-docs/TOMP-API-WG/transport-operator_maas_provider_api/1.5.0#/

Why did we choose this standard

As a public transport company, we want to use standards to avoid 1-1 implementations between different services. The TOMP API standard is a well-established standard with over 40 users spread over various countries in Europe and is a standard based on GBFS data. Since almost all data provided by shared mobility actors is based on GBFS data, this also makes the implementation of the standard much easier as you do not need to convert between different data models.

Why Integrating with the TOMP Standard is a Smart Business Move

Integrating with the Shared Mobility API, built on the proven TOMP standard, opens doors to new customers and strengthens your collaboration with public transport providers in key municipalities and cities. Entering a Maas-offering platform will significantly increase your exposure to new customers by participating in a bigger marketplace.

By aligning with this standard, your service becomes part of a cohesive mobility offering, making it easier for residents and visitors to discover and use your solutions. Municipalities increasingly favor operators who integrate with shared mobility frameworks, as it ensures better accessibility, reliability, and user experience for their citizens. Moreover, you position your business as a trusted and forward-thinking partner, securing both market growth and long-term cooperation with public transport providers.

In addition, as mobility trends evolve, the TOMP standard is actively maintained and updated to accommodate new technologies and use cases. By integrating now, you prepare your service for continued relevance in the rapidly changing mobility landscape.

Why the TOMP Standard is the Right Choice and What It Offers

1. Enhanced Interoperability: The TOMP standard is designed to ensure seamless communication between mobility operators and public transport providers. This reduces technical barriers and simplifies integration, saving time and resources while ensuring your service is ready for future scalability.
2. Access to a Growing Network: By adopting the TOMP standard, your service becomes part of a unified ecosystem that connects operators,public transport authorities, and end users. This increases visibility and access to new customer groups, hence a potential for top linegrowth.
3. Streamlined Collaboration: The standard fosters closer collaboration with public transport companies, ensuring smoother partnerships and alignment with local mobility strategies. This collaboration helps build trust and enhances your position in competitive markets.
4. Regulatory Compliance: Municipalities and transport authorities often favor operators who adhere to established standards like TOMP when issuing permits. This alignment can improve your chances of securing concessions.
5. Improved User Experience: TOMP ensures that users can plan, book, and pay for services through unified systems, reducing friction and increasing satisfaction. This makes your service more attractive to both new and existing customers.
6. Future-Proofing Your Service: As mobility trends evolve, the TOMP standard is actively maintained and updated to accommodate new technologies and use cases. By integrating now, you prepare your service for continued relevance in the rapidly changing mobility landscape.
7. Sustainability Alignment: Many municipalities prioritize sustainable transport solutions. Integrating with the TOMP standard positions your service as part of a sustainable ecosystem, enhancing your brand image and appeal to environmentally conscious users.

Our reference application

Team shared mobility at Entur have created a open source reference application with all needed controllers, data classes and services with test data as a Kotlin Spring Boot application. We have also written a guide in the README with information about what kind of endpoints you as a Transport Operator need to implement. Since the TOMP-standard supports all kinds of mobilities, and we (as of 20th August 2024) only supports micro-mobility, the amount of endpoints and response data is at a minimum.

• Application: https://github.com/entur/shared-mobility-to-ref
• Swagger doc: https://petstore.swagger.io/?url=https://api.dev.entur.io/api-docs/shared-mobility-to-ref

Realtime data

Since all shared mobility operators in Norway are required by law to deliver realtime data to Entur, our team and clients uses the Mobility API to receive information about available assets, system information, vehicle types, pricing plans, system regions and geofencing zones. Because of this a lot of TOMP-endpoints becomes redundant, which also makes the implementation of the standard easier for transport operators.

Implementation

As mentioned, we have created an open source project who works as a reference app on how to implement the TOMP API standard. Take a look at the README.md in the shared-mobility-to-ref application for how to implement all the required endpoints.

Dictionary

• Booking: General information about the booking
• Booking.id: Unique identifier (UUID) for the booking
• Booking.state: The state of the booking
• Booking.departureTime: When the booking was created
• Booking.arrivalTime: When the booking was ended
• Booking.from: Where the trip started (coordinates)
• Booking.to: Where the trip ended (coordinates), not required
• Booking.pricing: The total amount of all the legs. Should be set after each leg have state START_FINISHING (ready for a picture of the asset)
• Booking.customer: Information about the customer. Usually only a ID
• Booking.legs: General information about a part of the trip. Usually only one leg on a booking with an asset (vehicle)
• Booking.legs[].id: Unique identifier (UUID) for the leg
• Booking.legs[].leg: The state of the leg
• Booking.legs[].state : Current state of the leg.
• Booking.legs[].departureTime: When the leg was created
• Booking.legs[].actualDepartureTime: When the leg actually started (state = IN_USE)
• Booking.legs[].arrivalTime/actualArrivalTime: When the leg was ended
• Booking.legs[].from: Where the trip started (coordinates)
• Booking.legs[].to: Where the trip ended (coordinates), not required
• Booking.legs[].pricing: Pricing plan for the leg. Does not include the current price of the trip
• Booking.legs[].asset: Information about the asset (vehicle)
• Booking.legs[].asset.id: Unique identifier (UUID) for the asset. Should be the same as the GBFS dynamic ID
• Booking.legs[].asset.stateOfCharge: Current battery level for the asset
• Booking.legs[].asset.maxRange: Current range for the asset in KM
• Booking.legs[].asset.assetType.id: Reference to a AssetType. Required in TOMP, but we have set a static fallback since we dont use it
• Booking.legs[].asset.overriddenProperties.meta.vehicleCode: Your internal vehicleCode
• Booking.legs[].asset.assetType.id : Reference to an AssetType. Required by the TOMP specification.
• Booking.legs[].asset.overriddenProperties.meta.vehicleCode : Operator-specific internal vehicle identifier.

Here are a list of all the endpoints you need to implement (with examples) to support the TOMP API standard:

Get meta data (describes the running implementations)

Description: This endpoint returns meta data about the running implementation. This includes what endpoints are implemented and what versions of the TOMP standard is supported.

Get vehicleId/assetId (GBFS) given QR-code

Description: This endpoint is used to get the vehicleId/assetId given a QR-code. The QR-code is a unique identifier for the vehicle.

Create a booking

Description: This endpoint creates a booking for a trip. The booking is created with a list of legs, which includes information about the assets (vehicle). Pricing on the booking is not mandatory before the state of all legs are set to START_FINISHING. The pricing on each leg represents the pricing plan, and the pricing on the booking represents the total price for the trip.

Change the state of a leg

Description: This endpoint is used to change the state of a leg. The state of a leg can be changed to IN_USE, PAUSE, START_FINISHING or FINISH. If its not possible to pause the vehicle, you dont need to support IN_USE or PAUSE events and you can set the leg state to IN_USE when creating the booking. When the state of a leg is set to START_FINISHING, the actualArrivalTime should be set.

Get a leg, a booking or all bookings

Create a support case

Endpoint: POST /support

Description: Creates a support case related to a shared mobility booking or asset. The request is routed to the correct transport operator based on the Operator-Id header. This endpoint is typically used when an end user experiences an issue during a trip (for example, unable to open or close a vehicle, asset not available, accident, etc.).

Headers:

• Entur-Distribution-Channel (required): Identifies the distribution channel initiating the request.
• Operator-Id (required): Identifies the transport operator that should receive the support case.

Authorization: Requires permission shared-mobility.support with action OPPRETT.

Request body (SupportRequest):

• supportType (required): Type of support issue.
• contactInformationEndUser (required): Contact details for the end user.
• distributionChannel (required): Distribution channel reference.
• transportOperatorBookingId (optional): Booking identifier used by the transport operator.
• assetId (optional): Identifier of the asset involved.
• comment (optional): Free-text description of the issue.
• place (optional): Location where the issue occurred.
• orderId (optional): Entur order identifier.
• vehicleCode (optional): Operator’s internal vehicle reference.

Responses:

• 200 OK: Support case successfully created.
• 400 application/problem+json: Invalid request or missing required information.

Get support status for a booking

Endpoint: GET /support/{bookingId}/status

Description: Retrieves the status of one or more support cases associated with a booking. This endpoint is intended for internal or operational use and is not exposed in public API documentation.

Authorization: Requires permission shared-mobility.support with action LES.

Path parameters:

• bookingId (required): UUID of the booking.

Response body (SupportStatus):

• status: Current status of the support case.
• timeToResolution: Estimated time to resolution in minutes.