Geocoding

Geocoding ist der Prozess der Umwandlung von Adressen – wie „Residenzstraße 1, 80333 München“ – in geographische Koordinaten: Breitengrad 48.1417088 und Längengrad 11.5772990. Dieser Vorgang wird durch den Einsatz der Search-API realisiert. Zudem ermöglicht das Reverse Geocoding die Konversion von geographischen Koordinaten in zugehörige Adressinformationen. Durch den Einsatz des Adress Lookup lassen sich detaillierte Informationen zu einem spezifischen Ort abrufen.

---

Search API

Endpunkt

https://api.gdpr-map.eu/search?[PARAMETER]&key=[API_KEY]

Der Suchbegriff kann unstrukturiert oder strukturiert angegeben werden.

---

Unstrukturierte Suche

Unstrukturierte Suchanfragen werden zunächst von links nach rechts und, falls dies fehlschlägt, von rechts nach links verarbeitet. So können Sie sowohl nach „Residenzstraße 1, München“ als auch nach „München, Residenzstraße 1“ suchen. Kommata sind optional, verbessern jedoch die Leistung, indem sie die Komplexität der Suche verringern.

Die unstrukturierte Form kann auch spezielle Ausdrücke enthalten, die den Typ des zurückzugebenden Ortes beschreiben oder eine Koordinate, um in der Nähe einer Position zu suchen.

Parameter	Beschreibung
q	Unstrukturierter Suchbegriff

Beispiel

https://api.gdpr-map.eu/search?q=Residenzstraße 1, München&key=[API_KEY]

---

Strukturierte Suche

Die strukturierte Form der Suchanfrage ermöglicht das Nachschlagen einer Adresse, die bereits in ihre Bestandteile aufgeteilt ist. Jeder Parameter repräsentiert ein Feld der Adresse. Alle Parameter sind optional. Sie sollten nur diejenigen verwenden, die für die Adresse, die Sie geokodieren möchten, relevant sind.

Dies ist nicht mit dem Parameter q aus der unstrukturierten Suche kombinierbar.

Parameter	Beschreibung
amenity	POI-Name oder Typ
street	Straße und Hausnummer
city	Stadt
county	Landkreis
state	Bundesland
country	Land
postalcode	Postleitzahl

Beispiel

https://api.gdpr-map.eu/search?street=Residenzstraße 1&city=München&country=Deutschland&key=[API_KEY]

---

Parameter

Die folgenden Parameter können verwendet werden, um die Suche weiter einzuschränken und die Ausgabe zu ändern. Sie sind für beide Formen der Suchanfrage nutzbar.

Ausgabeformat

Parameter	Werte	Standard
format	xml, json, jsonv2, geojson, geocodejson	jsonv2
json_callback	Callback-Funktion	–
limit	1–40	10

Der Parameter „format“ bestimmt das Ausgabeformat.

Der Parameter „json_callback“ ist ausschließlich für Ausgabeformate in JSON relevant. Wenn angegeben, wird die JSON-Ausgabe in einer Callback-Funktion mit dem angegebenen Namen eingebettet.

Die maximale Anzahl der zurückgegebenen Ergebnisse kann durch den „limit“ Parameter beschränkt werden. Er darf nicht mehr als 40 betragen.

---

Ausgabedetails

Parameter	Werte	Standard
addressdetails	0 / 1	0
extratags	0 / 1	0
namedetails	0 / 1	0

Wenn Sie die Adresse in ihre Bestandteile aufschlüsseln möchten, setzen Sie den Parameter „addressdetails“ auf 1. Der genaue Inhalt der Adressaufschlüsselung hängt vom Ausgabeformat ab.

Benötigen Sie zusätzliche Informationen im Ergebnis, die in der Datenbank verfügbar sind, wie zum Beispiel Wikipedia-Link oder Öffnungszeiten, dann setzen Sie „extratags“ auf 1.

Sollten Sie an der Liste aller bekannten Namen interessiert sein, setzen Sie „namedetails“ auf 1. Dadurch werden auch ältere Namen, Namensvarianten, Referenzen oder Markennamen ausgegeben.

