Implement MOTIS provider and Transitous by dancojocaru2000 · Pull Request #713 · schildbach/public-transport-enabler

dancojocaru2000 · 2026-05-10T07:13:13Z

I got hyperfixated so I spent the night implementing a MOTIS provider.

traines-source · 2026-05-12T16:48:21Z

Very cool! I hope that this way we can finally get Transitous in Öffi etc.!
For the sake of completeness, there had been existing work in another fork of PTE: https://gitlab.com/jbb/public-transport-enabler/-/tree/transitous?ref_type=heads (and apparently elsewhere more recently, which I haven't found though)

schildbach

Thanks for your contribution! I did a first review, and this generally looks very good!

It's probably too late now, but do you like the org.json API? Would you have preferred using a different JSON API?

schildbach · 2026-05-14T14:11:14Z

Unit tests pass as well 😃

dancojocaru2000 · 2026-05-14T14:24:22Z

org.json is fine, I don't think I have a strong preference

dancojocaru2000 · 2026-05-14T15:07:45Z

One issue that has been brought to my attention which needs to be addressed is that the Transitous API Usage has the following requirements:

Make sure your send HTTP User-Agent headers with every request, at least containing the following information:

Name of the application

Version of the client implementation

A way of contact (e-mail address or website URL)

I'm unsure how to handle this in the library, given that the application which uses the library (Öffi, Transportr, etc) will have to set its own user agent.

Co-authored-by: santawho <196087559+santawho@users.noreply.github.com>

MOTIS returns only one station ID corresponding to one dataset, but fetching the departures of that ID only returns the departures from that dataset. That means departures from the other datasets would get left out.

schildbach · 2026-05-14T22:07:43Z

I'm unsure how to handle this in the library, given that the application which uses the library (Öffi, Transportr, etc) will have to set its own user agent.

Yes, the apps need to call TransitousProvider.setUserAgent() then. I have never added email adresses or URLs to user agents though.

I think it would be nice to mention this requirement (maybe link to it) in the class-level JavaDoc, otherwise people maybe simply miss it.

dancojocaru2000 · 2026-05-14T22:10:07Z

Would it be reasonable to set a default bad user agent (something like CHANGE ME), and then throw an exception if that wasn't explicitly modified, to make sure a library user is aware of the requirement?

schildbach · 2026-05-14T22:15:24Z

Would it be reasonable to set a default bad user agent (something like CHANGE ME), and then throw an exception if that wasn't explicitly modified, to make sure a library user is aware of the requirement?

Rather than setting a weird user agent, we could also check against the default null. Currently though there is no getter for the user agent.

But it feels to me this is a bit over the top anyway.

dancojocaru2000 · 2026-05-14T22:16:35Z

Then I'll add the JavaDoc and undraft the PR.

traines-source · 2026-05-16T18:35:44Z

I think over at santawho#3 people added some more tweaks that are relevant, e.g. making distance nullable.
Also it would be good for apps using this to visibly put https://transitous.org/sources/ somewhere (and probably also attribute OSM directly). The Transitous usage policy will include this soon to make these requirements clearer :)

schildbach · 2026-05-30T13:16:18Z

I just tried this branch in Öffi. See https://gitlab.com/oeffi/oeffi/-/tree/motis?ref_type=heads if interested.

Öffi Stations:

It detects Tram and Bus stations in my vicinity, but only up to 500m. That's probably not enough for more sparsely populated areas than mine (Berlin).
None of the 5 detected stations show any departures. I'll crosscheck with other services if that's really the case, atm I think it's probably a matter of missing data.

Öffi Directions:

Stations seem to be autocompleted fine, I picked a station from Berlin and one from Munich.
Actually querying crashed:

