Die API des GDI-Geokoders - · PDF file2 API des GDI-Geokoders Die Kommunikation zwischen Client und Server wird mit Bedacht nach dem schlanken und leistungs- ... hn=6f&plz=15741&ort=Bestensee

Die API des GDI-Geokoders

Stand 18.06.2013

Revision 120

Technische Dokumentation GDI-Geokoder

Technische Hochschule Wildau [FH] Seite 2 von 13

Copyright:

© 2013 Technische Hochschule Wildau [FH]

Alle Marken- oder Produktnamen in dieser Dokumentation sind Warenzeichen oder eingetragene

Warenzeichen der jeweiligen Firmen oder Organisationen. Alle Rechte vorbehalten.

Rechtliche Vereinbarungen:

Die in diesem Dokument enthaltenen Informationen können ohne Vorankündigung geändert werden und

stellen keine Verpflichtung seitens des Verkäufers dar.

Ohne ausdrückliche schriftliche Erlaubnis der Autoren darf für andere Zwecke als den persönlichen Gebrauch

des Käufers dieses Handbuch in keinerlei Form mit irgendwelchen Mitteln, elektronisch oder mechanisch,

mittels Fotokopie, durch Aufzeichnung oder mit Informationsverarbeitungssystemen reproduziert oder

übertragen werden.

Impressum:

Technische Hochschule Wildau [FH]

Bahnhofstraße

15745 Wildau

Tel. +49 33 75 – 50 86 94

Stand Juni 2013 – Version 120



Änderungen

Datum Beschreibung Verantwortlicher

07.02.2013 - Erstveröffentlichung A. Knöfel

18.06.2013 - EFRE-Logo eingefügt P. Bernhardt



Inhalt

Änderungen ............................................................................................................................................. 3

Einleitung ................................................................................................................................................. 5

1 Systemaufbau .................................................................................................................................. 5

2 API des GDI-Geokoders ................................................................................................................... 7

2.1 GeokodiereAdresse ................................................................................................................. 7

2.1.1 Mögliche Fehlercodes ................................................................................................... 11

2.1.2 Die Abstufung der Qualität der Geokodierung ............................................................. 12

2.2 GetCapabilities ...................................................................................................................... 13



Einleitung

Aufgabe und konkretes Ziel des Projektes „GDI-Geokoder“ ist es, einen toleranten, zuverlässigen und

hochverfügbaren Dienst zur Verfügung zu stellen, mit dessen Hilfe zu einer Adresse hausnummernge-

nau die geographischen Koordinaten unter Verwendung des Gazetteer-Services der LGB ermittelt

werden können. Tolerant bedeutet in diesen Zusammenhang, dass typische Fehler in Adressbestän-

den, welche beim üblichen Umgang mit Adressen entstehen, durch die Software erkannt und auto-

matisiert aufgelöst werden. Dabei kann es sich z.B. um Schreibfehler, unvollständige oder auch veral-

tete Adressen handeln. Besonderes Merkmal dieses Dienstes im Vergleich mit den am Markt verfüg-

baren Angeboten ist dabei die Verwendung der hochgenauen, georeferenzierten Daten der Vermes-

sungsämter und der damit möglichen Hausnummer-genauen Lokalisierung der Eingabeadressen.

1 Systemaufbau

Der Client stellt eine Anfrage an den REST-Service des GDI-Geokoders, dieser wiederum fragt den

DOG-Gazetteer-Services der LGB an. Eine Anbindung von zusätzlichen externen Diensten zur Geoko-

dierung wäre zukünftig denkbar.

Abbildung 1: Grundkonzept des GDI-Geokoders



Im Folgenden wird der Aufbau einer Anfrage an den GDI-Geokoder verdeutlicht.

Abbildung 2: Aufbau einer Anfrage an den GDI-Geokoder

Die Kommunikation zwischen Client und Server wird mit Bedacht nach dem schlanken und leistungs-

fähigen REST-Paradigma realisiert, um den entstehenden Overhead so gering wie möglich halten zu

können und um sich in das Gesamtsystem der OGC-konformen Services einzupassen. Bei jeder An-

frage an den Geokodierungswebservice werden die Nutzerkennung, die zu geokodierende Adresse

und der Name des gewünschten Koordinatenreferenzsystems an den Server gesandt. Als Koordina-

