| Alpha Prototype — Feedback Welcome! |
Brief description
Service directories of mobility services are directories of services (APIs) that support the planning and booking of journeys. Such directories play a key role in scenarios for the international networking of mobility, for MaaS (Mobility as a Service) and for AI-based assistants. However, standards and protocols for this are still barely established.
With this article we would like to contribute to the development and standardisation of this area.
Technical description
What is a service directory of mobility services?
A service directory of mobility services is an electronic, machine-readable directory (also “catalogue”, “registry”, “yellow pages”) of services (mainly APIs) in the field of mobility. It supports the search for providers (intermediaries, brokers) with their planning and sales interfaces (APIs). It is therefore key to the planning of intermodal, multi-part journeys, including pricing and the subsequent booking (reservation, purchase, payment, clearing).
Why do we need such service directories?
We are currently seeing these arguments:
- EU regulation: The EU’s MMTIS regulation requires NAPs to provide certain data sets. Around 73 data categories are defined in the annex. Some of these could be organised in the form of a directory. The precise implementation provisions are currently (spring 2024) being drawn up in a NAPCORE WG 3 (with the involvement of our SKI+ team).
- Vision MaaS (Mobility as a Service): Service directories are needed to set up an international, interoperable, roaming-capable MaaS system. Only thanks to a directory could a roaming client (e.g. a MaaS user from abroad find the available services).
- AI-based personal assistants/agents: according to forecasts by Gartner and other providers of IT market analyses, many purchases will be made by AI-based assistants or agents in a few years’ time. People then ask their AI prompt, for example, “How can I travel from A to B?” and “Book me this journey!”. This will require structured directories of mobility providers.
Current status of implementation
According to our observations, such projects are still in their infancy. In many countries, no such directories are known as open data. There is also a lack of standardisation of data formats and processes. We are not aware of any standards for this at European level (CEN) or worldwide (ISO).
Worth mentioning is the example of Finland (NAP of Finland, https://finap.fi/#/services) with a list of 3000+ transport services (taxi, trains, car hire, etc.). However, this mainly focuses on transport companies and not intermediaries.
Technical description
Design of a prototypical data model (JSON) for Switzerland
In the following, we design a data model for a prototype of a directory of mobility services. This should be able to display metadata such as URL, description and supported sales processes. The model is intended to provide a basis for starting the discussion with stakeholders and the community.
Specification by example
Our design will be presented here using an exemplary, prototypical data set.
{
"last_updated": "2024-07-26T15:54:16.940281+00:00",
"ttl": 31536000,
"version": "0.1",
"spec": "https://opentransportdata.swiss/de/cookbook/service-directory",
"mobilityProviders": [
{
"id": "1",
"name": "SBB Swiss Mobility API - Ticketing",
"description": "An interface that you can integrate into your own distribution system. Fare details are made available to you via this interface.",
"type": "intermediary",
"endpoints": [
{
"url": "https://developer.sbb.ch/apis/b2p/information",
"environment": "prod",
"service_types": [
"pricing",
"reservation"
],
"api_protocol": "proprietary",
"api_version": "3.26.2",
"api_profile": "3.26.2/none",
"credentials": "BearerToken",
"url_description": "SBB Swiss Mobility API - Ticketing. An interface that you can integrate into your own distribution system. Fare details are made available to you via this interface.\nThere are two ways to use the service:\n- Either integrate the SBB Swiss Mobility API as a full version, so that bookings are made directly via your distribution environment\n- Or use the Affiliate solution, with a link to the SBB webshop or SBB mobile",
"qos_document": "https://developer.sbb.ch/apis/b2p/information",
"url_contractual": "https://company.sbb.ch/en/sbb-as-business-partner/services/digital-sales-solutions/sales-solutions/sbb-swiss-mobility-api/sbb-swiss-mobility-api-gtc.html",
"covered_modes": [
"rail",
"tram",
"bus",
"trolleybus",
"metro"
]
}
],
"myOpertors": [
{
"ref": "ch:1:sboid:100001",
"name": "Schweizerische Bundesbahnen SBB"
}
],
"otherOpertors": [],
"coveredArea": "CH"
},
{
"id": "101",
"name": "Open Journey Planner 2.0",
"description": "OJP is the API's Route Planner. The API can be used to plan trips, track journeys, and build departure and arrival indicators. OJP works from coordinate to coordinate, address to address.",
"type": "intermediary",
"endpoints": [
{
"url": "https://api.opentransportdata.swiss/ojp20",
"environment": "prod",
"service_types": [
"planning"
],
"api_protocol": "OJP",
"api_version": "2.0",
"api_profile": "none",
"credentials": "BearerToken",
"url_description": "unknown",
"qos_document": "https://data.opentransportdata.swiss/en/dataset/ojp2-0",
"url_contractual": "https://opentransportdata.swiss/en/dev-dashboard",
"covered_modes": [
"bus",
"coach",
"funicular",
"metro",
"rail",
"tram",
"trolleybus",
"water",
"cableway",
"taxi",
"bicycle",
"demand_and_response_bus",
"car",
"scooter",
"cable_car",
"telecabin",
"air_cableway"
]
}
],
"myOpertors": [],
"otherOpertors": [],
"coveredArea": "CH"
},
{
"id": "102",
"name": "OJPFare",
"description": "Beta: Price information with OJP Fares. A query of public transport prices via NOVA is made available via this interface. This is an initial test system and the data comes from integration and not from production.",
"type": "intermediary",
"endpoints": [
{
"url": "https://api.opentransportdata.swiss/ojpfare/",
"environment": "int",
"service_types": [
"pricing"
],
"api_protocol": "OJP",
"api_version": "1.0",
"api_profile": "none",
"credentials": "BearerToken",
"url_description": "unknown",
"qos_document": "https://opentransportdata.swiss/en/cookbook/beta-price-information-with-ojp-fares-2",
"url_contractual": "https://opentransportdata.swiss/de/dev-dashboard",
"covered_modes": [
"bus",
"coach",
"funicular",
"metro",
"rail",
"tram",
"trolleybus",
"water",
"cableway",
"taxi",
"bicycle",
"demand_and_response_bus",
"car",
"scooter",
"cable_car",
"telecabin",
"air_cableway"
]
}
],
"myOpertors": [],
"otherOpertors": [],
"coveredArea": "CH"
}
]
}
Modelling as a UML class diagram
Basic structure
The basic structure is a list (array) with all known mobilityProviders. In future versions, a file could be replaced by a query interface that allows individual mobilityProviders to be queried according to specific characteristics.
MobilityProvider
MobilityProvider includes basic fields (simple features) of the same:
- id: Identifier; taken from established directories where possible (e.g. sboid).
- orgId: Identifier from the atlas directory atlas.app.sbb.ch (does not exist for current sample data).
- type: Enum (value range: provider, intermediary, providerAndIntermediary).
- coveredArea: see below.
In addition, there are the lists (arrays) of endpoints, myOperators and otherOperators.
Endpoint
Endpoint defines a specific API interface for automatic use. Notes on the fields (see also Enums):
- apiVerision / apiProfile: Version and (if applicable) profile version of the interface standard/format.
- urlDescription / urlContractual /QoSDocument: URLs with corresponding documentation (Specification & Documentation / Contractual /Quality of Service)
- serviceType: Value range generalInfo, planning, availability, using, pricing, reservation, bookingLeg, bookingTrip, complaints, payment.
- apiProtocol: Value range proprietary, TOMP, OJP, OSDM.
- coveredMode: value range air, bus, coach, ferry, funicular, lift, metro, rail, tram, trolleybus, water, cableway, motorbike, taxi, bicycle, shuttle, demand_and_response_bus, horse_drawn_carriage, car, scooter, cable_car, telecabin, air_cableway, monorail, other. Corresponds to the modes of NeTEx.
- credentials: Value range BearerToken, OAuthSKI, OAuth, unknown.
Operator
myOperators and otherOperators reference supported or associated providers (transport companies); limited to id (ref) and name; further data would have to be outsourced in a separate list.
coveredCountry / coveredArea
This field in MobilityProvider sis used to define the geographical coverage. The following solution is proposed here:
- Definition of geographical areas using geofences with WGS-84 coordinates, stored in a separate GeoJSON file.
- Use of GeoJSON FeatureCollections, definition of polygons/multipolegons.
- Referencing of standard, commonly used abbreviations, e.g. CH for Switzerland, canton abbreviations for cantons, etc.
- Geofences that do not yet exist are newly recorded with the appropriate abbreviation.
Further information
This is currently an “alpha draft” for discussion and is not binding.
Feedback welcome, please send to opendata@sbb.ch.