05-30 15:07:37.900 27110 27110 E AndroidRuntime: Caused by: java.io.NotSerializableException: okhttp3.HttpUrl
05-30 15:07:37.900 27110 27110 E AndroidRuntime: 	at java.io.ObjectOutputStream.writeObject0(ObjectOutputStream.java:1240)
05-30 15:07:37.900 27110 27110 E AndroidRuntime: 	at java.io.ObjectOutputStream.defaultWriteFields(ObjectOutputStream.java:1620)
05-30 15:07:37.900 27110 27110 E AndroidRuntime: 	at java.io.ObjectOutputStream.writeSerialData(ObjectOutputStream.java:1581)
05-30 15:07:37.900 27110 27110 E AndroidRuntime: 	at java.io.ObjectOutputStream.writeOrdinaryObject(ObjectOutputStream.java:1490)
05-30 15:07:37.900 27110 27110 E AndroidRuntime: 	at java.io.ObjectOutputStream.writeObject0(ObjectOutputStream.java:1234)
05-30 15:07:37.900 27110 27110 E AndroidRuntime: 	at java.io.ObjectOutputStream.defaultWriteFields(ObjectOutputStream.java:1620)
05-30 15:07:37.900 27110 27110 E AndroidRuntime: 	at java.io.ObjectOutputStream.writeSerialData(ObjectOutputStream.java:1581)
05-30 15:07:37.900 27110 27110 E AndroidRuntime: 	at java.io.ObjectOutputStream.writeOrdinaryObject(ObjectOutputStream.java:1490)
05-30 15:07:37.900 27110 27110 E AndroidRuntime: 	at java.io.ObjectOutputStream.writeObject0(ObjectOutputStream.java:1234)
05-30 15:07:37.900 27110 27110 E AndroidRuntime: 	at java.io.ObjectOutputStream.writeObject(ObjectOutputStream.java:354)
05-30 15:07:37.900 27110 27110 E AndroidRuntime: 	at android.os.Parcel.writeSerializable(Parcel.java:3086)

I'll investigate and will report back.

schildbach · 2026-05-30T13:20:48Z

+        protected String nextPageCursor;
+        @Nullable
+        protected String previousPageCursor;
+        protected HttpUrl endpoint;


Sadly the OkHttp HttpUrl class is not serializable, while QueryContext is (and Serialization is used by Öffi).

I see these options:

just store the URL as String – probably easiest

keep HttpUrl but implement custom serialization for that field – somewhat ugly

somehow get rid of Serialization completely (in Öffi, but probably other consumers too) – in this case, no changes necessary

schildbach · 2026-05-30T13:24:48Z

None of the 5 detected stations show any departures. I'll crosscheck with other services if that's really the case, atm I think it's probably a matter of missing data.

Does Transitious actually have departure times (live or planned)? On https://transitous.org/ I only see trip planning, not any station boards.

Edit: I just searched for "Hauptbahnhof" in Öffi Stations and got somewhat random 10 Hauptbahnhöfe, with 9 of them showing no departures. "Gera Hauptbahnhof" however shows a bunch and they are nicely formatted. However most departures are hours ago – not that useful.

traines-source · 2026-05-30T17:42:53Z

Transitous does have departure times, see e.g. https://api.transitous.org/?stopArriveBy=false&stopId=de-DELFI_de%3A05915%3A7756_G&time=2026-05-30T17%3A29%3A00.000Z (this is a link to the web UI, which uses the stoptimes API, as does this PR). I'm not sure what issues you are facing, in Germany the coverage should be mostly complete and over in ÖffiNG everything seems to work as well. (Also it can be beneficial to use the new center param if the app remembers the coordinates of saved locations anyways, since stop ids are not very stable in the source feeds...)

For the nearby view, instead of the reverse-geocode endpoint it is probably better to also use the stoptimes endpoint with a larger radius or the /map/stops endpoint (which only includes the stops and no departures). Reverse-geocode is hardcoded to 500 meters radius indeed.

schildbach · 2026-05-31T10:41:30Z

This PR uses this endpoint for departure times:

https://api.transitous.org/api/v5/stoptimes?stopId=de-DELFI_de%3A08111%3A2492&exactRadius=false&radius=200&n=200&time=2026-05-31T12%3A34%3A00.0%2B0200

This example station (Stuttgart Hauptfriedhof) yields "no departures" in Öffi, despite including a list of 180 "stop times". However I don't actually see any date/time field in these stop times (but I'm new to the API so I just might oversee things).

Edit: Ah, it's (somewhat unintuitively) in the place sub-map: fields departure and scheduledDeparture

traines-source · 2026-05-31T10:52:05Z

