Barrierefreier Zugang zum ÖV 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 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. Die Lizenz ermöglicht Datennutzern, die Originalquellen wiederzuerkennen und bei gemischten Datensätzen auseinanderzuhalten.

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

Bitte verwenden Sie keine Share-Alike oder Non-Commercial-Lizenzen - diese können aufgrund unterschiedlicher internationaler Rechtslagen von Dritten nicht rechtssicher eingebunden werden.

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 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: Orte (z.B. Bahnhöfe) und Equipment (Aufzüge und/oder Fahrtreppen). Diese sollten über zwei verschiedene URL-Pfade abgerufen werden können.
  • Falls die API mehrsprachig angeboten wird, können statt Strings Objekte verwendet werden, in denen jeder angebotenen Locale ein String zugeordnet wird (z.B. { "en": "elevator", "de": "Aufzug", "fr": "ascenseur", "tr": "Asansör"}). Als Keys müssen hierbei IETF Language Tags nach der Spezifikation von RFC5646 verwendet werden.

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

Pagination

Zurückgegebene Listen können 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 Orte 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 Orte (z.B. Bahnhöfe, Einkaufszentren, …)

Dieser Endpoint liefert eine Liste von Orten aus. Falls in der Aufzugs-API OpenStreetMap-IDs als Referenz auf Bahnsteige/Haltepunkte/Bahnhöfe verwendet werden, kann dieser Endpoint auch weggelassen werden, OpenStreetMap wird in diesem Fall als ‘Quelle der Wahrheit’ betrachtet.

Wenn bereits GTFS oder Apples Indoor-Mapping-Format IDMF zum Indoor-Mapping verwendet wird, kann dieser Endpoint weggelassen werden, um Synchronisierungsarbeit zu vermeiden. In diesem Fall reicht es, den Equipment-Endpoint zu implementieren. In diesem Fall muss der Equipment-Endpoint ID-Querreferenzen auf Datensätze aus OSM, GTFS oder IDMF enthalten, um eine Zuordnung zu ermöglichen.

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