---

Sprache

Parameter	Beschreibung
accept-language	ISO-Sprachcodes oder HTTP-Header-Format

Bevorzugte Sprachreihenfolge für die Anzeige von Suchergebnissen. Dies kann entweder eine einfache, durch Kommas getrennte Liste von Sprachcodes sein oder dasselbe Format wie der „Accept-Language“ HTTP-Header haben.

---

Filter & Boost

Es gibt zwei Möglichkeiten, die Ergebnisse zu beeinflussen. Filter schließen bestimmte Arten von Ergebnissen vollständig aus. Boost-Parameter ändern lediglich die Reihenfolge der Ergebnisse und geben somit einigen Ergebnissen gegenüber anderen den Vorzug.

Parameter	Beschreibung
countrycodes	ISO 3166-1 alpha-2 Codes

Filter, der die Suchergebnisse auf ein oder mehrere Länder beschränkt. Der Ländercode muss dem ISO 3166-1 alpha-2-Code des Landes entsprechen, z. B. gb für das Vereinigte Königreich, de für Deutschland.

Jedem Ort wird anhand der OSM-Ländergrenzen ein Ländercode zugeordnet. In seltenen Fällen kann sich ein Ort überhaupt nicht in einem Land befinden, zum Beispiel wenn er sich in internationalen Gewässern befindet. Diese Orte werden ebenfalls ausgeschlossen, wenn der Filter gesetzt ist.

Dieser Parameter sollte nicht mit dem ‚country‘-Parameter der strukturierten Suche verwechselt werden. Der ‚country‘-Parameter enthält einen Suchbegriff und wird fuzzy behandelt. Der Parameter ‚countrycodes‘ ist ein exakter Filter und sollte daher bevorzugt werden. Beide Parameter in derselben Abfrage zu verwenden, funktioniert. Wenn die Parameter einander widersprechen, wird die Suche ergebnislos bleiben.

Parameter	Beschreibung
featureType	country, state, city, settlement

Der Parameter „featureType“ ermöglicht eine feinere Auswahl von Orten aus der Adressschicht. Die Ergebnisse können auf Orte beschränkt werden, die den ’state‘ (Bundesstaat), ‚country‘ (Land) oder ‚city‘ (Stadt) Teil einer Adresse bilden. Ein featureType von „settlement“ wählt jedes von Menschen bewohnte Merkmal von ’state‘ bis hinunter zu ’neighbourhood‘ (Nachbarschaft).

Parameter	Beschreibung
exclude_place_ids	Kommagetrennte Place-IDs

Wenn Sie nicht möchten, dass bestimmte OSM-Objekte im Suchergebnis erscheinen, geben Sie eine durch Kommas getrennte Liste der Place-IDs an, die Sie überspringen möchten. Dies kann verwendet werden, um zusätzliche Suchergebnisse zu erhalten. Zum Beispiel, wenn eine vorherige Abfrage nur wenige Ergebnisse geliefert hat, würde deren Einbeziehung hier dazu führen, dass die Suche andere, weniger genaue Übereinstimmungen zurückgibt (falls möglich).

Parameter	Beschreibung
viewbox	x1,y1,x2,y2

Boost-Parameter, der die Suche auf das angegebene Gebiet einschränkt. Es werden zwei beliebige Eckpunkte des Rechtecks akzeptiert, solange sie ein ordnungsgemäßes Rechteck bilden. Dabei steht x für Längengrad und y für Breitengrad.

Parameter	Beschreibung
bounded	0 / 1

Wenn auf 1 gesetzt, verwandelt dies den ‚viewbox‘-Parameter (siehe oben) in einen Filterparameter, der alle Ergebnisse außerhalb der Viewbox ausschließt.

Wenn bounded=1 angegeben ist und die Viewbox klein genug ist, dann ist eine ausschließliche Einrichtungs-Suche möglich. Geben Sie das spezielle Schlagwort für die Einrichtung in eckigen Klammern an, z.B. [pub], und eine Auswahl von Objekten dieses Typs wird zurückgegeben. Es gibt keine Garantie, dass das Ergebnis alle Objekte in dem Bereich zurückgibt.

