Documentation on the ref parameter and journeyDetail endpoint in general

[alios]

Hi!

It would be very helpful to know more about the ref parameter. From documentation I only know that it becomes "invalid" after some time. I did some trial on error on that. What I found so far are:

Format of the ref parameter

The format seems to be aaaaaa/bbbbbbb/cccccc/ddddd/ee? where a-e are placeholders for numbers.

• The purpose of aaaaaa, bbbbbb, cccccc is unknown
• The ddddd has only 5 digits (instead of 6) so I thought it might be the "Zugnummer" but this doen't really match: http://www.bahnstatistik.de/Zugnummern.htm
• the ee seems to be always 80 which would match the UIC Number for Germany
• The ? seems to be important - as it is also used to start a http query string it looks some what "strange"

It would be very helpful to know more about the how that number is build and how it matches to an individual train.

the date parameter

You can remove the date parameter from the call which results in almost the same output, but with the date fields missing in the return document.

the links in departure-/arrival-boards

The links to the journeyDetails in arrival-/depaturboards contain all the url params (like lang, date) + some undocumented ones (like station_evaId).

• the "refId" alone would be enough. journeyDetail calls can be build on that. Either add the ref id as an addtional field or even replace the generated links (would reduce returned documents in size).
• the undocumented params should be documented
• in the generated links seem to make sense (date is used to add the date field in the returned document
• others seem to have no purpose at all (lang and station_evaId seem to have no function at all)

  open questions

  1. How is the ref(id) field build and what is the meaning of the individual digits
  2. When and how do the refids expire.
  3. Will an "update" to a the yourney of an individual train (cause a completley random new ref id or is there something like a version (see also 1.)
  4. If I have a date, an indicudual train (f.e. the first IC XXXX in the morning/or a "Zugnummer") can I somehow construft a ref id to look up the details (and maybe later the real time infos) without having to query for a depatureBoard off a city on the route of the train.

[alios]

This kind of relates to #15. Having the id as its own field (without the complete url) and let the user build the journeyDetail url himself would avoid the cross protocol problem.

[highsource]

Hi,

I won't recommend investing much time in this ref parameter. Just treat it as an internal implemlementation detail. This relates to the HaCon software which is actually backing the whole thing. There's also an intermediate proxy which transforms between the internal XML interface and the external JSON/REST-like interface.

What I'll write below are more or less my guesses, so treat them with a grain of salt.

The format aaaaaa/bbbbbbb/cccccc/ddddd/ee more or less corresponds to the internal train id as used by HaCon software. See here, for instance:

https://gist.github.com/highsource/2cf6d51918aab9762b190c334e7ac3ba

However, in case of the DB Fahrplan API it seems like these train ids are randomly remapped. Probably in order to protect parts of the interface which are not set free for open data. For instance, they have to filter out short-distance trains (as these aren't in open data for the moment).

In any case (randomized/remapped or not) these ids are related to the internal train ids and have no functional meaning per se.

The whole ref parameter is apparently a part of the URL which is passed to some internal system when processing. That's why ? is important.

Now to your questions:

1. ref is a part of URL used for an internal request. The id is a randomized/remapped internal train id of HaCon systems.
2. Unclear, my experience is a couple of hours. Not long, not forever.
3. Yes, new random.
4. No. You have to start from the station and date/time and retrieve train runs from departure or arrivals. You may even need to make several requests because you don't necessarily get all the train runs (refs). You have to note the time of the last train run (for this stop) and query again with that time.

But it's all done already. Have you seen this?

• https://github.com/patrickbr/db-api-to-gtfs - the Python script which scrapes the API
• https://github.com/fredlockheed/db-fv-gtfs - timetable for 2016 in GTFS

Hope this helps, Alexey

[highsource]

Now, to wrap up, this ref thing should be considered an internal implementation detail and will not be further documented.