tenreferenzsysteme können alle vom Gazetteer-Service der GDI-BE/BB unterstützten Systeme ver-

wendet werden (EPSG:4326, EPSG:25832, EPSG:25833 und EPSG:325833).

Die Antwort an den Client besteht im Wesentlichen aus der geokodierten Adresse, dessen geographi-

schen Koordinaten, die ursprünglich übergebenen Eingabeadresse und einer Angabe über die Quali-

tät der Geokodierung. Die Qualität dient in diesem Zusammenhang dazu, das Ergebnis der Geokodie-

rung zu bewerten und Aussagen über die Genauigkeit, d.h. wie genau konnte für die übergebene Ad-

resse in den Datenbeständen des Gazetteer-Services eine Entsprechung gefunden werden, treffen zu

können (siehe Kapitel 2.1.2 „Die Abstufung der Qualität der Geokodierung“).

Im Falle eines Fehlers wird der Client in maschinell auswertbarer als auch menschlich lesbarer Form

benachrichtigt (siehe Kapitel 2.1.1 „Mögliche Fehlercodes“). Die für jegliche Kommunikation verwen-

dete Sprache ist Deutsch.



2 API des GDI-Geokoders

Die Kommunikation zwischen Client und Server wird mit Bedacht nach dem schlanken und leistungs-

fähigen REST-Paradigma realisiert, um den entstehenden Overhead so gering wie möglich halten zu

können und um sich in das Gesamtsystem der OGC-konformen Services einzupassen. So ist der GDI-

Geokoder über den Aufruf einer URL erreichbar und antwortet mittels XML. Im Folgenden werden

die verschiedenen Funktionen und die Parameter für den GDI-Geokoder vorgestellt.

2.1 GeokodiereAdresse

Über die Funktion „GeokodiereAdresse“ wird eine Adresse hausnummerngenau geokodiert. Bei jeder

Anfrage an die Funktion, werden die Authentifizierungsinformationen des Nutzers, die zu geokodie-

rende Adresse und der Name des gewünschten Koordinatenreferenzsystems an den Server gesandt.

Die Parameter der Funktion „GeokodiereAdresse“ sind im Folgenden aufgelistet:

Tabelle 1: Parameter der Methode „GeokodiereAdresse“

Parameter Beschreibung Bemerkungen

key Pro Benutzer wird eine eindeu-tige Nutzerkennung vergeben und in der Abfrage zur Authentifi-zierung angegeben (siehe Kapitel Fehler! Verweisquelle konnte icht gefunden werden. „Fehler! Verweisquelle konnte nicht ge-funden werden.“)

Die Nutzerkennung muss zwingend angegeben werden, sonst kann keine Geokodierung erfolgen. Jeder Benutzer erhält eine eigene eindeutige Nut-zerkennung.

str Der Namen der Straße der zu ge-okodierenden Adresse.

Eine Straße muss zwingend eingegeben werden, sonst ist eine Geokodierung nicht möglich.

hn Hierbei handelt es sich um die Hausnummer der zu geokodie-renden Adresse (z.B. 5).

Sobald eine Hausnummernerweiterung angege-ben wurde, muss auch eine Hausnummer ange-geben werden. Ansonsten ist der Parameter opti-onal. Die Hausnummer kann auch inklusive Erweite-rung angegeben werden (z.B. 5c), dann bleibt der Parameter „Hausnummer-erweiterung“ leer, bzw. muss dieser nicht mit in der Anfrage angege-ben werden.

hne Hierbei handelt es sich um die Hausnummererweiterung der zu geokodierenden Adresse (z.B. c).

Optionaler Parameter

plz Die Postleitzahl der zu geokodie-renden Adresse.

Es muss mindestens die Postleitzahl oder der Ort angegeben werden, es dürfen nicht beide Para-meter leer sein. Es wird jedoch empfohlen beide Parameter anzugeben, um die Trefferquote zu er-höhen.

ort Der Ort der zu geokodierenden Adresse.

ot Hierbei handelt es sich um den Ortsteil der zu geokodierenden Adresse.

Optionaler Parameter



srs Der Name des zu verwendeten Raumbezugsystem (Spatial Refe-rence System – SRS) für die Geo-kodierung.

