Open Journey Planner SDK for iOS and macOS

Overview

This SDK is enabling Swift applications to integrate Open Journey Planner (OJP) V2 APIs to support distributed journey planning according to the European (CEN) Technical Specification entitled “Intelligent transport systems – Public transport – Open API for distributed journey planning”.

For a general introduction to OJP, consult the Cookbook on opentransportdata.swiss. Visit vdvde.github.io/OJP for the documentation of the XML Schema of OJP.

🚧 Currently this SDK is under construction. Note that APIs may still change. 🚧

Features

Available APIs

• Location Information Request
• Trip Request
• TripInfo Request
• Stop Event Request

Requirements

• Compatible with: iOS 15+ and macOS 14+
• A valid API token for OJP 2.0 on opentransportdata.swiss

Installation

The SDK can be integrated into your Xcode project using the Swift Package Manager. Add following dependency to your Package.swift or as a Package Dependency in Xcode:

    .package(url: "`https://github.com/openTdataCH/ojp-ios.git", from: "1.0.0"),

Usage

Initializing

import OJP

let apiConfiguration = APIConfiguration(
    apiEndPoint: URL(string: "your api endpoint")!, 
    requesterReference: "your request reference", 
    additionalHeaders: [
        "Authorization": "Bearer yourBearerToken"
    ]
)

let ojpSdk = OJP(
    loadingStrategy: .http(apiConfiguration),
    language: "de" // optional ISO language code. Defaults to the preferred localization. 
)

Basic Usage

Get a list of PlaceResult from a keyword

// get only stops
let stops = try await ojpSdk.requestPlaceResults(
    from: "Bern",
    restrictions: .init(type: [.stop])
)
        
// get stops and addresses
let addresses = try await ojpSdk.requestPlaceResults(from: "Bern", restrictions: .init(type: [.stop, .address]))

Get a List of PlaceResults around a Place using Longitude and Latitude

let nearbyStops = try await ojpSdk.requestPlaceResults(
    from: Point(long: 5.6, lat: 2.3), 
    restrictions: .init(type: [.stop])
)

Get a List of Trips between two Places

let origin = try await ojpSdk.requestPlaceResults(
    from: "Bern", 
    restrictions: .init(type: [.stop])
).first!

let via = try await ojpSdk.requestPlaceResults(
    from: "Luzern", 
    restrictions: .init(type: [.stop])
).first!

let destination = try await ojpSdk.requestPlaceResults(
    from: "Zurich HB", 
    restrictions: .init(type: [.stop])
).first!

let tripDelivery = try await ojp.requestTrips(
    from: origin.placeRef, 
    to: destination.placeRef, 
    via: via.placeRef,
    params: .init(
        includeTrackSections: true, 
        includeIntermediateStops: true
    )
)

Update an existing Trip

// in order to update a trip, you need to keep around the "original" `OJPv2.TripResult` or a `OJPv2.Trip`.

// example using `OJPv2.Trip`
let tripResult = OJPv2.TripResult(trip: trip)
let tripRefineDelivery = try await OJP.configured.requestTripRefinement(tripResult: tripResult)

For a more detailed introduction head over to the Getting Started article in the documentation.

Sample App

There is an experimental Sample App to showcase and test the SDK. Currently intended to be run as a macOS app.

Documentation

• Documentation of the Swift Library
• run format-code.sh to execute swiftformat on the library

Releases

See Releases for the history of all current releases.

How To Release A New Version

A new release can be prepared by creating and pushing a release/X.X.X branch. Where X.X.X is the semantic version of the release. As soon as this is pushed the prepare_release.yml workflow will:

1. update the Version.swift file
2. tag the release
3. open a new PR for this release

After this PR is approved and merged the draft_release.yml workflow will draft a Github release.

Used Standards

• OJP - Open API for distributed Journey Planning (vdvde.github.io/OJP/develop)
• SIRI-SX/VDV736 -> realization_guide_siri-sx_oev_schweiz_v1.0.pdf

Contributing

Contributions are welcomed. Feel free to create an issue or a feature request, or fork the project and submit a pull request.

License

MIT License, see LICENSE

Contact

Create an issue or contact opentransportdata.swiss