andaryjo / trias-client

Lean Node.js client for public transport TRIAS APIs

TRIAS Client

A lean Node.js client for TRIAS APIs. 🚀

This client aims to be an easy to use and lightweight implementation for the public transport TRIAS specification. It achieves that by providing only a small subset of the capabilities of TRIAS and utilizing the Friendly Public Transport Format.

trias-client currently implements TRIAS v1.2 and only supports following basic functionalities:

• Searching for stops (either using a name or coordinates).
• Fetching departures for a stop.
• Reading current ticker news for a stop.
• Navigating from stop to stop.

Usage

Please note that you will need an API endpoint and an API key or requestor reference key issued by a data provider. Check the providers list for open APIs.

Install the package:

npm install trias-client

Following script creates a client instance, searches for a station and fetches the departures for the first result. Please refer to the documentation for more information.

const trias = require("trias-client");

var client = trias.getClient({
    url: "place the url of the TRIAS API here",
    requestorRef: "place your requestor ref here"
});

var stopsResult = await client.getStops({
    name: "bismarckplatz"
});

var departuresResult = await client.getDepartures({
    id: stopsResult.stops[0].id
});

There's also an example script available that demonstrates how to use trias-client.

What is TRIAS?

TRIAS stands for "Travellor Realtime Information and Advisory Standard", has been developed in scope of the research and standardisation project for public transport "IP-KOM-ÖV" and was then introduced in 2014 as a standardized specification by the VDV (Verband Deutscher Verkehrsunternehmen). TRIAS offers a wide-range list of functionalities, including station / location search, realtime departures, navigation, ticket price calculation, malfunction reportings, and so on. Here is a list of all public transport providers that provide a TRIAS API.

Why TRIAS?

Compared to HAFAS, TRIAS isn't that widely distributed. But it's a step in the right direction as it allows for some kind of standardization in the jungle of Public Transport APIs. Unfortunately, many of the data providers still build their own proprietary APIs.

You might wonder why this even matters if you can just continue to use the existing HAFAS interfaces. The biggest difference is that these HAFAS interfaces are not supposed to be used by the public and public transport providers might even prohibit to use them (you can read more about that here). So if you want to develop and publish a project that uses public transport data, you might want to have some kind of agreement with the data provider, that reduces operational and legal risk for both you and the provider.

And this is where TRIAS becomes relevant, as the APIs built on it are public (not open, as they still require authentication, but public). And while some providers are a bit more strict regarding the use and display of the data, in general all of the APIs have fair terms of use and come with realistic usage quotas.

Related resources

trias-client was originally developed in scope of Abfahrt, a public transport companion (retired as of December 2022) that integrates multiple ÖPNV providers in just one app. You can take a look over there to see this client in action.

Dou you want to develop your own TRIAS client? Here are some resources:

• VDV 431-2 EKAP-Schnittstellenbeschreibung (german)
• VDV TRIAS XML specification
• TRIAS implementation example in PHP
• TRIAS request examples (german)

trias-client's Issues

Add support for custom headers

Some providers require authorization using http headers.

Retire request, introduce axios

The npm module request has been deprecated for some time now. I'd therefore like to switch to Axios, which is a more modern and promise-based alternative.

The migration becomes urgent as I'm having some issues adding the VVO provider to my own public transport application Abfahrt. Using this client, I'm not able to perform successful requests to the VVO TRIAS API (returning error 404).

This seems to be a problem with request in general, because it works with Postman and with axios when using the exact same request headers and payload. I did some low-level debugging on my own platform before I realised that this is a problem with this client: https://gitlab.com/andary/abfahrt-core/-/issues/50

I therefore will need to introduce axios sooner than planned.

Introduce mocked TRIAS service for testing

The module testing currently tests the functionality of the module for multile TRIAS providers to ensure it's comaptibility. However, I do not think that this is a good testing approach as it depends on the availability and correct implementation of external providers.

Instead, testing should be done on a mocked implementation of a TRIAS provider (maybe by generating random XML responses based on the TRIAS specificiation). It will be hard to then test not only the technical but also the business aspect of the data (does the data even make sense & what weird constellations can appear?).

Maybe testing can depend on a combination of mocked and actual TRIAS data. I just think that the unavailability of a TRIAS provider should not result in failing tests.

Add support for trips

Introduce TRIAS trips for release 1.0.

Propose changes to FPTF

The current FPTF version does not satisfy all the requirements needed to be able to fully adapt it for this client.

Let's propose some enhancements! Especially:

• Add line and direction to stopover.
• Add line to leg.

You can see all the changes I had to make here: https://github.com/andaryjo/trias-client/blob/c605157d535231a550c021b85df70eb216f668f8/src/types/fptf.ts

Allow custom Content-Type header

Currently the client automatically set the header Content-Type to application/xml. But for example the VVO provider needs the header set to text/xml.

The client should therefore not overwrite the header when already set by the consumer.

No stop results for providers VVS and VRR

Detected in Abfahrt Core: https://gitlab.com/andary/abfahrt-core/-/issues/90

Introduce journey ticker information

TRIAS has so called situations - which are essentially ticker news - for departures and trips. In both cases, these situations are not directly linked to one specific departure or trip, but apply to the whole service response:

<TripResponse>
  <TripResponseContext>
    <Situations></Situations>
  </TripResponseContext>
  <TripResult></TripResult>
  <TripResult></TripResult>
</TripResponse>

This is actually a weakness of TRIAS and not correctly implemented by many TRIAS providers, as they were (probably) trying to map their item-specific information into this field, which is now missing some context. E.g. the situation "Ersatzfahrt" would only apply to one specific item, but is here applied to all the items.

trias-client already supports situations for departures and I'm now planning to add this ticker information for journeys as well.

(as requested by Abfahrt Core in https://gitlab.com/andary/abfahrt-core/-/issues/80)

Extending the Providers.md

Hi,

I'm currently working on a similar library, but for python. Therefore I appreciate your collection of providers and I'm glad I found it. The only other list I am aware of is this (german) one.

As I want to test my python client on different APIs I would be happy to submit a MR to extend or update the list by updating information or links, adding new providers or add additional information.

However, I also think that such a list of providers should in the best case be available independent of a software solution in the long term. Some places to put it could be either the VDV GitHub where the specification of TRIAs is also located or a Wiki like TransitWiki What are your thoughts on that?

For now if I find anything worth updating in the providers.md I would submit a Pull Request, if that works for you.

Regards

Max

Add docs

Add detailed documentation on the methods, their options and the results.