Adressen und Koordinaten geocodieren

Zweck und Einsatzbereich

NeuraPort enthält zwei technisch vorbereitete Integrationsfunktionen: eine Suche nach einer Adresse und eine Rückauflösung von Koordinaten zu einer Adresse. Beide verwenden den externen Dienst Nominatim von OpenStreetMap. Die Ergebnisse werden nur zurückgegeben; es wird dadurch kein Stamm- oder Aktendatensatz angelegt oder geändert.

Für diese Funktion ist im geprüften Stand kein sichtbarer Menüeintrag und keine eingebundene Produktmaske belegt. Zwar enthält das Frontend eine vorbereitete Komponente für Adressvorschläge, ihre Verwendung in einer Route oder einem Formular ist jedoch nicht belegt. Behandeln Sie die Funktion daher derzeit als Integrationsmöglichkeit, nicht als allgemein verfügbaren Bedienablauf in der Oberfläche.

Voraussetzungen und Berechtigungen

Der technische Vertrag verlangt einen angemeldeten Benutzerzugang und mindestens eines der folgenden für die aktuelle Organisationseinheit zugänglichen Transportmodule: Ocean Export, Ocean Import, Air Export, Air Import, Road oder Warehouse. Die beiden Funktionen sind als lesende Abfragen ausgelegt; ein gesondertes fachliches Recht für Geocoding ist nicht belegt.

Die tatsächliche Freigabe hängt außerdem von der Modul-Lizenzkonfiguration der Zielumgebung ab. Lassen Sie einen fehlenden Zugriff deshalb durch die Administration zusammen mit der Lizenz- und Modulkonfiguration prüfen.

Die Antwort hängt von der Erreichbarkeit des externen Nominatim-Dienstes ab. Für den produktiven Einsatz muss dessen Nutzung einschließlich Rate- und Datenschutzvorgaben freigegeben sein.

Schritt-für-Schritt-Anleitung

Ein bestätigter Bedienweg innerhalb der NeuraPort-Oberfläche ist nicht vorhanden. Führen Sie daher keine vermeintliche Navigation oder technische Abfrage aus dieser Seite ab.

Prüfen Sie, ob an Ihrem freigegebenen Arbeitsplatz überhaupt eine Geocoding-Funktion sichtbar ist. Fehlt sie, behandeln Sie die Funktion als nicht bedienbar.
Bitten Sie die zuständige Administration oder das Integrationsteam um Bestätigung des vorgesehenen Integrationswegs, des benötigten Transportmoduls und der Freigabe des externen Providers.
Lassen Sie vor einer produktiven Verwendung Rate-, Datenschutz- und Datenminimierungsvorgaben festlegen. Übermittelt werden dürfen nur die für Suche oder Rückauflösung erforderlichen Angaben.
Prüfen Sie jedes bereitgestellte Ergebnis fachlich, bevor Sie Angaben manuell in Stamm- oder Aktendaten übernehmen. Orts-, Länder- und Hausnummernangaben können unvollständig sein.
Behandeln Sie eine leere Trefferliste oder ein ausbleibendes Rückauflösungsergebnis als kein Ergebnis, nicht als bestätigte Adresse.
Erfassen Sie die Adresse bei Leer- oder Fehlerzuständen manuell über den dafür freigegebenen Stammdatenweg und melden Sie den Integrationsfehler mit Zeitpunkt und betroffener Funktion an die Administration.

Die vorhandene, aber nicht nachweislich eingebundene Vorschlagskomponente fragt erst ab vier eingegebenen Zeichen nach einer kurzen Eingabepause ab und fordert sechs Treffer an. Daraus folgt kein zugesicherter Ablauf für eine sichtbare NeuraPort-Maske.

Feldreferenz

Die folgende Tabelle beschreibt den belegten technischen Datenvertrag für Administration und Integrationsteam. Sie ist keine Self-Service-Anleitung und begründet keinen sichtbaren Bedienweg.

Feld	Pflicht	Bedeutung	Validierung
`q`	Ja, bei Adresssuche	Suchbegriff für Adresse oder Ort	Mindestens 3 Zeichen.
`limit`	Nein	Höchstzahl der Treffer aus der Adresssuche	Ganze Zahl von 1 bis 10; Standardwert 5.
`lat`	Ja, bei Koordinatenrückauflösung	Breitengrad der aufzulösenden Position	Zahlenwert; ein zusätzlicher fachlicher Wertebereich ist im technischen Vertrag nicht festgelegt.
`lon`	Ja, bei Koordinatenrückauflösung	Längengrad der aufzulösenden Position	Zahlenwert; ein zusätzlicher fachlicher Wertebereich ist im technischen Vertrag nicht festgelegt.
`display_name`	Antwortfeld	Vollständige, vom Dienst gelieferte Orts- oder Adressbezeichnung	Kann leer sein.
`lat` / `lon` in der Antwort	Antwortfeld	Koordinaten des Suchtreffers beziehungsweise die übergebenen Koordinaten bei Rückauflösung	Werden als Textwerte zurückgegeben.
`address.road`, `address.house_number`, `address.city`, `address.postcode`, `address.country`, `address.country_code`	Antwortfeld	Strukturierte Adressbestandteile	Einzelne Bestandteile können fehlen. Der Ländercode wird, wenn vorhanden, in Großbuchstaben zurückgegeben.
`type`	Antwortfeld der Adresssuche	Vom externen Dienst gelieferte Treffertypisierung	Kann fehlen oder vom Dienst abhängen.