---

Polygone

Parameter	Werte	Standard
polygon_geojson	0 / 1	0
polygon_kml	0 / 1	0
polygon_svg	0 / 1	0
polygon_text	0 / 1	0

Füget die vollständige Geometrie des Ortes zur Ausgabe des Ergebnisses hinzu. Ausgabeformate in GeoJSON, KML, SVG oder WKT werden unterstützt. Es kann jeweils nur eine dieser Optionen verwendet werden.

Parameter	Werte	Standard
polygon_threshold	Fließkommazahl	0.0

Wenn eine der polygon_*-Ausgaben gewählt wird, wird eine vereinfachte Version der Ausgabegeometrie zurückgegeben. Der Parameter beschreibt die Toleranz in Grad, um die sich die Geometrie von der ursprünglichen Geometrie unterscheiden darf. Die Topologie wird in der Geometrie erhalten.

Sonstiges

Parameter	Werte	Standard
dedupe	0 / 1	1
debug	0 / 1	0

Manchmal gibt es in OSM mehrere Objekte, die denselben Ort oder dasselbe Objekt identifizieren. Der einfachste Fall ist eine Straße, die aufgrund unterschiedlicher Merkmale in viele verschiedene OSM-Wege aufgeteilt wird. Nominatim wird versuchen, solche Duplikate zu erkennen und nur eine Übereinstimmung zurückzugeben. Das Setzen dieses Parameters „dedupe“ auf 0 deaktiviert diesen Deduplizierungsmechanismus und stellt sicher, dass alle Ergebnisse zurückgegeben werden.

Der Parameter „debug“ gibt verschiedene Entwickler-Debug-Informationen aus. Daten über die Interna der „Suchschleifen“-Logik und SQL-Abfragen. Die Ausgabe erfolgt im HTML-Format. Dies überschreibt das angegebene maschinenlesbare Format.

---

Reverse Geocoding

Reverse Geocoding erzeugt eine Adresse aus einer als Breitengrad und Längengrad gegebenen Koordinate.

Die Reverse Geocoding API berechnet nicht die genaue Adresse der Koordinaten, sondern ermittelt das nächstgelegene OSM-Objekt und dessen Adressinformationen. Dies kann gelegentlich zu unerwarteten Ergebnissen führen.

Zunächst sind nur OSM-Objekte enthalten, die für die Suche geeignet sind. Kleine, unbenannte Wege zum Beispiel fehlen in der Datenbank und können daher auch nicht für das Reverse Geocoding verwendet werden.

Ein weiteres Problem, das beachtet werden muss, ist, dass das nächstgelegene OSM-Objekt nicht immer eine ähnlich passende Adresse zu der angeforderten Koordinate haben mag. Beispielsweise kann es in dicht bebauten Stadtgebieten zu einer völlig anderen Straße gehören.

Endpunkt

https://api.gdpr-map.eu/reverse?lat=[lat]&lon=[lon]&[PARAMETER]&key=[API_KEY]

Die Parameter „latitude“ und „longitude“ entsprechen Breitegrad und Längengrad einer Koordinate in der WGS84-Projektion. Die API gibt genau ein Ergebnis oder einen Fehler zurück, wenn die Koordinate in einem Bereich ohne OSM-Datenabdeckung liegt.

Beispiel

https://api.gdpr-map.eu/reverse?lat=48.1417088&lon=11.5772990&key=[API_KEY]

Parameter

Dieser Abschnitt listet zusätzliche Parameter auf, um die Ausgabe weiter zu beeinflussen.

Ausgabeformat

Parameter	Werte	Beschreibung
format	xml, json, jsonv2, geojson, geocodejson	jsonv2
json_callback	Name der Callback Funktion	nicht gesetzt

Der Parameter „format“ bestimmt das Ausgabeformat.

Der Parameter „json_callback“ ist ausschließlich für Ausgabeformate in JSON relevant. Wenn angegeben, wird die JSON-Ausgabe in einer Callback-Funktion mit dem angegebenen Namen eingebettet.

