Author: Peter Hirzel (Software Architect SBB Journey Planner), 2023
Licence: Apache License, Version 2.0
The project contains 2 targets:
- a simple OJPAdapter library to request Public-Transportation queries against the swiss public Open Journey-Planner (SKI) based on OJP Specification OJP.xsd.
- a RESTful OJPController with a Transmodel implemenation of a Journey-Planner interface
Remark about OJP SKI+
- Public Transportation router commissioned by BAV
- Usage for e.g. by öv-info.ch
- OJP Wiki
- OJP-Demo shell and XML insights
Abstracting the complex VDV OJP.xsd Schema by Java POJOs, map response properly and provide low-level error-handling.
Anyone (for e.g. public transport-organisation) who plans to use the Swiss OJP router (or other european OJP instances supporting the same protocol version) may try this library to setup a quick working starting point.
The vdv ojp XSD might be quite complex and JAXB POJO generation therefore too!
Besides, understanding the OJP semantics may mean a steep learning curve for non-insiders.
The author hopes using this OJP-Adapter library may "abstract" the above steps massively, though the resulting OJP model may still be complex to deal with (perhaps check the returned data for a more intuitive understanding as well).
This Software was originally developed for SBB AG Switzerland, Personenverkehr, CustomerInformation by Peter Hirzel (Software Architect Journey-Planner) for experimental reasons:
- APIs (endpoints) under SBB Journey-Service within tag Open Journey Planner V3
Contains:
- the OJP.xsd 1.0 is transformed into a JAVA POJO (by JAXB) by
- open-source bliksemlabs or Maven
- dependency ojp-java-model
- Further documentation:
- Semantic model description OJP v1 - Open API for distributed Journey Planning by jmaerki
The provided OJPAdapter is able to query Swiss SKI+ OJP instances, if configured well (by means your own access token):
- use OJPAadapter for raw native XML handling in conversation with OJP protocol.
- Use of Swiss SKI+ OJP 2.0 API.
- Demonstration of easy filters and response analysis by OJPAdapterAccessTest
See:
- VDV OJP 2.0 Model base for Java model Doc
- OJP 2.0 Cookbook
- OJP 2.0 Demo
- OJP 2.0 API Explorer (OpenApi 3)
Contains:
- OJP/Transmodel mapping
- SpringBoot OJPWebApplication
-
- OJPController like subset of SBB Journey-Service v3 APIs where supported by SKI+ OJP:
- Transmodel like implementation model as used by SBB Customer Information
- Covers Place, Trip, DatedVehicleJourney (including Departures/Arrivals)
- Download repository
- mvn clean install
- copy ojp-adapter-integration/src/main/resources/ojp-SAMPLE.properties to ojp.properties and add your own key for SKI+ OJP Instance from opentransportdata.swiss passive instance v2 "Manage the API key"
- run swiss.opentransportdata.ojp.adapter.**.OJPAdapterAccessTest (to try out native OJP XML based request/response)
- clone ojp-adapter-service/main/resources/application.yml to application-local.yml and set 'ojp.authorization'
- run swiss.opentransportdata.ojp.adapter.service.application.OJPWebApplication with 'VM Options'=-Dspring.profiles.active=local
- open OpenAPI 3 Swagger-UI
Remark:
- At least the OJP passive key should be easy to get.
- For the OJP active instance key you probably need to contact the operation-responsibles.
- If your just interested in Open API 3 Swagger-UI resulting out of ojp-adapter-service/../OJPController, see JSON-specification
-
Checkout if you need to acces SKI+ OJP active instance, which supports only OJP v1.*
-
Currently, OJPAdapter deals with one SINGLE Journey-Planner request at a time, though MULTIPLE requests could be performed at once.
-
Complete OJP set of request-filters (currently the most relevant filters are adapted).
-
Complete OJP response mapping (currently the most relevant properties are implemented).
-
Quality tests for correctly mapped output should be verified and confirmed by SKI+.