Einleitung

Der Tagesfahrplan Service stellt einen Fahrplan inklusive Sollzugbildung und Verspätungsdaten über eine REST Schnittstelle bereit.

Beschreibung der Schnittstelle

Das encoding ist generell UTF-8, d.h. sämtliche Parameter werden als UTF-8 interpretiert [1] und ohne Angabe eines charsets im "Accept" header, wird XML mit encoding UTF-8 zurückgeliefert.

DailyTimetable

Liefert die Fahrplandaten eines Kalendertages, d.h. die Daten sätmlicher Fahrten, deren geplantes Abfahrtsdatum diesem Tag entspricht. Dabei werden Fahrten grundsätzlich immer komplett zurückgeliefert, es werden also auch Halte nach Mitternacht geliefert, falls die Fahrt (geplant) vor 24:00 gestartet ist.

URL: /timetable/{client}/{network}/{date} bzw. /timetable/{client}/{network}

Table 1. Parameter "DailyTimetable"
Parameter Multiplizität Typ Beschreibung

client

1

Aufzählungstyp

Der Name des Mandanten
Die gültigen Werte sind konfigurationsabhängig.

network

1

Aufzählungstyp

Das Name des Netzes
Die gültigen Werte hängen vom gewählten Client / Mandanten ab.\ Der Wert "all" ist grundsätzlich immer gültig und liefert Daten sämtlicher Netze des jeweiligen Mandanten ohne Beschränkung.

date

0..1

Datum

Datum des Kalendertages im ISO 8601 Format JJJJ-MM-TT

Erläuterungen:

  • client
    Die Werte dieses Aufzählungstypen hängen von der Konfiguration der Schnittstelle ab. Es kann lediglich ein einziger Mandant oder gleichzeitig mehrere unterstützt werden.

    Fehlerhafte bzw. genauer unbekannte Werte werden mit HTTP code 400 (Bad Request) quittiert.

  • network
    Dieser Parameter identifiziert das Netz, für das der Fahrplan ausgegeben werden soll. Die gültigen Werte dieses Aufzählungstypen hängen vom gewählten Mandanten ab. Falls das Netz beschränkt wird, werden Fahrten, die gar keinem Netz zugeordnet sind (z.B. ungeplante Fahrten) nicht zurückgeliefert. Der Wert "all" ist grundsätzlich immer gültig und adressiert sämtliche Netze des jeweiligen Mandanten ohne Beschränkung. D.h. hier wären dann auch Fahrten ohne Netzzuordnung enthalten.

    Unbekannte Werte werden mit HTTP code 400 (Bad Request) quittiert.

  • date
    Der Kalendertag, für den der Fahrplan ausgegeben werden soll. Wird hier kein Datum angegeben, so wird der aktuelle Tag adressiert. Liegt der Tag in der Vergangenheit, so können geplante und tatsächliche Zeiten/Fahrverläufe ausgegeben werden, ansonsten können lediglich Planzeiten (ohne Verspätungsdaten) angezeigt werden und dies auch nur, sofern ein Vorladeprozess diese Daten zur Verfügung gestellt hat.

Bei sämtlichen Parametr wird zwischen Groß- und Kleinschreibung unterschieden. Normalerweise sind die Werte aller Aufzählungstyp in Kleinschreibung definiert.

Beispiel request / response

GET /timetable/{client}/all/2019-03-15 HTTP/1.1
Host: timetable-rest.etc-consult.de
Authorization: Basic cm9iaW46TWpMU3ctdXdtU3Rs
Accept: application/xml
Accept-Language: en

