VAG NürnbergPULS Webservices v1.3

Web-API für Echtzeitinformationen der VAG Nürnberg.
Version v1.3
OpenAPI 3.0.4

Übersicht#

Der PULS REST-Webservice stellt eine XML- oder JSON Schnittstelle bereit, die als entsprechender Service für Externe verwendet werden kann. Die Schnittstelle wird als REST-Service bereitgestellt. Ein anfragendes System, welches Zugang zu den Service-URLs hat, kann in Kenntnis der verwendeten Formate die gewünschten Daten anfragen.

Dieses Dokument liefert als Schnittstellenbeschreibung:

Der Nachrichtenaustausch mit dem Webservice erfolgt über das http-Protokoll. Die Daten des Webservice werden mit dem http-Verb GET angefordert.

Schnittstellenbeschreibung#

Verfügbare Serviceendpunkte der Web-API:

Produktivumgebung: https://start.vag.de/dm/api/v1/
----------------------------------------------------------------------------------
Basis URI für die Services lautet: https://hostname:port/api/…

URI Konvention zu den Services:
Haltestellen-API  …/haltestellen{netvu}?{Querystring}
Abfahren-API      …/abfahrten/{netvu}/{haltid}/{linie}?{Querystring}
Fahrten-API       …/fahrten/{Betriebszweig}/{Betriebstagsdatum}/{Fahrtnummer}?{Querystring}

Format der Antwort als XML oder JSON#

Es ist möglich, das Ergebnis der Anfrage als XML oder JSON zu erhalten. Dies erfolgt über einen entsprechenden Eintrag in dem HTTP-Header der Anfrage.

Per Default wird aktuell JSON zurückgeliefert.

Datum und Zeitformat#

Alle verwendeten Zeitformate werden gemäß ISO 8601 kodiert: 2012-09-26T18:15:28+02:00

Es werden keine weiteren Zeiteinheiten jenseits der Sekunde, also 1/10, 1/100..-Sekunden verwendet.

Zeichensatz#

Als Zeichensatz für die Übertragung wird ausschließlich UTF-8 verwendet.

Haltestellen-API#

Realisiert die Abfrage nach Haltestellen und die Umkreissuche. Die Abfragen können VAG oder VGN orientiert erfolgen. D.h. es werden die jeweiligen Kennungen der Haltestellen bei dem Aufruf des Webservice verwendet.

GET /api/v1/Haltestellen/{netvu}#

Suche nach Haltestellen über den Namen der Haltestelle

Tags: Haltestellen

Parameters

Name In Type Required Description
netvu path string ✓ Netz des Verkehrsunternehmens, aktuell "VAG" oder "VGN"
name query string Name der Haltestelle (like)

Responses

Code Description
200 Liefert eine Liste mit den gefundenen Haltestellen

GET /api/v1/Haltestellen/{netvu}/location#

Liefert eine Liste mit den Haltestellen zu der Umkreissuche

Tags: Haltestellen

Parameters

Name In Type Required Description
netvu path string ✓ Netz des Verkehrsunternehmens, aktuell "VAG" oder "VGN"
lon query number Longitude für die Umkreissuche in WGS 84 Format in Grad
lat query number Latitude für die Umkreissuche in WGS 84 Format in Grad
distance query integer Radius für die Umkreissuche. Defaultwert = 1000 Meter.

Responses

Code Description
200 Liefert zu der Umkreissuche die ermittelten Haltestellen

Abfahrten-API#

Realisiert die Abfrage zu den Abfahrten an einer Haltestelle. Die Abfragen können VAG oder VGN orientiert erfolgen. D.h. es werden die jeweiligen Kennungen der Haltestellen bei dem Aufruf des Webservice verwendet.

GET /api/v1/Abfahrten/{netvu}/{haltid}#

Liefert die Abfahrten für die übergebene Haltestelle

Tags: Abfahrten

Parameters

Name In Type Required Description
netvu path string ✓ Netz des Verkehrsunternehmens, aktuell "VAG" oder "VGN"
haltid path string ✓ Haltestellenkennung je nach NetVU - VGN-Kennung oder die HaltID der VAG
line path string ✓ Linienname der VAG Nürnberg
product query string Betriebszweig der VAG (Bus, Tram, UBahn), Querystring: product=Bus,Tram
timespan query integer Zeitfenster für die Abfrage in Minuten (?timespan=10)
timedelay query integer Zeitliche Verschiebung für die Anfrage in Minuten (?timedelay=5)
limitcount query integer Maximale Anzahl der zurückgelieferten Abfahrten

Responses

Code Description
200 Liefert die Abfahrten zu der angegebenen Haltestelle
400 Fehlerhafte Anfrage
404 Eine Haltestelle mit der angegebenen Kennung existiert nicht

GET /api/v1/Abfahrten/{netvu}/{haltid}/{line}#

Liefert die Abfahrten für die übergebene Haltestelle und Linie

Tags: Abfahrten

Parameters