Optionaler Parameter, wird kein Wert angege-ben, wird der in der web.config definierte Stan-dard genommen (aktuell EPSG:25833 - siehe Ka-pitel Fehler! Verweisquelle konnte nicht gefun-den werden. „Fehler! Verweisquelle konnte nicht gefunden werden.“) Unterstützte Raumbezugssysteme: EPSG:4326, EPSG:25832, EPSG:25833, EPSG:32533

Der Aufruf der Funktion „GeokodiereAdresse“ sieht beispielsweise folgendermaßen aus:

Code 1: Beispielaufruf des GDI-Geokoders

http://localhost/GdiGeokoder/RestService/GeokodiereAdresse?key=zgnsjf&str=Mozart-straße&hn=6&hne=f&plz=15741&ort=Bestensee&ot=&srs=EPSG:4326

Ebenfalls möglich wäre ein Aufruf ohne der optionalen Parameter Hausnummernerweiterung, Orts-

teil und SRS:

Code 2: Beispielaufruf des GDI-Geokoders ohne Hausnummererweiterung und Ortsteil

http://localhost/GdiGeokoder/RestService/GeokodiereAdresse?key=zgnsjf&str=Mozartstraße& hn=6f&plz=15741&ort=Bestensee

Der Rückgabewert des GDI-Geokoders, wird nach folgendem Schema generiert:

Code 3: Schema für den Rückgabewert des GDI-Geokoders bei der Methode GeokodiereAdresse

<?xml version="1.0" encoding="utf-16"?> <xsd:schema attributeFormDefault="unqualified" elementFormDefault="qualified" version="1.0" xmlns:xsd="http://www.w3.org/2001/XMLSchema">  <xsd:complexType name=" AdressenTyp"> <xsd:sequence> <xsd:element name="Strasse" type="xsd:string" /> <xsd:element name="Hausnummer" type="xsd:int" /> <xsd:element name="Hausnummererweiterung" type="xsd:string" /> <xsd:element name="Postleitzahl" type="xsd:int" /> <xsd:element name="Ort" type="xsd:string" /> <xsd:element name="Ortsteil" type="xsd:string" /> <xsd:element name="Adressbezeichner" type="xsd:string" /> </xsd:sequence> </xsd:complexType> <xsd:element name="GDIGeokoder"> <xsd:complexType> <xsd:sequence> <xsd:element name="EingangsAdresse" type=" AdressenTyp" /> <xsd:element name="GeokodierteAdresse" type=" AdressenTyp" /> <xsd:element name="Qualitaet" type="xsd:int" /> <xsd:element name="Latitude" type="xsd:decimal" /> <xsd:element name="Longitude" type="xsd:decimal" /> <xsd:element name="SrsName" type="xsd:string" /> <xsd:element name="Benutzer" type="xsd:string" /> <xsd:element name="Nutzerkennung" type="xsd:int" /> <xsd:element name="FehlerCode" type="xsd:int" /> <xsd:element name="FehlerNachricht" type="xsd:string" />



</xsd:sequence> </xsd:complexType> </xsd:element> </xsd:schema>



Der Rückgabewert für den Beispielaufruf aus Code 1 lautet wie folgt. Code 4: Beispiel-Rückgabewert der Funktion „GeokodiereAdresse“ des Geokodier-Services

<?xml version="1.0" encoding="utf-8" ?> <GDIGeokoder xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema"> <EingangsAdresse> <Strasse>Mozartstraße</Strasse> <Hausnummer>6</Hausnummer> <Hausnummererweiterung>f</Hausnummererweiterung> <Postleitzahl>15741</Postleitzahl> <Ort>Bestensee</Ort> <Ortsteil /> <Adressbezeichner>Mozartstraße 6f, 15741 Bestensee</Adressbezeichner> </EingangsAdresse> <GeokodierteAdresse> <Strasse>Mozartstraße</Strasse> <Hausnummer>6</Hausnummer> <Hausnummererweiterung>e</Hausnummererweiterung> <Postleitzahl>15741</Postleitzahl> <Ort>Bestensee</Ort> <Ortsteil /> <Adressbezeichner>Mozartstraße 6e, 15741 Bestensee</Adressbezeichner> </GeokodierteAdresse> <Qualitaet>99</Qualitaet> <Latitude>52,241604999028461</Latitude> <Longitude>13,653827999688184</Longitude> <SrsName>EPSG:4326</SrsName> <Benutzer>Anton Schwarz</Benutzer> <Nutzerkennung>zgnsjf </Nutzerkennung > <FehlerCode>0</FehlerCode> <FehlerNachricht /> </GDIGeokoder>