XML Schema

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<xs:schema attributeFormDefault="unqualified" elementFormDefault="qualified" version="1.0" targetNamespace="https://www.etc-consult.de/namespace/timetable" xmlns:tns="https://www.etc-consult.de/namespace/timetable" xmlns:xs="http://www.w3.org/2001/XMLSchema">

  <xs:element name="DailyTimetable" type="tns:dailyTimetable"/>

  <xs:complexType name="dailyTimetable">
    <xs:sequence>
      <xs:element name="trains" minOccurs="0">
        <xs:complexType>
          <xs:sequence>
            <xs:element name="train" type="tns:train" minOccurs="0" maxOccurs="unbounded"/>
          </xs:sequence>
        </xs:complexType>
      </xs:element>
    </xs:sequence>
    <xs:attribute name="type" type="xs:string" use="required"/>
    <xs:attribute name="date" type="xs:date" use="required"/>
    <xs:attribute name="railwayCompany" type="xs:string" use="required"/>
    <xs:attribute name="network" type="xs:string" use="required"/>
    <xs:attribute name="direction" type="xs:int" use="required"/>
  </xs:complexType>

  <xs:complexType name="train">
    <xs:sequence>
	  <xs:element name="throughService" type="tns:throughService" minOccurs="0" maxOccurs="1"/>
	  <xs:element name="stops" minOccurs="0">
        <xs:complexType>
          <xs:sequence>
            <xs:element name="stop" type="tns:stop" minOccurs="0" maxOccurs="unbounded"/>
          </xs:sequence>
        </xs:complexType>
      </xs:element>
    </xs:sequence>
    <xs:attribute name="number" type="xs:int" use="required"/>
    <xs:attribute name="dayOfOperation" type="xs:string" use="required"/>
    <xs:attribute name="networkName" type="xs:string"/>
  </xs:complexType>

 <xs:complexType name="throughService">
    <xs:sequence>
     <xs:element name="administrationFrom" type="xs:string"  minOccurs="1"/>
	 <xs:element name="administrationTo" type="xs:string"  minOccurs="1"/>
	 <xs:element name="trainnumber" type="xs:string" minOccurs="1"/>
	 <xs:element name="ibnr" type="xs:string" minOccurs="1"/>
  </xs:sequence>
  </xs:complexType>

  <xs:complexType name="stop">
    <xs:sequence>
      <xs:element name="line" type="xs:string" minOccurs="0"/>
      <xs:element name="category" type="xs:string" minOccurs="0"/>
      <xs:element name="distanceNextStop" type="xs:long" minOccurs="0"/>
      <xs:element name="stopOnRequest" type="xs:boolean"/>
      <xs:element name="arrival" type="xs:dateTime" minOccurs="0"/>
      <xs:element name="departure" type="xs:dateTime" minOccurs="0"/>
      <xs:element name="arrivalDelta" type="xs:duration" minOccurs="0"/>
      <xs:element name="departureDelta" type="xs:duration" minOccurs="0"/>
      <xs:element name="deltaOrigin" type="xs:string" minOccurs="0"/>
      <xs:element name="coordinates" minOccurs="0"  maxOccurs="1">
      <xs:complexType>
        <xs:sequence>
           <xs:element name="location" type="tns:location" minOccurs="0" maxOccurs="unbounded"/>
         </xs:sequence>
        </xs:complexType>
      </xs:element>
      <xs:element name="vehicles" minOccurs="0">
        <xs:complexType>
          <xs:sequence>
            <xs:element name="vehicle" type="tns:vehicle" minOccurs="0" maxOccurs="unbounded"/>
          </xs:sequence>
        </xs:complexType>
      </xs:element>
    </xs:sequence>
    <xs:attribute name="order" type="xs:double" use="required"/>
    <xs:attribute name="name" type="xs:string" use="required"/>
    <xs:attribute name="ibnr" type="xs:string"/>
  </xs:complexType>

  <xs:complexType name="location">
    <xs:sequence>
      <xs:element name="latitude" type="xs:decimal" minOccurs="1"/>
      <xs:element name="longitude" type="xs:decimal" minOccurs="1"/>
    </xs:sequence>
    <xs:attribute name="name" type="xs:string" use="required"/>
  </xs:complexType>

  <xs:complexType name="vehicle">
    <xs:sequence>
      <xs:element name="number" type="xs:string" minOccurs="0"/>
      <xs:element name="abbreviation" type="xs:string" minOccurs="0"/>
    </xs:sequence>
    <xs:attribute name="position" type="xs:int" use="required"/>
    <xs:attribute name="circulation" type="xs:string"/>
    <xs:attribute name="circulationStart" type="xs:string"/>
    <xs:attribute name="circulationEnd" type="xs:string"/>
  </xs:complexType>


</xs:schema>
1. Da alle Parameter als Teil der URL übergeben werden, müssen diese selbstverständlich URL kodiert sein. Allerdings ist für Zeichen ausserhalb des ASCII charsets nicht festgelegt, welches charset dabei Verwendung findet, RFC3986 empfiehlt hier lediglich UTF-8. Zum Beispiel wäre ein "ö" im ISO 8859-1 charset URL kodiert "%F6", während es im UTF-8 charset URL kodiert "%C3%B6" wäre.