die api des gdi-geokoders - · pdf file2 api des gdi-geokoders die kommunikation zwischen...
TRANSCRIPT
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
Technische Dokumentation GDI-Geokoder
Technische Hochschule Wildau [FH] Seite 3 von 13
Änderungen
Datum Beschreibung Verantwortlicher
07.02.2013 - Erstveröffentlichung A. Knöfel
18.06.2013 - EFRE-Logo eingefügt P. Bernhardt
Technische Dokumentation GDI-Geokoder
Technische Hochschule Wildau [FH] Seite 4 von 13
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
Technische Dokumentation GDI-Geokoder
Technische Hochschule Wildau [FH] Seite 5 von 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
Technische Dokumentation GDI-Geokoder
Technische Hochschule Wildau [FH] Seite 6 von 13
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.
Technische Dokumentation GDI-Geokoder
Technische Hochschule Wildau [FH] Seite 7 von 13
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
Technische Dokumentation GDI-Geokoder
Technische Hochschule Wildau [FH] Seite 8 von 13
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"> <!-- AdressenTyp--> <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" />
Technische Dokumentation GDI-Geokoder
Technische Hochschule Wildau [FH] Seite 9 von 13
</xsd:sequence> </xsd:complexType> </xsd:element> </xsd:schema>
Technische Dokumentation GDI-Geokoder
Technische Hochschule Wildau [FH] Seite 10 von 13
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“.
Technische Dokumentation GDI-Geokoder
Technische Hochschule Wildau [FH] Seite 11 von 13
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>
Technische Dokumentation GDI-Geokoder
Technische Hochschule Wildau [FH] Seite 12 von 13
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
Technische Dokumentation GDI-Geokoder
Technische Hochschule Wildau [FH] Seite 13 von 13
2.2 GetCapabilities
Über die Funktion „GetCapabilities“ kann die technische Beschreibung des GDI-Geokoders abgerufen
werden .