Dokumentation GeocodingMap – Version 1.1

Die GeocodingMap ist eine in eigene Webprojekte einfach einzubindende Kartenkomponente mit der Möglichkeit, Adressen zu verorten. Ebenfalls können Koordinaten übergeben werden - diese werden direkt in die Karte gezeichnet. Über weitere Parameter kann auf die Ausgestaltung der Karte Einfluss genommen bzw. zusätzliche Module geladen werden.

Einen Überblick über derzeit alle hinzuladbaren Module gibt folgende Abbildung:

Die GeocodingMap kann aber auch zur Erfassung und Pflege von Adressdatenbeständen verwendet werden. Dazu kann das nachfolgende Suchfeld eingebunden werden.

Verwenden Sie die nachfolgenden Links
Die GeocodingMap einbinden
Die GeocodingMap zum Erstellen von Karten verwenden
Die GeocodingMap für die Adresserfassung und Nachverortung verwenden

 

Nutzungsbedingungen

Die GeocodingMap ist ein Angebot des Landes NRW, in dem auch Geobasisdaten genutzt werden, die nicht den Open Data Prinzipien unterliegen. Eine Nutzung der GeocodingMap ist nur in Angeboten von Landesbehörden, Landesbetrieben, Einrichtungen und Gerichten des Landes, Gutachterausschüssen für Grundstückswerte des Landes sowie von Kreisen, kreisfreien Städten und kreisangehörigen Gemeinden des Landes und Anstalten des öffentlichen Rechts im Sinne des § 114a der Gemeindeordnung für das Land Nordrhein-Westfalen zur Erfüllung ihrer Aufgaben zulässig.

 

Die GeocodingMap einbinden

Die Einbindung der Komponente erfolgt durch das Setzen des folg. JavaScript Verweises:

<script type="text/javascript" src="http://www.gis-rest.nrw.de/geocoding_map/v110/init.js"></script>

 

Die GeocodingMap zum Erstellen von Karten verwenden

Im Body der HTML-Seite ist ein Bereich zu definieren, in den die Karte hineingeneriert werden soll. Dies geschieht über ein DIV je Karte. Das Klassen-Attribut trägt den Namen itnrwMap.

<div id="itnrwMap_0" class="itnrwMap"> </div>
<div id="itnrwMap_1" class="itnrwMap"> </div>
<div id="itnrwMap_2" class="itnrwMap"> </div>

Wie das Beispiel zeigt, können auch mehrere Karten in einem Dokument definiert werden (MultiMaps). Standardmäßig werden Karten mit den Maßen 350 x 250 Pixel und dem Kartenwerk „webatlas“ erzeugt (Kartenwerke siehe unten, Attribut data-itnrw-map). Soll das Aussehen der Karte manipuliert bzw. weitere Module geladen werden, sind diese über Parameter zu definieren und zu konfigurieren.

 

Konfigurationsparameter

IEine Karte kann erweitert werden, indem das DIV um weitere Attribute ergänzt wird.Beispiel: Eine Karte mit angepasster Größe, einem anderen initialen Kartenwerk und der Möglichkeit, zwischen zwei Kartenwerken hin und her zu schalten sieht wie folgt aus:

<div id="itnrwMap_0" class="itnrwMap"
data-itnrw-map="width:600px, height:300px, basemap:webatlas_grau";
data-itnrw-module-toggler="webatlas_grau, dop20"></div>

Folgend eine Übersicht über alle Konfigurationsparameter:

data-itnrw-addresses
Dieses Attribut wird verwendet, um den Geocoder anzuweisen, die entsprechende Adresse bzw. die entsprechenden Adressen zu verorten. Hierbei wird ein separater Dienst zum Geokodieren der Adressen angesprochen. Für diesen benötigen Sie einen Token, den Sie durch uns ausgestellt bekommen. Wenden Sie sich hierzu bitte an limgeo@it.nrw.de