Der Rückgabewert der Funktion „GeokodiereAdresse“ enthält die übergebene Adresse (Ein-

gangsadresse) und die geokodierte Adresse, insofern die Adresse geokodiert werden konnte. Weiter-

hin wird die Qualität der Geokodierung angegeben, die in Kapitel 2.1.2 „Die Abstufung der Qualität“

näher definiert wird. Die Koordinaten der Latitude und Longitude werden je nach dem der Methode

übergebenem Raumbezugssystem (SRS) zurückgegeben. Das heißt die Mozartstraße 6e in 15741 Bes-

tensee hat im Raumbezugsystem „EPSG: 4326“ die Koordinaten 13,654 und 52,241 und im Raumbe-

zugsystem „EPSG:25833“ die Koordinaten 5788764,503 und 408085,014 (auf 3 Stellen nach dem

Komma gerundet).

Der Benutzer wird anhand der Nutzerkennung (Parameter „key“) ermittelt. Im Rückgabewert ist der

Klarname des Benutzers enthalten. Wird eine ungültige Nutzerkennung angegeben, bzw. gar keine

Nutzerkennung angegeben, wird ein entsprechender Fehlercode zurückgegeben.

Tritt ein sonstiger Fehler beim Geokodieren auf, werden ein Fehlercode und eine Fehlernachricht zu-

rückgegeben. Näheres zu den Fehlercodes finden Sie in Kapitel siehe Kapitel 2.1.1 „Mögliche Fehler-

codes“.



2.1.1 Mögliche Fehlercodes

Tritt ein Fehler bei der Geokodierung auf, da beispielsweise die Parameter nicht korrekt übergeben

wurden, werden in den Rückgabedaten ein Fehlercode und eine Fehlernachricht übermittelt. Tritt

kein Fehler auf, ist der Fehlercode „0“ und die Nachricht ist leer. Die im Folgenden aufgelisteten Feh-

ler können auftreten. Dabei wird der Platzhalter [SRS] für den Wert des Parameter 'srs' verwendet.

Tabelle 2: mögliche Fehlercodes

Fehlercode Fehlernachricht

200 Der Parameter 'Nutzerkennung' (key) muss angegeben werden.

201 Die angegebene Nutzerkennung (key) ist ungültig.

202 Der Parameter 'Straße' (str) muss angegeben werden.

203 Es muss mindestens eine Postleitzahl ('plz') oder ein Ort ('ort') angegeben werden.

204 Der Parameter 'Hausnummer' (hn) muss angegeben werden, wenn eine 'Hausnum-mernerweiterung' (hne) angegeben wurde.

205 Der Parameter 'Ort' (ort) muss angegeben werden, wenn ein 'Ortsteil' (ot) angegeben wurde.

206 Das Raumbezugssystem '[SRS]' wird nicht unterstützt.

207 Das Raumbezugssystem '[SRS]' wird zurzeit noch nicht unterstützt. (Betrifft die Raumbezugssysteme EPSG:4258 und EPSG:4839)

300 Es ist ein unbekannter Fehler beim GDI-Geokoder aufgetreten.

Der Rückgabedaten sehen in einem Fehlerfall beispielsweise wie folgt aus:

Code 5: Rückgabewert im Fehlerfall

<?xml version="1.0" encoding="utf-8" ?> <GDIGeokoder xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema"> <EingangsAdresse> <Strasse>Mozartstraße</Strasse> <Hausnummer /> <Hausnummererweiterung>c</Hausnummererweiterung> <Postleitzahl>15741</Postleitzahl> <Ort>Bestensee</Ort> <Ortsteil /> <Adressbezeichner>Mozartstraße c, 15741 Bestensee</Adressbezeichner> </EingangsAdresse> <GeokodierteAdresse> <Adressbezeichner /> </GeokodierteAdresse> <Qualitaet>0</Qualitaet> <Latitude>0</Latitude> <Longitude>0</Longitude> <SrsName /> <Benutzer /> <Nutzerkennung /> <FehlerCode>204</FehlerCode> <FehlerNachricht> Der Parameter 'Hausnummer' (hn) muss angegeben werden, wenn eine 'Hausnummernerweiterung' (hne) angegeben wurde.</FehlerNachricht> </GDIGeokoder>