The times are contained in place.{arrival|scheduledArrival|departure|scheduledDeparture}.
Maybe boolean equivs is the culprit? In Transitous, depending on the source feed, individual stops are usually platforms/bays. If you filter for really just the stop you requested, this will lead to unexpected results. You may use the parentId to group stops or remove the radius param and rely on Transitous/MOTIS to do the equivalence logic for you, which will also include departures from different feeds (e.g. when the local public transport stems from a different source feed than the long distance transport, they will never have the same parentId, but hopefully be returned by the stoptimes endpoint even without radius.

schildbach · 2026-05-31T10:54:25Z

+                    final JSONObject place = stopTime.getJSONObject("place");
+                    final String departureStopId = place.getString("stopId");
+
+                    if (!equivs && !stationId.equals(departureStopId)) {


I think this conditional fails way more often than it should, leading to no departures being returned if equivs is false (always false in Öffi Departures).

Would it be an option to also test againt parentId, or would that lead to too many results?

schildbach · 2026-05-31T11:06:07Z

The times are contained in place.{arrival|scheduledArrival|departure|scheduledDeparture}. Maybe boolean equivs is the culprit?

Yes, I just came to the same conclusions.

In Transitous, depending on the source feed, individual stops are usually platforms/bays. If you filter for really just the stop you requested, this will lead to unexpected results. You may use the parentId to group stops or remove the radius param and rely on Transitous/MOTIS to do the equivalence logic for you, which will also include departures from different feeds (e.g. when the local public transport stems from a different source feed than the long distance transport, they will never have the same parentId, but hopefully be returned by the stoptimes endpoint even without radius.

I'd be happy to remove the client-side filter, if that were possible. It would also save resources.

So are you saying that if we remove the radius and exactRadius URL parameters this would lead to a sensible "no equivs" behaviour?

schildbach · 2026-05-31T11:29:22Z

+            endpointBuilder.setQueryParameter("window", String.valueOf(3600));
+        }
+        if (time != null) {
+            endpointBuilder.addQueryParameter("time", new SimpleDateFormat("yyyy-MM-dd'T'h:m:ss.SZ").format(time));


The time format is incorrect. Please use HH for hours to use 24 hour format. And mm for minutes so that it's always two digits.

About the S: Does motis really support milliseconds? Their examples don't imply so. I'd consider removing it.

About the Z: Have you considered passing in time as UTC always? In that case, you'd need to pass a literal Z as timezone.

schildbach · 2026-05-31T11:29:33Z

+            throw new IllegalArgumentException("to needs to be stop or have coordinates: " + to);
+        }
+
+        endpointBuilder.addQueryParameter("time", new SimpleDateFormat("yyyy-MM-dd'T'h:m:ss.SZ").format(date));


traines-source · 2026-05-31T11:45:25Z

Yes it's unfortunately a bit complicated. And just today with the new MOTIS release deployed to Transitous, the equivalence logic has been considerably improved.

I've thought about it again. For both equivs=false and equivs=true I think you should use

(optionally) stopId
(more importantly, if possible) center (stopIds can change, not very often, but they do, the position of the stops hopefully less so, so if the stops are stored somewhere as favorites etc. better to not rely on the stopId – if you provide both stopId and center, the latter will only be used as a fallback
exactRadius=false
and then for equivs=false a radius like 50 meters. Als long as exactRadius is false, this will return stops outside of the radius that MOTIS/Transitous considers equivalent in the narrower sense, i.e. very similar stop name and essentially the same station, i.e. can be shown in a departure view without absolutely having to name the stop for each entry. This is of course a heuristic and the quality might vary depending on region.
for equivs=true a radius like 500 meters. Meaning for each entry in the UI, you need to show the actual departure station, and you might want to group by parentId.

schildbach · 2026-05-31T12:10:02Z

I just worked on some patches to queryDepartures() that finally made it to show departures in my vicinity.

However, I now seriously consider removing equivs from the PTE queryDepartures() API, and make the result structure simpler (basically, replace the ID→StationDepartures map by just one StationDepartures). It has always been a pain, and never been used by Öffi afair.

Any thoughts about this change? It would not affect queryTrips() btw.

traines-source · 2026-05-31T12:16:11Z

Idk I think it is a useful distinction, depending on the usecase, and something that all timetable information systems do in one way or another. Just that the definition of "equivalent" and "same" is of course very vague and depending on use case as well. Also in some sense it would be a breaking change to PTE.

schildbach · 2026-05-31T12:16:22Z

(optionally) stopId

(more importantly, if possible) center (stopIds can change, not very often, but they do, the position of the stops hopefully less so, so if the stops are stored somewhere as favorites etc. better to not rely on the stopId – if you provide both stopId and center, the latter will only be used as a fallback

I know the pain of changing stop IDs. It has always been a problem with the other APIs as well. However, geo-coordinates change too.

As long as https://api.transitous.org/api/v1/reverse-geocode?place=…&type=STOP returns up-to-date stop IDs, there is only one problem with changing stop IDs: station favorites. But users can migrate them, and Öffi could even help them with that (currently it doesn't).

At the moment I suspect it might be a problem to use complex structures like a map with a geo-coordinates as a station ID in Öffi.

traines-source · 2026-05-31T12:22:18Z

The detour via reverse-geocode would be unnecessary, since stoptimes already supports querying by coordinates (reason why I think also for the nearby feature it or /map/stops is the better option).
You could just consider the comma-separated coordinates as the stop id string. But yeah thats of course a tradeoff. I would have said if the coordinates change by more than 50 meters, it's essentially a different stop. But using the actual stopId should also work in most cases, it's not like they change every other day (but probably more often than in a typical HAFAS system).

schildbach · 2026-05-31T12:30:59Z

and then for equivs=false a radius like 50 meters. Als long as exactRadius is false, this will return stops outside of the radius that MOTIS/Transitous considers equivalent in the narrower sense, i.e. very similar stop name and essentially the same station, i.e. can be shown in a departure view without absolutely having to name the stop for each entry. This is of course a heuristic and the quality might vary depending on region.

I fear this will fail in too many ways, and be a pain to maintain – especially world-wide.

I just tested removing the radius and exactRadius for the equivs=false case (on top of some other necessary patches), and it seemed to work fine for Berlin:

simple bi-directional and uni-directional Bus/Tram stops
crossings of two Bus or Tram lines (typically resulting in 4 positions)
larger crossings of three or more modes
crossings with products from different public transport companies
huge multi-mode hubs like Berlin Hauptbahnhof

So I wonder what's the specific reason for including a 50 meters radius in the query?

traines-source · 2026-05-31T12:35:43Z

50 meter radius would just be needed when using center. It would still include all the equivalences you mentioned above also beyond the radius (as long as exactRadius is not set to true), i.e. you could also set it to 1 meter – it is just to enable the "coordinates-as-stopid" workaround while allowing for some small coordinate change hopefully without including any unrelated stations that are not the "same" according to MOTIS.

schildbach · 2026-05-31T15:47:44Z

I propose PR #723 which removes the equivs concept from queryDepartures(). Feel free to comment there.

If/when it is merged, I can add the necessary changes to this PR.

cyroxx · 2026-09-13T23:43:56Z

Hi @dancojocaru2000, hi @schildbach,

I'd like to help move this PR forward. I'm particularly interested in using Transitous/MOTIS for Seattle, so I wanted to test the provider against a region outside Europe and report back with something reproducible.

Based on this thread, I backported a few small fixes on top of this branch, verified with unit tests and a live run against api.transitous.org:

Serializable QueryTripsContext: AbstractMotisProvider.QueryContext stored the MOTIS endpoint as okhttp3.HttpUrl, which is not Serializable. This is exactly the java.io.NotSerializableException: okhttp3.HttpUrl @schildbach ran into testing this in Öffi. I now store it as a String and re-parse it with HttpUrl.parse(...) in queryMoreTrips(), plus added an explicit serialVersionUID and a round-trip serialization unit test.
ISO-8601 UTC time formatting: replaced the SimpleDateFormat("yyyy-MM-dd'T'h:m:ss.SZ") pattern (12-hour h, un-padded m, not thread-safe) with DateTimeFormatter.ISO_INSTANT on the UTC instant, used both in queryDepartures() and queryTrips().
Nullable walking-leg distance: parseMotisItinerary() required a distance field on individual (e.g. walking) legs via getDouble(...). MOTIS can omit it; switched to optDouble(..., 0.0), with a unit test covering a leg JSON without distance.

I also added two live test cases to TransitousProviderLiveTest for Seattle (Westlake Station ↔ SeaTac Airport), verified locally against the live API — they exercise Sound Transit Link light rail and King County Metro bus data via Transitous.

I deliberately did not touch queryDepartures()'s equivs handling, since that's already being discussed in #723.

See this branch for details: https://github.com/cyroxx/public-transport-enabler/tree/motis
It contains 4 small commits on top of this PR's motis branch.

Please let me know how you'd like to proceed.

dancojocaru2000 force-pushed the motis branch 4 times, most recently from 6d757f9 to f19c9b4 Compare May 12, 2026 07:52

schildbach reviewed May 14, 2026

View reviewed changes

Implement MOTIS provider and Transitous

a30d52c

dancojocaru2000 force-pushed the motis branch 2 times, most recently from a3f1bd9 to d0e9973 Compare May 14, 2026 15:04

MOTIS: Fix styling

c560e95

dancojocaru2000 force-pushed the motis branch from d0e9973 to c560e95 Compare May 14, 2026 15:05

dancojocaru2000 marked this pull request as draft May 14, 2026 15:05

dancojocaru2000 and others added 4 commits May 14, 2026 17:18

MOTIS: Include high speed trains in default products

cee88c6

Co-authored-by: santawho <196087559+santawho@users.noreply.github.com>

MOTIS: Improve stop name cleaning

1c7df4a

MOTIS: Add radius parameter to queryDepartures

ad8b118

MOTIS returns only one station ID corresponding to one dataset, but fetching the departures of that ID only returns the departures from that dataset. That means departures from the other datasets would get left out.

MOTIS: Implement equals and hashCode for context

2e30551

dancojocaru2000 force-pushed the motis branch from 4a287d9 to 2e30551 Compare May 14, 2026 16:21

dancojocaru2000 marked this pull request as ready for review May 14, 2026 22:24

dancojocaru2000 force-pushed the motis branch from 3a0f120 to aa9214b Compare May 14, 2026 22:27

Transitous: document user agent requirement

0936ff4

dancojocaru2000 force-pushed the motis branch from aa9214b to 0936ff4 Compare May 14, 2026 22:28

1Maxnet1 mentioned this pull request May 29, 2026

Worldwide routing with transitous.org grote/Transportr#954

Open

schildbach reviewed May 30, 2026

View reviewed changes

schildbach reviewed May 31, 2026

View reviewed changes

michaelblyons mentioned this pull request Jun 10, 2026

GTFS without Navitia #555

Open

Conversation

dancojocaru2000 commented May 10, 2026

Uh oh!

traines-source commented May 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

schildbach left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

schildbach commented May 14, 2026

Uh oh!

dancojocaru2000 commented May 14, 2026

Uh oh!

dancojocaru2000 commented May 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

schildbach commented May 14, 2026

Uh oh!

dancojocaru2000 commented May 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

schildbach commented May 14, 2026

Uh oh!

dancojocaru2000 commented May 14, 2026

Uh oh!

traines-source commented May 16, 2026

Uh oh!

schildbach commented May 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

schildbach May 30, 2026

Choose a reason for hiding this comment

Uh oh!

schildbach commented May 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

traines-source commented May 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

schildbach commented May 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

traines-source commented May 31, 2026

Uh oh!

schildbach May 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

schildbach commented May 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

schildbach May 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

schildbach May 31, 2026

Choose a reason for hiding this comment

Uh oh!

traines-source commented May 31, 2026

Uh oh!

schildbach commented May 31, 2026

Uh oh!

traines-source commented May 31, 2026

Uh oh!

schildbach commented May 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

traines-source commented May 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

schildbach commented May 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

traines-source commented May 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

traines-source commented May 12, 2026 •

edited

Loading

dancojocaru2000 commented May 14, 2026 •

edited

Loading

dancojocaru2000 commented May 14, 2026 •

edited

Loading

schildbach commented May 30, 2026 •

edited

Loading

schildbach commented May 30, 2026 •

edited

Loading

traines-source commented May 30, 2026 •

edited

Loading

schildbach commented May 31, 2026 •

edited

Loading

schildbach May 31, 2026 •

edited

Loading

schildbach commented May 31, 2026 •

edited

Loading

schildbach May 31, 2026 •

edited

Loading

schildbach commented May 31, 2026 •

edited

Loading

traines-source commented May 31, 2026 •

edited

Loading

schildbach commented May 31, 2026 •

edited

Loading

traines-source commented May 31, 2026 •

edited

Loading