Name In Type Required Description
netvu path string ✓ Netz des Verkehrsunternehmens, aktuell "VAG" oder "VGN"
haltid path string ✓ Haltestellenkennung je nach NetVU - VGN-Kennung oder die HaltID der VAG
line path string ✓ Linienname der VAG Nürnberg
product query string Betriebszweig der VAG (Bus, Tram, UBahn), Querystring: product=Bus,Tram
timespan query integer Zeitfenster für die Abfrage in Minuten (?timespan=10)
timedelay query integer Zeitliche Verschiebung für die Anfrage in Minuten (?timedelay=5)
limitcount query integer Maximale Anzahl der zurückgelieferten Abfahrten

Responses

Code Description
200 Liefert die Abfahrten zu der angegebenen Haltestelle
400 Fehlerhafte Anfrage
404 Eine Haltestelle mit der angegebenen Kennung existiert nicht

Fahrten-API#

Die Fahrten-API dient der Abfrage von Echtzeitinformationen zu den Fahrten eines Betriebstages. Dabei können zum einen alle laufenden Fahrten als auch bestimmte Fahrten direkt abgefragt werden.

GET /api/v1/Fahrten/{betriebszweig}#

Liefert zu dem übergebenen Betriebszweig die aktuellen Fahrten

Tags: Fahrten

Parameters

Name In Type Required Description
betriebszweig path string ✓ Betriebszweig der Fahrten: Bus
timespan query integer Zeitfenster für die Abfrage in Minuten (Default: 60 Minuten)

Responses

Code Description
200 Liefert anhand des angegebenen Betriebszweiges die gefundenen Fahrten
400 Der angegebene Betriebszweig existiert nicht

GET /api/v1/Fahrten/{betriebszweig}/{fahrtnummer}#

Liefert zu den übergebenen Parametern die gefundene Fahrt

Liefert zu dem angegebenen Betriebszweig mit der Fahrtnummer und dem angegebenen Betriebstag die gefundene Fahrt inklusive des Fahrtverlaufes

Tags: Fahrten

Parameters

Name In Type Required Description
betriebszweig path string ✓ Betriebszweig der VAG: Bus
fahrtnummer path integer ✓ Fahrtnummer der Fahrt
betriebstag path string ✓ Betriebstagsdatum der Fahrt (optional)

Responses

Code Description
200 Liefert anhand der angegebenen Parameter die gefundene Fahrt
400 Der angegebene Betriebszweig existiert nicht
404 Eine Fahrt mit den angegebenen Parametern existiert nicht

GET /api/v1/Fahrten/{betriebszweig}/{betriebstag}/{fahrtnummer}#

Liefert zu den übergebenen Parametern die gefundene Fahrt

Liefert zu dem angegebenen Betriebszweig mit der Fahrtnummer und dem angegebenen Betriebstag die gefundene Fahrt inklusive des Fahrtverlaufes

Tags: Fahrten

Parameters

Name In Type Required Description
betriebszweig path string ✓ Betriebszweig der VAG: Bus
fahrtnummer path integer ✓ Fahrtnummer der Fahrt
betriebstag path string ✓ Betriebstagsdatum der Fahrt (optional)

Responses

Code Description
200 Liefert anhand der angegebenen Parameter die gefundene Fahrt
400 Der angegebene Betriebszweig existiert nicht
404 Eine Fahrt mit den angegebenen Parametern existiert nicht

Schemas#

V1 - AbfahrtDto#

Datenklasse für die Abfahrtsdaten einer Fahrt an einem Haltepunkt

Field Type Required Description
linienname string Name der Linie der Fahrt
haltepunkt string Referenz auf die Halteposition
richtung string Richtung (1 oder 2)
richtungstext string Richtungstext der Fahrt
ankunftszeitSoll string Planmässige Ankunft (Zeit und Datum, nicht bei Starthaltestelle)
ankunftszeitIst string Prognostizierte Ankunft (Zeit und Datum)
abfahrtszeitSoll string Planmässige Abfahrt (Zeit und Datum, nicht bei Endhaltestelle)
abfahrtszeitIst string Abfahrtszeit und –datum (nicht bei Endhaltestelle)
produkt string Produkt / Fahrzeugtyp
longitude number Längengrad auf dem sich die Halteposition befindet
latitude number Breitengrad auf dem sich die Halteposition befindet
fahrtnummer integer Fahrtnummer
betriebstag string Datum des Betriebstages
fahrtartnummer integer Fahrtartnummer
fahrzeugnummer string Betriebliche Fahrzeugnummer des Fahrzeuges kommt über das ITCS
besetztgrad string Fahrzeugauslastung - Besetztgrad -> 0: Unbekannt, 1: Schwachbesetzt, 2: Starkbesetzt, 3: Überfüllt
prognose boolean true, falls Prognose möglich
haltesteigText string Bezeichnung des Steigs des Haltepunkts
abfahrtszeitenAusblenden boolean true, falls Abfahrtszeiten ausgeblendet werden sollen