Das Attribut kann entweder initial oder zur Laufzeit gesetzt/geändert werden. Die Karten werden in einem Array vorgehalten. Der Entwickler kann über die set-Methode das Setzen einer neuen Adresse vornehmen indem er z.B. für die erste Karte im DOM folgenden Aufruf absetzt:

itnrwMaps[0].set("data-itnrw-addresses", "[neue Str Hsnr, PLZ Ort;]");
data-itnrw-addresses="[Straße Hausnummer, PLZ Ort; TooltipText; InfoFensterInhalt; Punktbeschriftung; alternativesSymbol]"

Ein Adress-Block steht in eckigen Klammern. Dieser Block enthält die Adresse (Straße und Hausnummer getrennt durch Komma von PLZ und Ort) und Kurztexte für den Tooltip, den HTML-Inhalt für das Info-Fenster sowie die Punktbeschriftung (Textfelder = optional). Im HTML-Inhalt sind ggf. doppelte Anführungszeichen zu ersetzen (z.B. &quot;).

Zusätzlich kann ein eigenes Symbol definiert werden (optional), welches durch eine URL angegeben wird. In diesem Fall wird das Symbol mittig auf der Koordinate platziert:

Konvention: http://imageURL/name_breite_höhe_ankerpunkt.png (oder .jpg)
Beispiel: http://imageURL/icon_20_20.png

Falls ein Symbol abweichend von der Bildmitte platziert werden soll, kann sich an nachfolgender Abbildung orientiert werden. 9 Schwerpunkte stehen zur Verfügung. Zum Ausrichten der eigenen Grafik an z.B. der unteren Mitte muss der Grafikschwerpunkt 8 verwendet werden:

Konvention: http://imageURL/name_breite_höhe.png (oder .jpg)
Beispiel: http://imageURL/icon_20_20_8.png

Grafik Bild positionieren

Falls die Größe nicht aus dem Dateinamen ermittelt werden kann, wird das Bild in einer Ausdehnung von 12x12px dargestellt.

Adresse, Tooltip, Inhalt Info-Fenster, Punktbeschriftung und SymbolURL werden durch ein Semikolon getrennt. Für mehrere Adressen werden mehrere Adress-Blöcke getrennt durch ein Komma definiert. Beispiel:

data-itnrw-addresses="[Mauerstraße 51, 40476 Düsseldorf; IT.NRW; <b>IT.NRW</b>], [Kennedydamm 15, 40476 Düsseldorf; IT.NRW Nebenstelle; <b>IT.NRW</b><br>Nebenstelle]"

 

data-itnrw-flurstuecke
Dieses Attribut wird verwendet, um den Geocoder anzuweisen, ein Flurstück/Flurstücke zu verorten. Es kann entweder initial oder zur Laufzeit gesetzt/geändert werden. Die Karten werden in einem Array vorgehalten. Der Entwickler kann über die set-Methode das Setzen eines neuen Flurstücks vornehmen indem er z.B. für die erste Karte im DOM folgenden Aufruf absetzt:

itnrwMaps[0].set("data-itnrw-flurstuecke", "[Gemeinde,Gemarkungsname, Flur,Flurstücksnummer;]");
data-itnrw-flurstuecke="[Gemeinde,Gemarkungsname, Flur,Flurstücksnummer; TooltipText; InfoFensterInhalt; Punktbeschriftung; alternativesSymbol]"

Das Flurstück kann über verschiedene Schreibweisen übergeben werden:

  • Gemeinde,Gemarkungsname,Flur,Flurstücksnummer
  • Gemarkungsnummer-Flur-Flurstücksnummer
  • Flurstückskennzeichen (18stellig):

 

Grafik Objektname Flurstück

Ein Flurstück-Block steht in eckigen Klammern. Dieser Block enthält das Flurstück und die optionalen drei Beschreibungsfelder sowie die Möglichkeit, eigene Symbole zu definieren (siehe data-itnrw-addresses). Für mehrere Flurstücke werden mehrere Flurstück -Blöcke getrennt durch ein Komma definiert. Beispiel:

