Show delay times

[thekonz]

There should be data about delays in the API.

It should show in the departureBoard, arrivalBoard and journeyDetail.

Proposed format for departureBoard and arrivalBoard:

"Departure/Arrival": [
    {
        "name": "IC 2264",
        "type": "IC",
        "stopid": "8000191",
        "stop": "Karlsruhe Hbf",
        "time": "19:55",
        "isDelayed": true,
        "delayAmount": "00:05",
        "date": "2016-03-04",
        "direction": "Basel Bad Bf",
        "track": "6",
        "JourneyDetailRef":
        {
            "ref": "http://..."
        }
    }
]

With the isDelayed, you indicate, whether the train is delayed. If you have a delayed train without an estimated amount of delay time, the delayAmount would be 00:00 or null, but the isDelayed still shows the fact, that the train is delayed.

Proposed format for journeyDetail:

"Stops": {
    "Stop": [
        {
            "name": "München Hbf",
            "id": "8000261",
            "lon": "11.558338",
            "lat": "48.140228",
            "routeIdx": "0",
            "depTime": "16:48",
            "isDelayed": true,
            "delayAmount": "00:05",
            "depDate": "2016-03-04",
            "track": "17"
        }
    ]
}

What do you think about the format?

[marcelbuesing]

isDelayed would be fairly subjective. From my perspective one minute late could already mean delayed. I think either a delay, like you mentioned 00:05, or a scheduled arrival 16:48 and actual arrival 16:53 would make more sense.

[highsource]

In Lufthansa API they have:

• scheduledTimeLocal, scheduledTimeUTC
• estimatedTimeLocal``,estimatedTimeUTC`
• actualTimeLocal``,actualTimeUTC`

Both for depature and arrival. They also have timeStatus like delayed or early. This is subjective, but there is some official DB "opinion" on that.

[Stefan-Hintz]

The above Lufthansa API approach looks much more useful to me.
There should be standard date format, which includes time and timezone.
I think, if all dates include the given timezone of the local station, then the UTC fields might not needed.
Having them could be convenient but increases the size of the JSON.

[Stefan-Hintz]

(How would cancelled trains will be displayed?)

I found now the documentation of cancelled trains in:
http://open-api.bahn.de/bin/rest.exe/v1.0/xsd?name=hafasRestDepartureBoard.xsd

It would be nice, if all the spreaded documentation would be here at github. So changed to it would be clearly visible.

[Stefan-Hintz]

What about unknown delay times? https://twitter.com/ntvde/status/740084190843047937

[DaleSchultz]

the data is not mean to be realtime, just the schedule, so no delays or actual arrival/departure data is present.