Ausgabe Details

Parameter	Werte	Standard
addressdetails	0 / 1	0
extratags	0 / 1	0
namedetails	0 / 1	0

Wenn Sie die Adresse in ihre Bestandteile aufschlüsseln möchten, setzen Sie den Parameter „addressdetails“ auf 1. Der genaue Inhalt der Adressaufschlüsselung hängt vom Ausgabeformat ab.

Benötigen Sie zusätzliche Informationen im Ergebnis, die in der Datenbank verfügbar sind, wie zum Beispiel Wikipedia-Link oder Öffnungszeiten, dann setzen Sie „extratags“ auf 1.

Sollten Sie an der Liste aller bekannten Namen interessiert sein, setzen Sie „namedetails“ auf 1. Dadurch werden auch ältere Namen, Namensvarianten, Referenzen oder Markennamen ausgegeben.

Ausgabesprache

Parameter	Werte	Standard
accept-language	de,en,...	Inhalt des „Accept-Language“ HTTP header

Bevorzugte Sprachreihenfolge für die Anzeige von Suchergebnissen. Dies kann entweder eine einfache, durch Kommas getrennte Liste von Sprachcodes sein oder dasselbe Format wie der „Accept-Language“ HTTP-Header haben.

Ausgabe einschränken

Parameter	Werte	Standard
zoom	0–18	18

Detailgrad, der für die Adresse erforderlich ist. Dies ist eine Zahl, die ungefähr dem Zoomniveau entspricht, das in XYZ-Kachelquellen in Frameworks wie z.B. Maplibre GL verwendet wird. In Bezug auf die Adressdetails sind die Zoomstufen wie folgt:

zoom	Detailstufe
3	Land
5	Bundesland
8	Landkreis
10	Stadt
12	Stadt / Stadtbezirk
13	Dorf / Vorort
14	Nachbarschaft
15	jegliche Siedlung
16	Hauptstraßen
17	Haupt- und Nebenstraßen
18	Gebäude

Ausgabe von Polygonen

Parameter	Werte	Standard
polygon_geojson	0 / 1	0
polygon_kml	0 / 1	0
polygon_svg	0 / 1	0
polygon_text	0 / 1	0

Fügt die vollständige Geometrie des Ortes zur Ausgabe des Ergebnisses hinzu. Ausgabeformate in GeoJSON, KML, SVG oder WKT werden unterstützt. Es kann jeweils nur eine dieser Optionen verwendet werden.

Parameter	Werte	Standard
polygon_threshold	Fließkommazahl	0.0

Wenn eine der polygon_*-Ausgaben gewählt wird, wird eine vereinfachte Version der Ausgabegeometrie zurückgegeben. Der Parameter beschreibt die Toleranz in Grad, um die sich die Geometrie von der ursprünglichen Geometrie unterscheiden darf. Die Topologie bleibt in der Geometrie erhalten.

Sonstiges

Parameter	Werte	Standard
debug	0 / 1	0

Der Parameter „debug“ gibt verschiedene Entwickler-Debug-Informationen aus. Daten über die Interna der „Suchschleifen“-Logik und SQL-Abfragen. Die Ausgabe erfolgt im HTML-Format. Dies überschreibt das angegebene maschinenlesbare Format.

---

Address Lookup

Die Address Lookup API ermöglicht es, die Adresse und andere Details von einem oder mehreren OSM-Objekten wie Knoten (node), Wegen (way) oder Relationen (relation) abzufragen.

Endpunkt

https://api.gdpr-map.eu/lookup?osm_ids=[N|W|R][id]&[PARAMETER]&key=[API_KEY]

Der Parameter „osm_ids“ ist obligatorisch und muss eine durch Kommas getrennte Liste von OSM-IDs enthalten, die jeweils mit ihrem Typ gekennzeichnet sind, entweder Knoten (N), Weg (W) oder Relation (R). Es können gleichzeitig bis zu 50 IDs abgefragt werden.

Beispiel

https://api.gdpr-map.eu/lookup?osm_ids=N392410378,W175574445,R56392&key=[API_KEY]