data-itnrw-flurstuecke="[3461-6-462; IT.NRW; <b>IT.NRW</b>], [3461-1-625; IT.NRW Nebenstelle; <b>IT.NRW</b><br>Nebenstelle]"

Hinweis: Es können immer nur Adressen (Priorität 1) oder Flurstücke (Priorität 2)  oder Koordinaten (Priorität 3) verarbeitet werden.

 

data-itnrw-coords
Dieses Attribut wird verwendet, um Koordinaten zur direkten Anzeige an die GeocodingMap zu übergeben. Es kann entweder initial oder zur Laufzeit gesetzt/geändert werden. Die Karten werden in einem Array vorgehalten. Der Entwickler kann über die set-Methode das Setzen einer neuen Adresse vornehmen indem er z.B. für die erste Karte im DOM folgenden Aufruf absetzt:

itnrwMaps[0].set("data-itnrw-coords", "[epsg:25832; 344565.4, 5679410]");
data-itnrw-coords="[epsg:25832; Koordinate; TooltipText; InfoFensterInhalt; Punktbeschriftung; alternativesSymbol]"

Ein Koordinaten-Block steht in eckigen Klammern. Dieser Block enthält den EPSG-Code, das Koordinatenpaar (Koordinaten getrennt durch Komma) und die optionalen drei Beschreibungsfelder sowie die Möglichkeit, eigene Symbole zu definieren (siehe data-itnrw-addresses). Derzeit werden nur UTM-Koordinaten verarbeitet. EPSG-Code, Koordinate, Tooltip, Inhalt Info-Fenster, Punktbeschriftung und SymbolURL werden durch ein Semikolon getrennt. Für mehrere Koordinaten werden mehrere Koordinaten-Blöcke getrennt durch ein Komma definiert. Beispiel:

data-itnrw-coords="[epsg:25832; 344565.4, 5679410; TooltipText; InfoFensterInhalt], [epsg:25832; 344565.4, 5679410]"

Hinweis: Es können immer nur Adressen (Priorität 1) oder Flurstücke (Priorität 2)  oder Koordinaten (Priorität 3) verarbeitet werden.

 

data-itnrw-map
Definiert werden können Kartenbreite und –höhe, das Basiskartenwerk sowie das Zoomlevel. Alle Parameter sind optional. Die Kartenbreite ist in px oder % anzugeben (default: 350 x 250 Pixel). Mögliche Optionen für die Basiskarte sind webatlas, webatlas_grau, dtk_sw bzw. dop20 (default: webatlas). Das Zoomlevel definiert die Kachelungsstufe der Basiskarte und damit, wie weit bei einer adressgenauen Verortung gezoomt wird (default: 14, möglich: 0-15).

Mögliche Auswahl an Basiskarten v.l.n.r.: webatlas, webatlas_grau, dtk_sw, dop20

Beispiel:

data-itnrw-map="width:800px, height:400px, basemap:webatlas_grau, zoomlevel:12"

Beispiel für die Verwendung keiner Basiskarte:

data-itnrw-map="basemap:none"

 

data-itnrw-layers
Dieses Attribut wird verwendet, um die Basiskarten zusätzlich mit Fachthemen zu überlagern. Derzeit können Dienste als ESRI ArcGIS Server Mapping Services und als OGC Web Map Services (WMS) definiert und der GeocodingMap hinzugefügt werden.

Für den ArcGIS Server Dienst::

data-itnrw-layers="[Dienstetyp; ServiceURL; Auflistung der Layer (optional); Transparenz des Dienstes (optional)]"

Die Beschreibung eines Dienstes steht in eckigen Klammern. Dieser Block enthält das Kürzel des einzubindenden Dienstes (hier: ags), die Adresse (URL) zum Dienst selbst, ggfs. die Auflistung der anzuzeigenden Layer (kommagetrennt) – ansonsten wird der gesamte Dienst verwendet – sowie ggfs. die Angabe der Transparenz zwischen 0 und 1 (0 = transparent, 1 = keine Transparenz, default: 1). Beispiel:

