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 Methode	URL	Beschreibung
generateLink	https://www.hvv.de/linking-service/create	Generierung 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:

Attribut	Typ	Pflicht	Beschreibung
destination	String	Ja	Zieladresse, Ziel-POI oder Ziel-Haltestelle
start	String	Nein	Startadresse, Start-POI oder Start-Haltestelle
language	String	Ja	DE oder EN

Response

Erfolgsfall

Attribut	Typ	Beschreibung
url	String	URL, z. B. https://www.hvv.de/linking-service/show/e10374dc7c9e4fb6bb5a7aa41714b324
destination	String	Ziel
start	String	Start (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:

Code	Fehler	Beschreibung
1	START_NO_RESULT	Wert von start liefert kein Ergebnis bei Geofox.
2	START_SELECT	Wert von start resultierte in mehrere Ergebnisse, welche im Parameter startSuggestions auswählbar sind.
3	START_TOO_MANY_RESULTS	Die zugrundeliegende Geofox-API lieferte zu viele Ergebnisse für den Wert von start. Bitte den Wert konkretisieren.
11	DESTINATION_NO_RESULT	Wert von destination liefert kein Ergebnis bei Geofox.
12	DESTINATION_SELECT	Wert von destination resultierte in mehrere Ergebnisse, welche im Parameter destinationSuggestions auswählbar sind.
13	DESTINATION_TOO_MANY_RESULTS	Die zugrundeliegende Geofox-API lieferte zu viele Ergebnisse für den Wert von destination. Bitte den Wert konkretisieren.
30	SERVICE_NOT_AVAILABLE	Die zugrundeliegende Geofox-API ist nicht erreichbar.
100	TECHNICAL_ERROR	Die zugrundeliegende Geofox-API meldete einen nicht weiter spezifizierten Fehler.

Technische Fehler

Code	Fehler	Beschreibung
400	Bad Request	Aufruf der Schnittstelle entgegen der Spezifikation, z.B. ohne ein Pflichtfeld
404/503	Service Unavailable	Verlinkungsservice 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.