Zum Inhalt springen

Komm gut nach Hause

Für Hamburg und Umgebung

Für Hamburg und Umgebung

Webservice-Schnittstelle

Automatisiert Links zur Fahrplanauskunft erzeugen

Die Webservice-Schnittstelle richtet sich an technisch versierte  Betreiber von Webseiten, die automatisiert zahlreiche URLs generieren möchten.
Alternativ können Sie natürlich jederzeit Einzellinks generieren.

Es handelt sich um eine JSON-Schnittstelle, über die Text-Links generiert werden können. Es wird eine reine URL zurückgegeben.
Die Schnittstelle erwartet und liefert Daten im Zeichensatz UTF-8.

Auf Anfrage senden wir Ihnen gerne das HVV-Logo zu, wenn Sie den Link zur HVV-Fahrplanauskunft prominenter hervorheben möchten. Bitte schicken Sie uns dazu eine kurze E-Mail mit einer kurzen Beschreibung Ihres Vorhabens.

Webservice-Methode

Webservice MethodeURLBeschreibung
generateLinkhttps://www.hvv.de/linking-service/createGenerierung einer URL

Wenn zu einem angefragten Wert kein eindeutiges Ergebnis gefunden werden konnte, wird eine Liste von Vorschlägen zurückgegeben, die aus maximal 20 Einträgen besteht. Über diese Vorschläge kann die Suchanfrage spezifiziert werden.

Request

Die Webservice-Methode erwartet folgende Werte:

AttributTypPflichtBeschreibung
destinationStringJaZieladresse, Ziel-POI oder Ziel-Haltestelle
startStringNeinStartadresse, Start-POI oder Start-Haltestelle
languageStringJaDE oder EN

Response

Erfolgsfall

AttributTypBeschreibung
urlStringURL, z. B. https://www.hvv.de/linking-service/show/e10374dc7c9e4fb6bb5a7aa41714b324
destinationStringZiel
startStringStart (falls gesetzt)

Der Wert des Feldes „url“ ist die Antwort auf die Anfrage und kann auf der Webseite eingesetzt werden.

Als zusätzliche Information wird der Startpunkt (falls angefragt) und das Ziel der generierten Verlinkung zurückgegeben.

Fehlerfälle

Fehler die nicht zur Generierung eines Links führen, werden ausschließlich durch SOAP Faults behandelt.
Nachfolgend sind alle auftretenden Fehlerfälle aufgeführt:

CodeFehlerBeschreibung
1START_NO_RESULTWert von start liefert kein Ergebnis bei Geofox.
2START_SELECTWert von start resultierte in mehrere Ergebnisse, welche im Parameter startSuggestions auswählbar sind.
3START_TOO_MANY_RESULTSDie zugrundeliegende Geofox-API lieferte zu viele Ergebnisse für den Wert von start. Bitte den Wert konkretisieren.
11DESTINATION_NO_RESULTWert von destination liefert kein Ergebnis bei Geofox.
12DESTINATION_SELECTWert von destination resultierte in mehrere Ergebnisse, welche im Parameter destinationSuggestions auswählbar sind.
13DESTINATION_TOO_MANY_RESULTSDie zugrundeliegende Geofox-API lieferte zu viele Ergebnisse für den Wert von destination. Bitte den Wert konkretisieren.
30SERVICE_NOT_AVAILABLEDie zugrundeliegende Geofox-API ist nicht erreichbar.
100TECHNICAL_ERRORDie zugrundeliegende Geofox-API meldete einen nicht weiter spezifizierten Fehler.

Technische Fehler

CodeFehlerBeschreibung
400Bad RequestAufruf der Schnittstelle entgegen der Spezifikation, z.B. ohne ein Pflichtfeld
404/503Service UnavailableVerlinkungsservice ist nicht verfügbar

Beispiele von Anfragen

In der technischen Dokumentation kann mit Hilfe der "Try it out"-Funktion eine Beispiel-Anfrage gebaut und getestet werden, welche dann die Grundlage für Entwicklungen bilden kann.