data-itnrw-layers="[ags; http://rechner/arcgis/service/MapServer; 0,1,2; 0.4]"

Für den WMS-Dienst:

data-itnrw-layers="[Dienstetyp; ServiceURL; Auflistung der Layer; Version (optional); Transparenz des Dienstes (optional)]"

Die Beschreibung eines Dienstes steht in eckigen Klammern. Dieser Block enthält das Kürzel des einzubindenden Dienstes (hier: wms), die Adresse (URL) zum Dienst selbst, die Auflistung der anzuzeigenden Layer (kommagetrennt), ggfs. die Version des WMS (default: 1.3.0) sowie ggfs. die Angabe der Transparenz zwischen 0 und 1 (0 = transparent, 1 = keine Transparenz, default: 1). Beispiel:

data-itnrw-layers="[wms; http://rechner/service; layer0,layer1,layer2; 1.1.1]"

Für mehrere Dienste werden mehrere Service-Blöcke getrennt durch ein Komma definiert. Anmerkung: Die Dienste werden der Karte nacheinander hinzugefügt. Daraus ergibt sich hinsichtlich der Sichtbarkeit, dass der letzte Layer immer der oberste ist.

data-itnrw-layers="[ags; http://rechner/arcgis/service/MapServer; 0,1,2; 0.4], [wms; http://rechner/service; layer0,layer1,layer2; 1.1.1]"

 

data-itnrw-extent
Dieses Attribut wird verwendet, um den Ausschnitt (Extent) der Karte festzulegen. Er kann entweder initial oder zur Laufzeit gesetzt/geändert werden. Die Karten werden in einem Array vorgehalten. Der Entwickler kann über die set-Methode das Setzen einer neuen Adresse vornehmen indem er z.B. für die erste Karte im DOM folgenden Aufruf absetzt:

itnrwMaps[0].set("data-itnrw-extent", "316151.0, 5668812.8, 378829.3, 5691743.9");
data-itnrw-extent="x_lu, y_lu, x_ro, y_ro"

Der Extent wird durch zwei Punkte beschrieben: durch den x- und y-Wert der linken unteren (lu) sowie den x- und y- Wert der rechten oberen (ro) Ecke. Diese 4 Werte werden dem Attribut getrennt durch Kommata übergeben. Beispiel:

data-itnrw-extent="316151.0, 5668812.8, 378829.3, 5691743.9"

Anmerkung: Werden der Karte zusätzlich Adressen (data-itnrw-addresses) bzw. Koordinaten (data-itnrw-coords) übergeben, besitzt der initiale Extent Vorrang. Wird dieser nicht mehr benötigt oder soll zur Laufzeit gelöscht werden, dann die set-Methode verwenden und einen leeren String setzen.

 

data-itnrw-module-search (Suchleiste)
Dieses Attribut wird verwendet, um die Suchleiste in der Karte zu aktivieren. Diese kann z.B. so konfiguriert werden, dass interaktiv nach Adressen gesucht werden kann. Die Suchleiste wird nur geladen, wenn die Karte ausreichend breit definiert wurde.

data-itnrw-module-search="Suchdienst1, Suchdienst2, .."

In die Suchleiste können verschiedene Suchdienste eingebunden werden. Derzeit ist das Suchen nach Adressen, Flurstücken und Verwaltungsgebieten vorgesehen. Werte: „alle“ für alle Suchdienste bzw. „adressen“, „flurstuecke“ oder „verwaltungsgebiete“ konfigurieren. Beispiel:

data-itnrw-module-search="adressen, verwaltungsgebiete"

Die Suche erzeugt - falls eine Callback-Funktion angemeldet wurde - Rückgaben im GeoJSON-Format (siehe Attribut data-itnrw-callbacks).

 

