The TOMP-API is agnostic regarding ‘static information’ that is needed to book. Static information (data from level 1 of MaaS Maturity modal of RISE) can be supplied using GBFS, GTFS, NeTEx, IXSI5 (shared cars), and even OCCP (EV charging), APDS (parking), and CDS (curbs), depending on the modality you offer. That means you don’t have to ‘redo’ what you already have done and can start planning or booking right away.
But, if you want to reuse your information, and use the TOMP-APIs planning and/or booking module in addition to this, you have to ‘stitch’. Somewhere you have to tell the outer world how your information (like NeTEx bus stop numbers, or GBFS asset IDs) should be supplied in the booking process. In other words, interoperability.
In version 1.4.0 we have extended the meta-endpoint, where the implemented endpoints can be found. Until version 1.3.0, we published in here only the TOMP-endpoints, but from version 1.4.0, we’ll be able to publish external ‘endpoints’ as well, including how it should be used to the planning/booking process.
The best way to clarify how this works, is by writing down an example. In the example below, we will show you a GBFS vehicle_status.json file, how it should be specified in the offer request (or in the one-stop-booking, which is also new in version 1.4.0) and how to specify it in the meta-endpoint.
The example comes from the GBFS’ github:
{
"last_updated":1640887163,
"ttl":0,
"version":"3.0",
"data":{
"vehicles":[
{
"vehicle_id":"973a5c94-c288-4a2b-afa6-de8aeb6ae2e5",
"last_reported":1609866109,
"lat":12.345678,
"lon":56.789012,
"is_reserved":false,
"is_disabled":false,
"vehicle_type_id":"abc123",
"rental_uris": {
"android": "https://www.example.com/app?vehicle_id=973a5c94-c288-4a2b-afa6-de8aeb6ae2e5&platform=android&",
"ios": "https://www.example.com/app?vehicle_id=973a5c94-c288-4a2b-afa6-de8aeb6ae2e5&platform=ios"
}
},
{
"vehicle_id":"987fd100-b822-4347-86a4-b3eef8ca8b53",
"last_reported":1609866204,
"is_reserved":false,
"is_disabled":false,
"vehicle_type_id":"def456",
"current_range_meters":6543.0,
"station_id":"86",
"pricing_plan_id":"plan3"
}
]
}
}
If we want to get an offer for the first asset, we could call the TOMP’s /plannings/offers endpoint like this:
{ “from”: { “coordinates”: { “lng”: 56.7890, “lat”: 12.3457 },
“departureTime”: “2022-10-12T10:05:00”,
“useAssets”: [ “973a5c94-c288-4a2b-afa6-de8aeb6ae2e5” ] }
Or, in case we only are interested in getting a vehicle of type ‘abc123’, we could call it this way:
{ “from”: { “coordinates”: { “lng”: 56.7890, “lat”: 12.3457 },
“departureTime”: “2022-10-12T10:05:00”,
“useAssetTypes”: [ “abc123” ] }
This makes sence, but how can you – as Transport Operator – inform the MaaS Provider that stitching should be done this way? That’s where the meta-endpoint comes in play. The MaaS provider can call your meta-endpoint to discover what you have implemented. In there, there should be the next part:
“endpoints”: [
{ “externalType”: “GBFS”,
“path”: “https://gbfs.my-bikes.eu/vehicle_status.json”
“useAssets”: [“vehicle_id”]
} ]
This specification shows that we can use the ‘vehicle_id’ in the vehicle_status of GBFS can be used to request an offer, by placing it in the ‘useAssets’ field of the offer request. In case of the type-reference, we should add something like this:
“endpoints”: [
{ “externalType”: “GBFS”,
“path”: “https://gbfs.my-bikes.eu/vehicle_types.json”
“useAssetTypes”: [“vehicle_type_id”]
} ]
That’s just it? Ah, yes. Very pragmatic, no theoretical excercises required. The supplied field ‘useAssets’ or ‘useAssetTypes’ already clarifies where it can be used.