2.1.2 Die Abstufung der Qualität der Geokodierung

Die Qualität der Geokodierung ist ein Ganzzahlwert von 100 bis 0. Dieser Wert ermöglicht die Bewer-

tung der Genauigkeit einer Ergebnisadresse und gibt Auskunft über mögliche Fehler in der Eingabe-

adresse. Fehlerlose Suchkriterien für die Geokodierung einer Adresse führen zur maximalen Qualität

von „100“. Sind einzelne Suchkriterien fehlerhaft, gehen Strafkosten wie folgt in die Qualität ein:

Tabelle 3: Strafkosten für die Geokodierung

fehlerhafte Suchkriterien Strafkosten

Hausnummererweiterung -1

Hausnummer -2

Ortsteil -4

Ort oder Postleitzahl -8

Ist eine Adresse nicht geokodierbar, erhält sie die Qualität „0“. Als nicht geokodierbar gilt eine Ad-

resse, wenn der Straßenname in Kombination mit dem Ort oder der Postleitzahl nicht gefunden wird.

Tabelle 4: Abstufung der Geokodierungsqualität

Qualität Bedeutung

100 Korrekt: Straßenname, Hausnummer, Hausnummererweiterung, Postleitzahl, Ort, Ortsteil

99 Fehlerhaft: Hausnummererweiterung

Korrekt: Straßenname, Hausnummer, Postleitzahl, Ort, Ortsteil

98 Fehlerhaft: Hausnummer

Korrekt: Straßenname, Hausnummererweiterung, Postleitzahl, Ort, Ortsteil

97 Fehlerhaft: Hausnummer, Hausnummererweiterung

Korrekt: Straßenname, Postleitzahl, Ort, Ortsteil

96 Fehlerhaft: Ortsteil

Korrekt: Straßenname, Hausnummer, Hausnummererweiterung, Postleitzahl, Ort

95 Fehlerhaft: Ortsteil, Hausnummererweiterung

Korrekt: Straßenname, Hausnummer, Postleitzahl, Ort

94 Fehlerhaft: Ortsteil, Hausnummer

Korrekt: Straßenname, Hausnummererweiterung, Postleitzahl, Ort

93 Fehlerhaft: Ortsteil, Hausnummer, Hausnummererweiterung

Korrekt: Straßenname, Postleitzahl, Ort

92 Fehlerhaft: Postleitzahl oder Ort

Korrekt: Straßenname, Hausnummer, Hausnummererweiterung, Postleitzahl oder Ort, Ortsteil

91 Fehlerhaft: Postleitzahl oder Ort, Hausnummererweiterung

Korrekt: Straßenname, Hausnummer, Postleitzahl oder Ort, Ortsteil

90 Fehlerhaft: Ort oder Postleitzahl, Hausnummer

Korrekt: Straßenname, Hausnummererweiterung, Postleitzahl oder Ort, Ortsteil

89 Fehlerhaft: Ort oder Postleitzahl, Hausnummer, Hausnummererweiterung

Korrekt: Straßenname, Postleitzahl oder Ort, Ortsteil

88 Fehlerhaft: Ort oder Postleitzahl, Ortsteil

Korrekt: Straßenname, Postleitzahl oder Ort, Hausnummer, Hausnummererweiterung

87 Fehlerhaft: Ort oder Postleitzahl, Ortsteil, Hausnummererweiterung

Korrekt: Straßenname, Postleitzahl oder Ort, Hausnummer

86 Fehlerhaft: Ort oder Postleitzahl, Ortsteil, Hausnummer

Korrekt: Straßenname, Postleitzahl oder Ort, Hausnummererweiterung

85 Fehlerhaft: Ort oder Postleitzahl, Ortsteil, Hausnummer, Hausnummererweiterung

Korrekt: Straßenname, Postleitzahl oder Ort

0 Nicht geokodierbar



2.2 GetCapabilities

Über die Funktion „GetCapabilities“ kann die technische Beschreibung des GDI-Geokoders abgerufen

werden .

Documents

Die API des GDI-Geokoders - · PDF file2 API des GDI-Geokoders Die Kommunikation zwischen Client und Server wird mit Bedacht nach dem schlanken und leistungs- ... hn=6f&plz=15741&ort=Bestensee