V1 - AbfahrtenApiResponse#

Field Type Required Description
metadata V1 - Metadata
haltestellenname string Haltestellenname
vagKennung string VAG-Kennung der zugehörigen Haltestelle
vgnKennung integer VGN-Kennung der zugehörigen Haltestelle
abfahrten array of See V1 - AbfahrtDto Liste der zugehörigen Abfahrten
sonderinformationen array of string Sonderinformationen der Haltestelle

V1 - ErrorApiResponse#

Error - Antwort der Puls-API V1

Field Type Required Description
message string Text der Fehlermeldung

V1 - FahrtDto#

Antwortobjekt für eine Fahrt in der Fahrtenliste

Field Type Required Description
fahrtnummer integer Fahrtnummer
linienname string Name der Linie
richtung string Richtung (1 oder 2)
richtungstext string Richtungstext der Fahrt
betriebstag string Datum des Betriebstages
startzeit string Planmäßige Startzeit der Fahrt
endzeit string Planmäßige Endzeit der Fahrt
startHaltID string Referenz auf die geplante Start-Halteposition
endHaltID string Referenz auf die geplante End-Halteposition
faelltAus boolean Fahrt fällt aus
zusatzfahrt boolean Bei der Fahrt handelt es sich um eine außerplanmäßige Fahrt
fahrzeugnummer string Betriebliche Fahrzeugnummer des Fahrzeuges kommt über das ITCS
besetztgrad string Fahrzeugauslastung - Besetztgrad
0: Unbekannt, 1: Schwachbesetzt, 2: Starkbesetzt, 3: Überfüllt
prognose boolean true, falls Prognose möglich

V1 - FahrtenApiResponse#

Field Type Required Description
metadata V1 - Metadata
linienname string Name der Linie der Fahrt
richtung string Richtung (1 oder 2)
richtungstext string Richtungstext der Fahrt
fahrtnummer integer Fahrtnummer der Fahrt
betriebstag string Datum des Betriebstages
Produkt string Produkt / Fahrzeugtyp
faelltAus boolean Fahrt fällt aus
zusatzfahrt boolean Bei der Fahrt handelt es sich um eine außerplanmäßige Fahrt
fahrzeugnummer string Betriebliche Fahrzeugnummer des Fahrzeuges kommt über das ITCS
besetztgrad string Fahrzeugauslastung - Besetztgrad
0: Unbekannt, 1: Schwachbesetzt, 2: Starkbesetzt, 3: Überfüllt
prognose boolean true, falls Prognose möglich
Fahrtverlauf array of See V1 - FahrwegHaltepositionDto Haltepositionen des Fahrtverlaufes
fahrten array of See V1 - FahrtDto Liste mit der Fahrten

V1 - FahrwegHaltepositionDto#

Halteposition zu einer Fahrt

Field Type Required Description
haltestellenname string Haltestellenname
vagKennung string VAG-Kennung der zugehörigen Haltestelle
vgnKennung integer VGN-Kennung der zugehörigen Haltestelle
haltepunkt string Eindeutige Kennung der Halteposition bei der VAG Nürnberg
ankunftszeitSoll string Planmässige Ankunft (Zeit und Datum, nicht bei Starthaltestelle)
ankunftszeitIst string Prognostizierte Ankunft (Zeit und Datum)
abfahrtszeitSoll string Planmässige Abfahrt (Zeit und Datum, nicht bei Endhaltestelle)
abfahrtszeitIst string Abfahrtszeit und –datum (nicht bei Endhaltestelle)
richtungstext string Richtungstext der Fahrt
longitude number Längengrad auf dem sich die Halteposition befindet
latitude number Breitengrad auf dem sich die Halteposition befindet
durchfahrt boolean true, falls bei der Halteposition nicht angehalten wird
einsteigeverbot boolean true, falls bei der Halteposition ein Einsteigeverbot besteht
aussteigeverbot boolean true, falls bei der Halteposition ein Aussteigeverbot besteht
zusatzhalt boolean true, falls es sich um eine zusätzliche Halteposition handelt

V1 - HaltestelleDto#

Datenklasse zur Haltestelle Antwort

Field Type Required Description
haltestellenname string Haltestellenname
vagKennung string VAG-Kennung der Haltestelle
vgnKennung integer VGN-Kennung der Haltestelle
longitude number Längengrad auf dem sich die Haltestelle befindet
latitude number Breitengrad auf dem sich die Haltestelle befindet
produkte string Eingesetzte Produkte / Fahrzeugtypen an der Haltestelle

V1 - HaltestellenApiResponse#

Antwortklasse für die Haltestellen-API Zugriffe

Field Type Required Description
metadata V1 - Metadata
haltestellen array of See V1 - HaltestelleDto Liste der Haltestellen

V1 - Metadata#

Metadaten für die Version 1 der Web-API

Field Type Required Description
version string Aktuelle Kennung der Version 1
timestamp string Zeitstempel der Anfrage auf dem Server