Der Parameter „osm_ids“ ist obligatorisch und muss eine durch Kommas getrennte Liste von OSM-IDs enthalten, die jeweils mit ihrem Typ gekennzeichnet sind, entweder Knoten (N), Weg (W) oder Relation (R). Es können gleichzeitig bis zu 50 IDs abgefragt werden.

Parameter

Dieser Abschnitt listet zusätzliche Parameter auf, um die Ausgabe weiter zu beeinflussen.

Parameter	Wert	Standard
format	Eins aus: xml, json, jsonv2, geojson, geocodejson	jsonv2
json_callback	Name der Callback Funktion	nicht gesetzt

Der Parameter „format“ bestimmt das Ausgabeformat.

Der Parameter „json_callback“ ist ausschließlich für Ausgabeformate in JSON relevant. Wenn angegeben, wird die JSON-Ausgabe in einer Callback-Funktion mit dem angegebenen Namen eingebettet.

Ausgabe Details

Parameter	Wert	Standard
addressdetails	0 / 1	0
extratags	0 / 1	0
namedetails	0 / 1	0

Wenn Sie die Adresse in ihre Bestandteile aufschlüsseln möchten, setzen Sie den Parameter „addressdetails“ auf 1. Der genaue Inhalt der Adressaufschlüsselung hängt vom Ausgabeformat ab.

Benötigen Sie zusätzliche Informationen im Ergebnis, die in der Datenbank verfügbar sind, wie zum Beispiel Wikipedia-Link oder Öffnungszeiten, dann setzen Sie „extratags“ auf 1.

Sollten Sie an der Liste aller bekannten Namen interessiert sein, setzen Sie „namedetails“ auf 1. Dadurch werden auch ältere Namen, Namensvarianten, Referenzen oder Markennamen ausgegeben.

Ausgabesprache

Parameter	Wert	Standard
accept-language	Browser-Sprachkennung	Inhalt des „Accept-Language“ HTTP header

Bevorzugte Sprachreihenfolge für die Anzeige von Suchergebnissen. Dies kann entweder eine einfache, durch Kommas getrennte Liste von Sprachcodes sein oder dasselbe Format wie der „Accept-Language“ HTTP-Header haben.

Ausgabe von Polygonen

Parameter	Wert	Standard
polygon_geojson	0 / 1	0
polygon_kml	0 / 1	0
polygon_svg	0 / 1	0
polygon_text	0 / 1	0

Füget die vollständige Geometrie des Ortes zur Ausgabe des Ergebnisses hinzu. Ausgabeformate in GeoJSON, KML, SVG oder WKT werden unterstützt. Es kann jeweils nur eine dieser Optionen verwendet werden.

Parameter	Wert	Standard
polygon_threshold	Fließkommazahl	0.0

Wenn eine der polygon_*-Ausgaben gewählt wird, wird eine vereinfachte Version der Ausgabegeometrie zurückgegeben. Der Parameter beschreibt die Toleranz in Grad, um die sich die Geometrie von der ursprünglichen Geometrie unterscheiden darf. Die Topologie wird in der Geometrie erhalten.

Sonstiges

Parameter	Wert	Standard
debug	0 oder 1	0

Der Parameter „debug“ gibt verschiedene Entwickler-Debug-Informationen aus. Daten über die Interna der „Suchschleifen“-Logik und SQL-Abfragen. Die Ausgabe erfolgt im HTML-Format. Dies überschreibt das angegebene maschinenlesbare Format.

---

API Call Beispiele

cURL

curl "https://api.gdpr-map.eu/search?q=Berlin&key=API_KEY"

PHP

$response = file_get_contents(
  "https://api.gdpr-map.eu/search?q=Berlin&key=API_KEY"
);
echo $response;

Python

import requests

r = requests.get(
    "https://api.gdpr-map.eu/search",
    params={"q": "Berlin", "key": "API_KEY"}
)
print(r.json())

Node.js

const res = await fetch(
  "https://api.gdpr-map.eu/search?q=Berlin&key=API_KEY"
);
console.log(await res.json());