POST-Anforderung an Geocode
Mithilfe der POST-Anforderung können Sie eine einzelne Eingabeadresse oder eine Liste von Adressen zur Batch-Verarbeitung senden. Vergleichs- und/oder Geocoding-Einstellungen können optional für den Geocode-Dienst angegeben werden. Zudem erhalten Sie die zugehörigen Koordinaten für den Breitengrad/Längengrad sowie Standortinformationen. Die Einstellungsoptionen für eine POST-Anforderung sind die vollständige Gruppe der verfügbaren Optionen.
Basis-URI
http://<server>:<port>/rest/GlobalGeocode/geocode[.content type]
Wo:
- json
- JSON ist der standardmäßige Inhaltstyp, es sei denn, er wird durch eine HTTP-Inhaltsaushandlung ersetzt
- xml
- XML ist der standardmäßige Inhaltstyp, es sei denn, er wird durch eine HTTP-Inhaltsaushandlung ersetzt
Anforderungsparameter
- addresses: Die Adresse oder die Adressen, für die ein Geocoding ausgeführt werden soll. Erforderlich.
- type: Der Typ des Geocodes. Optional:
- preferences: Die Vergleichs- und Geocoding-Optionen. Optional:
- mustMatchMode: Die Vergleichskriterien zum Ermitteln der übereinstimmenden Kandidaten. Optional.
- returnFieldsDescriptor: Steuert die Rückgabe zusätzlicher Daten zu einem Kandidaten. Optional:
Adressparameter
>Das Adressenarray von Address-Objekten. Das Array „addresses“ kann eine oder mehrere Eingabeadressen enthalten. Das Adressenelement ist ein erforderliches Element.
Parameter | Typ | Beschreibung |
---|---|---|
placeName | Zeichenfolge | Gebäudename, Ortsname, Point of Interest (POI), Unternehmens- oder Firmenname, der mit der eingegebenen Adresse verknüpft ist. Optional: Beispiel: Pitney Bowes |
mainAddress | Zeichenfolge | Einzeilige Eingabe: Wenn kein anderes Feld ausgefüllt ist, wird der Eintrag mainAddress als Eingabe in eine einzelne Zeile verarbeitet. Es kann sich dabei um eine Sammlung von Adressfeldelementen handeln. Die Eingabereihenfolge der Adressfelder sollte der standardmäßigen Adressenformatierung Ihres Landes entsprechen. Optional: Beispiel: 4750 Walnut St., Boulder CO, 80301 Straßenanschrift: Wenn die Adressfelder (placeName, lastLine, postalCode usw.) separat eingegeben werden, wird der Inhalt dieses Feldes als der Teil für die Straßenanschrift verwendet und kann den Unternehmensnamen, die Hausnummer, Gebäudenamen und Straßennamen beinhalten. Optional: Straßenkreuzungseingabe: Um eine Kreuzung einzugeben, geben Sie die beiden Straßennamen ein, und trennen Sie sie anhand eines doppelten kaufmännischen Und-Zeichens (&&). |
lastLine | Zeichenfolge | Die letzte Zeile der Adresse. Optional: |
areaName1 | Zeichenfolge | Gibt das größte geografische Gebiet an, normalerweise ein Bundesland oder Kanton. Optional: |
areaName2 | Zeichenfolge | Gibt das zweitgrößte geografische Gebiet an, normalerweise ein Bezirk oder Landkreis. Optional: |
areaName3 | Zeichenfolge | Gibt einen Stadt- oder Ortsnamen an. Optional: |
areaName4 | Zeichenfolge | Gibt die Unterteilung eines Ortes oder einer Lokalität an. Optional: |
postCode1 | Zeichenfolge | Die Postleitzahl im entsprechenden Format des Landes. Optional: |
postCode2 | Zeichenfolge | Die Postleitzahlerweiterung im entsprechenden Format des Landes. Optional: |
country | Zeichenfolge | ISO 3166-1 Alpha-3-Ländercode. Erforderlich. Informationen zu Ländercodes erhalten Sie unter Länderreferenzliste und ISO 3166-1-Ländercodes. |
addressNumber | Zeichenfolge | Haus- oder Gebäudenummer. |
streetName | Zeichenfolge | Straßenname. |
unitType | Zeichenfolge | Gibt den Typ der Einheit an, z. B. Wohnung, Etage und Gebäude. |
unitValue | Zeichenfolge | Gibt den Wert/die Nummer der Einheit an, z. B. „3B“. |
Typparameter
Das type -Objekt vom Typ geocodeType hat die folgenden Parameter. Der Typparameter ist optional.Parameter | Typ | Beschreibung |
---|---|---|
geocodeType | Zeichenfolge |
Gibt den auszuführenden Geocode-Typ an. Optional:
|
Präferenzparameter
Das preferences-Objekt des Typs Preferences besteht aus den folgenden Elementen. Die folgenden Elemente gelten nur für den Geocode-Dienst. Das preferences-Element ist optional.
Um den Standardwert eines preferences-Elements für ein bestimmtes Land außer Kraft zu setzen, geben Sie das Schlüssel-Wert-Paar im Objekt customPreferences an, wobei vor der Schlüsselkonstanten der dreistellige ISO-3166-Ländercode mit einem Punkt steht. Beispiel: DEU.fallbackToGeographic
.
Parameter | Typ | Beschreibung |
---|---|---|
returnAllCandidateInfo | Boolean | Gibt an, ob alle verfügbaren Informationen für jeden Kandidaten zurückgegeben werden sollen.
|
fallbackToGeographic | Boolean | Gibt an, ob versucht werden soll, den Mittelpunkt einer geografischen Region zu bestimmen, wenn kein Geocode auf Adressebene bestimmt werden kann. Optional:
|
fallbackToPostal | Boolean | Gibt an, ob versucht werden soll, den Mittelpunkt einer Postleitzahl zu bestimmen, wenn kein Geocode auf Adressebene bestimmt werden kann. Optional:
|
FALLBACK_TO_WORLD | Zeichenfolge | Wenn XWG installiert ist: Gibt an, ob der World Geocoder (XWG) zum Ermitteln eines Geocodes verwendet werden soll, wenn kein Land-Geocoder installiert ist oder ein Land-Geocoder ohne ein Geocoding-Dataset installiert ist. Der World Geocoder (XWG) gibt entweder einen postalischen oder einen geografischen Geocode zurück, je nach dem Unterstützungsgrad im XWG-Geocoding-Dataset. Optional:
|
maxReturnedCandidates | Ganze Zahl | Die maximale Anzahl zurückzugebender Kandidaten. Optional: Muss ein Ganzzahlwert sein. Standard = 1. |
streetOffset | Double | Gibt den Versatzabstand von den Straßensegmenten an, die beim Geocoding auf Straßenebene verwendet werden sollen. Die Entfernung wird in den Einheiten angegeben, die Sie in der Option streetOffsetUnits angeben. Standardwert = 7 m. Der Versatzabstand dient beim Geocoding auf Straßenebene zur Vermeidung der Positionierung des Geocodes in der Mitte der Straße. Er gleicht den Umstand aus, dass beim Geocoding auf Straßenebene ein Punkt für den Breitengrad und den Längengrad in der Mitte der Straße, an der sich die Adresse befindet, zurückgegeben wird. Da sich das Gebäude, das durch eine Adresse bezeichnet wird, nicht auf der Straße selbst befindet, sollte der Geocode für eine Adresse kein Punkt auf der Straße sein. Stattdessen soll der Geocode den Standort des Gebäudes darstellen, das sich neben der Straße befindet. Ein Versatz von 50 Fuß bedeutet beispielsweise, dass der Geocode einen Punkt darstellt, der 50 Fuß von der Mitte der Straße entfernt ist. Die Entfernung wird senkrecht zum Teil des Straßensegments der Adresse berechnet. Mithilfe des Versatzes wird auch verhindert, dass einander gegenüberliegende Adressen denselben Punkt erhalten. Im folgenden Diagramm wird ein Versatzpunkt im Vergleich zum ursprünglichen Punkt dargestellt. |
streetOffsetUnits | Zeichenfolge | Gibt die Maßeinheit für den Straßenversatz an. Zur Auswahl stehen:
|
cornerOffset | Double | Gibt die Entfernung für den Versatz der Straßenendpunkte beim Vergleich auf Straßenebene an. Die Entfernung wird in den Einheiten angegeben, die Sie in der Option cornerOffsetUnits angeben. Mithilfe dieses Wertes wird verhindert, dass Adressen an Straßenecken denselben Geocode wie die Kreuzung erhalten. Definiert die Versatzposition des geocodierten Punktes in Bezug auf die Ecke. Standardwert = 7 m. Im folgenden Diagramm werden die Endpunkte einer Straße mit Versatzendpunkten verglichen. |
cornerOffsetUnits | Zeichenfolge | Gibt die Maßeinheit für den Eckversatz an. Zur Auswahl stehen:
|
matchMode | Zeichenfolge | Der Abgleichmodus legt fest, wie genau die Übereinstimmung zwischen der Eingabeadresse und den Referenzdaten sein muss. Wählen Sie einen Vergleichsmodus basierend auf der Qualität Ihrer Eingabe sowie der gewünschten Ausgabe aus. Die folgenden Abgleichmodi sind verfügbar:
|
clientCoordSysName | Zeichenfolge | Gibt das Koordinatensystem an, in das Sie die Geometry umwandeln möchten. Das Format muss dem EPSG-Code (European Petroleum Survey Group) oder dem SRID-Code entsprechen. Standardeinstellung = EPSG:4326 . Geben Sie das referenzierte Koordinatensystem im Format |
customPreferences | Map<String key, String value> | Gibt die landesspezifischen Eingabeeinstellungen an. Mithilfe dieses Objekts können Sie Folgendes angeben:
Um den Standardwert für ein bestimmtes Land außer Kraft zu setzen, stellen Sie der Schlüsselkonstanten den dreistelligen ISO-3166-Ländercode sowie einen Punkt voran, und geben Sie anschließend den Wert an. In einer XML-Anforderung würde eine Eingabe für eine landesspezifische Außerkraftsetzung beispielsweise folgendermaßen aussehen:
Benutzerdefinierte landesspezifische Eingabeoptionen sind für die folgenden Länder verfügbar:
Für Länder, die sowohl benutzerdefinierte Benutzerwörterbücher als auch standardmäßige Geocoding-Datasets unterstützen, können Sie eine benutzerdefinierte Einstellung mit dem Schlüssel KEY_CUSTOM_DICTIONARY_USAGE festlegen, der die Such- und Vergleichseinstellungen definiert, wenn in der Geocoding-Engine sowohl benutzerdefinierte Benutzerwörterbücher als auch standardmäßige Geocoding-Datasets verfügbar sind. Diese Option ist nur beim Forward Geocoding verfügbar. Weitere Informationen finden Sie unter Festlegen von Such- und Vergleichseinstellungen bei Verwendung von Standard- und Benutzerwörterbüchern. Informationen dazu, ob Ihr Land benutzerdefinierte Benutzerwörterbücher unterstützt, erhalten Sie im Abschnitt „Unterstützte Geocoding-Datasets“ im Kapitel des jeweiligen Landes. Wenn der World Geocoder (XWG) installiert ist, können Sie eine benutzerdefinierte Einstellung namens FALLBACK_TO_WORLD festlegen. Diese Einstellung gibt an, ob der XWG zum Ermitteln eines Geocodes verwendet werden soll, wenn kein Land-Geocoder installiert ist oder ein Land-Geocoder ohne ein Geocoding-Dataset installiert ist. XWG gibt entweder einen postalischen oder einen geografischen Geocode entsprechend dem Unterstützungsgrad im XWG-Geocoding-Dataset zurück. Optional:
|
preferredDictionaryOrder | List<String> | Gibt die Suchreihenfolge für das Wörterbuch an, wenn mehrere Wörterbücher installiert sind. Die standardmäßige Suchreihenfolge ist die Sortierung, in der die Wörterbücher konfiguriert sind. |
mustMatchFields-Parameter
Das mustMatchFields-Objekt vom Typ FieldsMatching ermöglicht das Festlegen der Vergleichskriterien zum Ermitteln von übereinstimmenden Kandidaten. Um diese Optionen zu aktivieren, müssen Sie das Feld matchMode auf Custom setzen.
Um den Standardwert eines mustMatchFields-Elements für ein bestimmtes Land außer Kraft zu setzen, geben Sie das Schlüssel-Wert-Paar im Objekt customPreferences an, wobei vor der Schlüsselkonstanten der dreistellige ISO-3166-Ländercode mit einem Punkt steht. Beispiel: „CAN.matchOnAddressNumber
“.
Parameter | Typ | Beschreibung |
---|---|---|
matchOnAddressNumber | Boolean |
|
matchOnPostCode1 | Boolean |
|
matchOnAreaName1 | Boolean |
|
matchOnAreaName2 | Boolean |
Anmerkung: Diese Option wird für die USA nicht unterstützt.
|
matchOnAreaName3 | Boolean |
|
matchOnAreaName4 | Boolean |
|
matchOnAllStreetFields | Boolean |
|
mustMatchInput | Boolean |
|
returnFieldsDescriptor
Das returnFieldsDescriptor-Objekt des Typs returnFieldsDescriptor steuert die Rückgabe zusätzlicher Daten eines Kandidaten. Standardmäßig werden die erweiterten Kandidateninformationen nicht zurückgegeben. In Fällen, in denen jedoch mehrere verfügbar sind, können sie folgendermaßen gesteuert werden:
Um den Standardwert eines returnFieldsDescriptor-Elements für ein bestimmtes Land außer Kraft zu setzen, geben Sie das Schlüssel-Wert-Paar im Objekt customPreferences an, wobei vor der Schlüsselkonstanten der dreistellige ISO-3166-Ländercode mit einem Punkt steht. Beispiel: „AUS.returnAllCustomFields
“.
Parameter | Typ | Beschreibung |
---|---|---|
returnAllCustomFields | Boolean |
|
returnedCustomFieldKeys | List<String> | Gibt eine Liste von Schlüsseln an, welche die benutzerdefinierten Felder darstellen, die in der Ausgabe customFields des Kandidaten zurückgegeben werden sollen. Beispiel: „CTYST_KEY “ oder „DATATYPE “. Standard: leer.Anmerkung: Um mehrere Schlüssel-Wert-Paare für ein Land anzugeben, trennen Sie die Namen der zurückzugebenden benutzerdefinierten Felder mit Leerzeichen. Beispiel:
"USA.returnedCustomFieldKeys" : "LAT LON SHORT_CITY" . Kandidaten, bei denen diese Informationen verfügbar sind, enthalten die drei benutzerdefinierten Felder mit diesen Schlüsseln in der Ausgabe customFields des Kandidaten.Anmerkung: Benutzerdefinierte Felder unterscheiden sich von Land zu Land. Die für Ihr Land geltenden Informationen finden Sie im Abschnitt Landesspezifische Informationen im Anhang, in dem weitere Details aufgeführt werden.
|
returnMatchDescriptor | Boolean |
|
returnStreetAddressFields | Boolean |
|
returnUnitInformation | Boolean |
|