data-itnrw-module-coords (Koordinatenleiste)
Dieses Attribut wird verwendet, um die Koordinatenleiste in der Karte zu aktivieren. Konfiguriert werden können darin diverse Koordinatensysteme, um entsprechend vorliegende Quellkoordinaten eingeben zu können, die in der Karte angezeigt werden. Die Koordinatenleiste wird nur geladen, wenn die Karte ausreichend breit definiert wurde.

data-itnrw-module-coords="epsg-Code1, epsg-Code2, .."

In die Koordinatenleiste können verschiedene Koordinatensysteme aufgenommen werden. Derzeit ist die Eingabe von UTM Zone 32N, Gauß-Krüger Zone 2 + 3 und Geographischen Koordinaten möglich. Werte: „alle“ für alle Koordinatensysteme bzw. „epsg:25832“ für UTM, „epsg:31466“ für Gauß-Krüger Zone 2, „epsg:31467“ für Gauß-Krüger Zone 3 oder „epsg:4326“ für Geographische Koordinaten konfigurieren. Beispiel:

data-itnrw-module-coords="epsg:31466, epsg:31467"

Die Transformation erzeugt - falls eine Callback-Funktion angemeldet wurde - Rückgaben im GeoJSON-Format (siehe Attribut data-itnrw-callbacks).

 

data-itnrw-module-toggler (Basiskarten Umschalter)
Der BasemapToggler ermöglicht das Umschalten zwischen den Basiskarten. Für das Umschalten sind mindestens zwei Basiskartenwerke zu definieren.

data-itnrw-module-toggler="Basiskarte1, Basiskarte2, .."

Werte: „alle“ zum Schalten durch alle Basiskarten bzw. „webatlas“, „webatlas_grau“, „dtk_sw“ und/oder „dop20“. Beispiel:

data-itnrw-module-toggler="webatlas_grau, dop20"

Hinweis zur Konfiguration “alle”:

Neben den 4 Basiskarten wird hier auch die Option “ohne Karte“ (keine Basiskarte) aufgenommen.

 

data-itnrw-module-tools (Werkzeugleiste)
Dieses Attribut wird verwendet, um die Werkzeugleiste bzw. einzelne Werkzeuge zu laden.

data-itnrw-module-tools="Werkzeug1, Werkzeug2"

Nächste Adresse (Reverse Geocoding): Werkzeug ermittelt die nächstgelegene Adresse im Umkreis des Klicks in der Karte.

Setze Koordinate: Werkzeug markiert die Position des Klicks in der Karte.

Definition eines Kartenausschnittes als Rechteck: Durch das Aufziehen eines Rechteckes mit der Maus wird ein bestimmtes Gebiet markiert. Damit das Werkzeug im Internet Explorer ab Version 10 funktioniert, wird folgende meta-Angabe im head des HTML-Dokumentes benötigt: <meta http-equiv="X-UA-Compatible" content="IE=9">

Definition eines Kartenausschnittes als Kreis: Durch das Aufziehen eines Kreises mit der Maus wird ein bestimmtes Gebiet markiert. Damit das Werkzeug im Internet Explorer ab Version 10 funktioniert, wird folgende meta-Angabe im head des HTML-Dokumentes benötigt: <meta http-equiv="X-UA-Compatible" content="IE=9">

Definieren eines Polygons: Durch das Setzen beliebiger Stützpunkte wird ein Gebiet markiert. Ein Doppelklick schließt das Zeichnen ab.

Definieren eines Freihand-Polygons: Mit gedrückter linker Maustaste kann ein beliebiges Gebiet markiert werden. Das Loslassen der linken Maustaste schließt das Zeichnen ab.

Werte: „alle“ für alle Werkzeuge bzw. „naechsteAdresse“, „setzeKoordinate“, „ausschnittRechteck“, „ausschnittKreis“, „zeichnePolygon“ oder „zeichneFreihandPolygon“. Beispiel:

data-itnrw-module-tools="naechsteAdresse, ausschnittRechteck"