Status und mögliche Übergänge

Auslöser	Ergebnis
Adresssuche mit gültigem Suchbegriff	Es wird eine temporäre Trefferliste zurückgegeben; kein NeuraPort-Datensatz ändert seinen Status.
Adresssuche ohne Treffer	Es wird eine leere Liste zurückgegeben.
Koordinatenrückauflösung mit Ergebnis	Eine temporäre Adressdarstellung wird zurückgegeben; kein NeuraPort-Datensatz ändert seinen Status.
Koordinatenrückauflösung bei Provider- oder Verarbeitungsfehler	Die Integration liefert kein Ergebnis (`null`).

Was im Hintergrund passiert

NeuraPort übermittelt bei der Suche den Suchbegriff und bei der Rückauflösung die Koordinaten an Nominatim. Die Anfrage enthält zusätzlich das gewünschte Sprachformat Deutsch/Englisch. Der Dienst antwortet mit Orts- und Adressdaten; NeuraPort reduziert diese auf die in der Feldreferenz genannten Werte.

Der Dienstaufruf hat im geprüften Stand ein Zeitlimit von zehn Sekunden. Innerhalb eines laufenden Backend-Prozesses wartet die Implementierung mindestens ungefähr 1,1 Sekunden zwischen zwei Aufrufen. Dies ist eine einfache technische Begrenzung, keine Zusage für eine organisationsweite oder produktionsweite Rate-Garantie.

Suchbegriff, Adresse und Koordinaten werden nicht vor der Übergabe anonymisiert. Übermitteln Sie daher nur Daten, die für die Suche erforderlich sind, und klären Sie den Einsatz des externen Dienstes mit Datenschutz und Betrieb. Eine produktive Freigabe einschließlich der zulässigen Rate ist noch offen.

Typische Fehler und Lösungen

Meldung oder Beobachtung	Ursache	Lösung
Nicht authentifiziert	Dem bestätigten Integrationsweg fehlt ein gültiger Benutzerzugang.	Lassen Sie Sitzung und Integrationskonfiguration durch die Administration prüfen; verwenden Sie keinen technischen Ersatzweg.
Die Integration wird wegen der Modulfreigabe abgelehnt.	Der Benutzer hat für die aktuelle Organisationseinheit kein zulässiges Transportmodul oder die Lizenzprüfung sperrt den Zugriff.	Prüfen Sie aktive Organisationseinheit, Modulzugriff und Lizenzkonfiguration mit der Administration.
Die Adresssuche wird nicht angenommen.	Der technische Suchbegriff ist zu kurz oder die angeforderte Treffermenge liegt außerhalb des unterstützten Bereichs.	Geben Sie die Beobachtung an das Integrationsteam; aus dieser Seite folgt kein eigener technischer Aufruf.
Die Suche liefert eine leere Liste.	Für den Suchbegriff wurde kein Treffer geliefert.	Erfassen Sie die Angaben manuell und melden Sie den fehlenden Treffer bei Bedarf an das Integrationsteam.
Die Rückauflösung liefert kein Ergebnis.	Nominatim war nicht erreichbar, lieferte keine verwertbare Antwort oder die Koordinaten konnten nicht aufgelöst werden.	Erfassen Sie die Adresse manuell und lassen Sie Providerstatus sowie Koordinaten durch das Integrationsteam prüfen.
Die Suche schlägt mit einem technischen Fehler fehl oder dauert auffällig lange.	Die externe Verbindung oder der Provider ist gestört; der Dienstaufruf hat ein Zeitlimit.	Erfassen Sie die Adresse bei Bedarf manuell und lassen Sie Provider- und Netzfreigabe durch Administration oder Integrationsteam prüfen.
In der Oberfläche ist keine Adresssuche sichtbar.	Für die vorhandene Integrationsfunktion ist kein eingebundener UI-Einstieg belegt.	Verwenden Sie keine Annahme über einen Menüpfad; lassen Sie den vorgesehenen Produkt- oder Integrationsablauf bestätigen.