Spezialschnittstellen:
Technische Spezifikation

ZEUS Web Services für Salzburg

Allgemeines

ZEUS ist eine Online-Datenbank, die zur Verwaltung von Energieausweisen dient.

Für Clientsoftware, die Energieausweise berechnet, bietet ZEUS ein SOAP Web Service an, um Adressdaten zu überprüfen und zugehörige Luftbilder anzuzeigen. Wenn für eine Adresse bereits ein GIS-Code vorhanden ist, dann kann das Luftbild auch ohne Aufruf der SOAP-Schnittstelle angezeigt werden.

Sicherheit

Für die Clientsoftware wird ein Zugriff mittels TLS/SSL (HTTPS) empfohlen. Jeder Zugriff erfordert eine HTTP Authentifizierung nach der „Digest Access Authentication“ Methode. Benutzername und Passwort für den Zugriff auf das Web Service werden nach Unterfertigung der Nutzungsvereinbarung zur Verfügung gestellt.

Die Benutzung des Web Services ist pro Methode und IP-Adresse auf 50 Abfragen pro Tag limitiert. Diese Maßnahme soll vor Missbrauch schützen.

Server

Die ZEUS Web Services sind unter folgenden URLs verfügbar:

• Testumgebung: https://spielwiese-service.energieausweise.net/version/1.0/wsdl/
• Produktion: https://service.energieausweise.net/version/1.0/wsdl/

Implementierte Methoden

Die ZEUS Web Services implementieren folgende SOAP Methoden:

checkAddress

Liefert Adressvorschläge zu den übergebenen Adressdaten zurück.

getAddress

Liefert einen Adressdatensatz zum übergebenen GIS-Code zurück.

getAerialPhoto

Liefert eine URL zum Luftbild anhand eines GIS- oder eines GWR -Codes zurück. Die gelieferte URL zeigt auf den ZEUS Web Services Server. Das Luftbild kann mithilfe des GIS-Codes auch direkt über einen einfachen HTTP-Request abgerufen werden.

Das Luftbild kann mithilfe des GIS-Codes auch direkt über einen einfachen HTTP-Request abgerufen werden.

Adresse überprüfen und alternative Vorschläge abrufen

Die Methode checkAddress liefert Adressvorschläge zu den übergebenen Adressdaten zurück.

Parameter

Folgende Parameter werden erwartet:

* Die Parameter plz, gemeinde und ort sind optional, jedoch muss mindestens einer davon übergeben werden. Eine Kombination von zwei oder drei Parametern liefert in den meisten Fällen ein besseres Ergebnis.

Resultat

Als Resultat wird eine Liste von Objekten (max. 25) mit folgenden Eigenschaften zurückgegeben:

Adressdetails anfordern

Die Methode getAddress liefert Details zu einer mithilfe des GIS -Codes eindeutig spezifizierten Adresse zurück.

Parameter

Folgende Parameter werden erwartet:

Resultat

Als Resultat wird ein Objekt mit den gleichen Eigenschaften wie bei der Methode checkAddress zurückgegeben.

Luftbild

URL vom Luftbild anfordern

Die Methode getAerialPhoto liefert die URL zu einem Luftbild anhand des GIS-Codes zurück. Dieser Aufruf ist optional; das Luftbild kann auch direkt als Grafik eingebunden werden.

Folgende Parameter werden erwartet:

Als Resultat wird ein Objekt mit folgenden Eigenschaften zurückgegeben:

Luftbild direkt anzeigen

Das Luftbild kann mithilfe des GIS-Codes direkt über einen einfachen HTTP-Request abgerufen werden. Im Bundesland Salzburg wird eine 500 × 600 Pixel große JPEG-Grafik zurückgeliefert. Für das Abrufen des Luftbildes ist keine Authentifizierung erforderlich.

Die URLs dafür sind:

• Testumgebung: https://spielwiese-service.energieausweise.net/version/1.0/aerialphoto/show/country/[country]/id/[id]/
• Produktion: https://service.energieausweise.net/version/1.0/aerialphoto/show/country/[country]/id/[id]/

Um ein Luftbild anzuzeigen, müssen in der URL folgende Platzhalter mit gültigen Daten ersetzt werden:

Beispiele:

• Testumgebung: https://spielwiese-service.energieausweise.net/version/1.0/aerialphoto/show/country/AT/id/5020_31549_184/
• Produktion: https://service.energieausweise.net/version/1.0/aerialphoto/show/country/AT/id/5020_31549_184/

Allgemeine Rückgabewerte

Bei jedem Aufruf wird zusätzlich zum erwarteten Resultat ein Rückgabewert übergeben. Folgende Rückgabewerte sind möglich:

Success – Erfolgreiche Abfrage

Eine erfolgreiche Abfrage mit gefundenen Resultaten liefert den returnValue mit returnCode success zurück. XML-Beispiel:

<returnValue>
	<returnCode>success</returnCode>
	<returnMessage>Success</returnMessage>
</returnValue>

NotFound - Keine Resultate gefunden

Eine erfolgreiche Abfrage, die keine Resultate findet, liefert den returnValue mit returnCode notFound zurück. XML-Beispiel:

<returnValue>
	<returnCode>notFound</returnCode>
	<returnMessage>NotFound</returnMessage>
</returnValue>

ParameterMissing – Fehlende Parameter

Sollten verpflichtende Parameter bei der Übergabe fehlen oder leer sein, wird ein returnValue mit returnCode parameterMissing zurückgeliefert. XML-Beispiel:

<returnValue>
	<returnCode>parameterMissing</returnCode>
	<returnMessage>Missing Parameter: strasse</returnMessage>
</returnValue>

ParameterInvalid – Ungültige Parameter

Sollte ein übergebener Parameter nicht dem erwarteten Format entsprechen, wird ein returnValue mit returnCode parameterInvalid zurückgeliefert (z.B. plz mit dem Wert 100 entspricht einer ungültigen Postleitzahl). XML-Beispiel:

<returnValue>
	<returnCode>parameterInvalid</returnCode>
	<returnMessage>Invalid Parameter: plz</returnMessage>
</returnValue>

LimitExceeded – Abfrage-Limit überschritten

Die Abfragen sind für jeden Benutzer pro Tag limitiert. Wird dieses Limit überschritten, wird ein returnValud mit returnCode limitExceeded zurückgeliefert. XML-Beispiel:

<returnValue>
	<returnCode>limitExceeded</returnCode>
	<returnMessage>LimitExceeded</returnMessage>
</returnValue>

Error – Service Fehler

Sollte ein Fehler im System auftreten, wird ein returnValue mit returnCode error zurückgeliefert. XML-Beispiel:

<returnValue>
	<returnCode>error</returnCode>
	<returnMessage>Error</returnMessage>
</returnValue>

Kontakt für die Nutzungsvereinbarung

SAGIS – Datenabgabe – div. Anfragen Kontaktadresse
Amt der Salzburger Landesregierung
Referat 7/06 - Geodateninfrastruktur
Michael-Pacher-Straße 36
5020 Salzburg
Telefon: +43 662 8042-4388
E-Mail: sagis@salzburg.gv.at
Web: www.salzburg.gv.at/sagis

Changelog