Die Transformation erzeugt - falls eine Callback-Funktion angemeldet wurde - Rückgaben im GeoJSON-Format (siehe Attribut data-itnrw-callbacks).

 

data-itnrw-callbacks (Anmelden einer Rückgabe-Funktion)
Das Definieren einer Rückgabe-Funktion (Callback) wird erforderlich, wenn die GeocodingMap nicht nur Ergebnisse visualisieren soll, sondern der Client Daten weiterverarbeiten möchte. Beispiel: Die ermittelten Koordinaten über das Werkzeug „Setze Koordinaten“ sollen ggf. in eine Datenbank gespeichert werden.

data-itnrw-callbacks="Modul:Funktionsname"

Es können für die Werkzeuge „Nächste Adresse” (naechsteAdresse), „Setze Koordinate“ (setzeKoordinate), „Definition eines Kartenausschnitts als Rechteckt (ausschnittRechteck) und „Definition eines Kartenausschnittes als Kreis“ (ausschnittKreis) sowie die Suche-Leiste (search) und die Koordinaten-Leiste (coords) Callback-Funktionen registriert werden, um die ermittelten Daten weiterzuverarbeiten. Beispiel:

data-itnrw-callbacks="setzeKoordinate:meineFunktion"

Global sollte dann eine Funktion mit dem Namen „meineFunktion“ existieren.

var meineFunktion = function(data) {  //TODO}

In „data“ hat der Entwickler Zugriff auf das Ergebnis. Dabei orientiert sich die Rückgabe am GeoJSON-Standard. Für das obige Bespiel sieht sie z.B. wie folgt aus:

 

data-itnrw-timeout (Verzögerung beim Rendern der Karte)
Dieses Attribut soll nur verwendet werden, wenn es Probleme mit der Erstellung der Karte gibt. Die Karte wird erst nach Ablauf der eingegebenen Zeit erzeugt (Verzögerung in Millisekunden). Beispiel:

data-itnrw-timeout="5000"

 

Die GeocodingMap für die Adresserfassung und Nachverortung verwenden (Beta-Version)

Im Body der HTML-Seite ist ein Bereich zu definieren, in den das Eingabefeld hineingeneriert werden soll. Dies geschieht über ein DIV. Das Klassen-Attribut trägt den Namen itnrwAddress.

Beispiel 1: Das Eingabefeld wird auf einer Registrierungsseite für Nutzerdaten verwendet. Bei der Adresseingabe werden Vorschläge angezeigt, aus denen komfortabel der Treffer selektiert werden kann. Durch die Anmeldung einer Rückgabe-Funktion (Callback) werden die Adressdaten als GeoJSON an den Entwickler zurückgegeben. Die Adressen können somit in eigenen Datenbanken abgespeichert werden. Bei Bedarf kann per CSS das Status-Icon und die Schaltfläche „Adresse bearbeiten“ ausgeblendet werden (hinter der Eingabeleiste).

Vorteil: schnelles Finden der Adresse, einheitliche Schreibweise gewährleisten

<div id="itnrwAddress_0" class="itnrwAddress">
data-itnrw-props="callback:meineFunktion" </div>

Beispiel 2: Das Eingabefeld kann zur nachträglichen Geokodierung verwendet werden (Adressen sind z.B. nur straßengenau bestimmbar, Adresszusätze fehlen, Adresse befindet sich an anderer Stelle). Es können die Adressinformationen auf der linken Seite (s. folgende Abb.) editiert werden. Durch die Anwahl des xy-Werkzeuges in der Karte kann eine neue Koordinate gesetzt werden. Die Schaltfläche „Übernehmen“ gibt die geänderten Adressdaten an den Entwickler zurück.

Parameter für data-itnrw-props:
callback: Rückgabe-Funktion anmelden
width: Breite des Eingabefeldes in px setzen
name: Name des HTML <input /> Elements setzen

<div id="itnrwAddress_0" class="itnrwAddress">
data-itnrw-props="callback:meineFunktion,
width:'400px', name:'unserName_0'" </div>