Barrierefreier Zugang zum ÖPNV mit Projekt Elevate: Anforderungen an Fahrtreppen- und Aufzug-APIs

Über Projekt Elevate

Projekt Elevate ist ein Projekt des Berliner Sozialhelden e.V. zur Verbesserung der persönlichen Mobilität mit Aufzügen und Fahrtreppen im Öffentlichen Personennah- und fernverkehr.
Im Rahmen des Projekts haben wir die Equipment-Status-APIs einiger Verkehrsunternehmen angebunden und zu einer einheitlichen API harmonisiert. Eins der Projektziele ist, den Live-Status von Fahrtreppen und Aufzügen in Navigations-Apps barrierefrei über eine einheitliche API für App-Entwickler verfügbar zu machen. Auf diese Weise können Reisende die Informationen in Apps wie z.B. wheelmap.org zentral und Verkehrsverbund-übergreifend abrufen.

Welche Lizenz?

Die wahren Möglichkeiten von Open Data werden erst durch die Wahl einer gängigen und standardisierten Lizenz ermöglicht: Wenn jeder Datenherausgeber eigene Nutzungsbedingungen formulieren würde, müssten App-Entwickler jede Quelle erst rechtlich prüfen lassen – eine zu hohe Hürde für Innovation, die selbst bei Unternehmenssoftware oft ihren Ursprung auf informellen Hackathons, in Universitäten oder bei NGOs wie Sozialhelden e.V. findet.

Als Lizenz empfehlen wir die CC0-Lizenz, um Ihre Daten für alle Anwender international rechtssicher gemeinfrei verfügbar zu machen. Hierfür eignet sich das von creative commons angebotene CC0-Tool, mit dem Sie einen passenden Lizenztext mit wenigen Angaben selbst generieren können.

Falls eine Quellenerwähnung rechtlich notwendig oder gewünscht ist, empfehlen wir die CC-BY-4.0 International-Lizenz, unter der die über Ihre API verbreiteten Daten
  • international rechtssicher verwendet und weiterverbreitet werden können
  • solange die Originalquelle genannt wird und Änderungen an den Originaldaten als solche markiert werden.

Unter der CC-BY-4.0-Lizenz bietet u.a. die Deutsche Bahn offene Daten an.

Im Zweifel helfen wir gerne bei der Wahl einer passenden Lizenz.

Generelle Anforderungen an angebundene APIs

Die Anforderungen in diesem Dokument spiegeln unsere Erfahrungen aus Sicht von App-Entwicklern wider und dienen als Checkliste von Empfehlungen, um die Anbindung an Projekt Elevate und andere Navigations-Apps zu vereinfachen.

Durch die Ähnlichkeit zu Datenstrukturen bereits bestehender APIs von Verkehrsverbünden wird sichergestellt, dass Daten ohne großen Implementationsaufwand von dort importiert werden können und App-Entwickler bestehenden Quellcode mit möglichst geringem Aufwand weiterverwenden können.

Die API-Spezifikation ist im Hinblick darauf gestaltet, dass sich die darüber angebotenen Echtzeitdaten in andere Projekte zum Erreichen der Qualitätsstufe 4 des DELFIplus-Projekts einbinden lassen, z.B. OpenStreetMap und OpenStationMap.

  • Die API sollte via HTTP oder HTTPS zur Verfügung stehen (via GET-Request)
  • Als Response-Format eignet sich JSON oder XML am besten (wegen der erhöhten Verbreitung in moderneren Apps bevorzugt JSON)
  • Auf komplexere Autorisierungs-/Authentifizierungs-Verfahren (z.B. OAuth, Token mit kurzem Expire-Datum, signierte Requests) sollte verzichtet werden, da diese einen sehr hohen Implementations- und Wartungsaufwand für App-Entwickler erfordern. Falls die API für die Öffentlichkeit aus technischen Gründen nicht erreichbar sein soll, kann ein Benutzername/Passwort oder Autorisierungstoken-Mechanismus verwendet werden.
  • Zum Tracking von Traffic Quotas und zur Erhöhung der Stabilität der kann ein Token-basiertes Autorisierungsverfahren verwendet werden. Falls ein Token-basiertes Verfahren verwendet wird, sollte ein Prozess bestehen, um Token-Inhaber automatisiert mehrere Monate im Voraus über das Gültigkeitsende zu informieren, um langsamere IT-Abteilungen nicht vom API-Zugang abzuschneiden.
  • Die API sollte mindestens 2 Datentypen unterstützen: PoIs (z.B. Bahnhöfe) und Equipment (Aufzüge und/oder Fahrtreppen). Diese sollten über zwei verschiedene URL-Pfade abgerufen werden können.

Soweit möglich, sollten die beschriebenen Attributnamen verwendet werden.

Pagination

Bei sehr großen Datenmengen können zurückgegebene Listen paginiert sein, um Request-Timeouts zu vermeiden. Um Traffic zu sparen, kann die Rückgabe über Parameter auf bestimmte Felder beschränkt werden, um z.B. nur den Funktionszustand von Equipment abzufragen.

Bei einer paginierten Rückgabe sollte
  • die Anzahl gesamt verfügbarer PoIs oder Seiten als Feld mitgeliefert werden (z.B. "resultCount": 123 oder "pages": 10)
  • via URL-Query-Parameter möglich sein, eine bestimmte Seite abzufragen (z.B. ?skip=2000&limit=1000 zum Abfragen von Resultat 2000-2999)
  • auf eine Seitenabfrage via relativer URLs verzichtet werden, damit ein einzelner Request-Timeout nicht dazu führt, dass die gesamte Datenabfrage danach nicht funktioniert.

Endpoint für PoIs

Dieser Endpoint liefert eine Liste von PoIs aus.

Orte in der Antwort müssen mindestens folgende Datenattribute haben:
id
eine eindeutige ID.
name
Bezeichnung des Orts als String, bei mehrsprachigen Namen als Objekt mit IETF language tags, z.B. { "de": "München Hauptbahnhof", "en": "Munich main railway station" }). Abkürzungen wie ‘Bhf’ sollten hier vermieden werden, damit der Name von Sprachassistenten und Screen-Readern vorgelesen werden kann.
category
Kategoriename des Orts. Wir empfehlen OpenStreetMap-kompatible Kategorie-Tags wie railway:tram_stop, siehe https://wiki.openstreetmap.org/wiki/Map_Features#Stations_and_Stops). Falls alle Orte der Quelle dieselbe Kategorie haben, kann das Feld weggelassen werden.
latitude/longitude
Geokoordinaten (am besten als WGS84/EPSG:4326-Dezimaldarstellung. Andere Koordinatensysteme werden von vielen Geo-Apps, Libraries und Tools nicht unterstützt).

Wir empfehlen, diese weiteren Attribute auszugeben:
ids
Eindeutige IDs innerhalb weiterer, externer Datenquellen zum Vereinheitlichen von Daten (Objekt)
ids.osm
ID zur Zuordnung zu einer Haltestelle aus OpenStreetMap
ids.ifopt
IFOPT-ID für Haltestellen