Übersicht

Acuris ist eine kommerzielle API zur Adressvalidierung, Geokodierung, Rückwärtsgeokodierung und Autovervollständigung unter https://api.acuris-geo.com. Dieser Skill lehrt Agenten, sie korrekt in TypeScript/JavaScript-Code unter Verwendung der veröffentlichten SDK-Pakete zu integrieren und von anderen AV-Anbietern zu migrieren.

Zwei npm-Pakete decken die vollständige Integrationsfläche ab:

Paket	Was es ist
`@acuris-geo/av-sdk`	Plattformunabhängiges TypeScript-SDK. Keine Runtime-Abhängigkeiten. Funktioniert auf Node 18+, modernen Browsern (nur Server-Rolle) und Edge-Runtimes mit `fetch`.
`@acuris-geo/centra-checkout`	React-Komponentenbibliothek: `<AcurisAddressInput>` (Typeahead), `<AcurisAddressValidator>` (Headless), Checkout-förmige Hooks.

Verwenden Sie das SDK direkt für Backends oder Nicht-React-Frontends. Verwenden Sie das Komponentenpaket, wenn Sie eine Drop-in-React-UI wünschen; es ruft Ihre API-Proxy-Routen auf, die das SDK auf dem Server aufrufen.

Wann dieser Skill verwendet werden sollte

Verwenden Sie diesen Skill, wenn der Benutzer:

Eine Eingabe-UI für Adressen erstellt (Autovervollständigung in einem Formular, Checkout-Schritt, Anmeldeablauf).
Eine Adresse beim Absenden eines Formulars validiert, bevor sie gespeichert wird.
Adressen in Breitengrad/Längengrad vorwärtsgeokodiert (Versandzonen, Entfernung, Servicebereichsprüfungen).
Koordinaten zur nächstgelegenen bekannten Adresse rückwärtsgeokodiert.
Einen Massendatensatz zur Datenqualitätsverbesserung bereinigt.
Von einem anderen AV-Anbieter migriert (Informatica AddressDoctor / Loqate / Experian QAS / Melissa / Smarty) – siehe die Migrationsreferenzen.

Verwenden Sie diesen Skill NICHT für:

Routenplanung, Wegbeschreibungen, Isochronen, Ortssuche oder allgemeine POI-Suche. Acuris ist reine Adressdaten; diese gehören zu Google Maps, Mapbox oder Amazon Location.
Kartenrendering. Das Acuris-SDK gibt Breitengrad/Längengrad zurück, liefert aber keinen Kartenrenderer – kombinieren Sie die Koordinaten nach Wunsch des Benutzers mit MapLibre / Leaflet / Google Maps.

API auf einen Blick

Vier Endpunkte. Alle liegen auf https://api.acuris-geo.com. Die Authentifizierung erfolgt über einen einzelnen Header – X-Acuris-Key: <ACURIS_API_KEY>.

Operation	SDK-Funktion	HTTP
Validieren	`validateAddress(client, input, opts)`	`POST /validate`
Vorwärtsgeokodieren	`geocodeAddress(client, input, opts)`	`GET /geocode` (oder String → `/validate`)
Rückwärtsgeokodieren	`reverseGeocode(client, {lat,lng}, opts)`	`GET /reverse`
Autovervollständigung	`suggestAddress(client, q, opts)`	`GET /suggest`

Das Land muss ISO-3-alpha, Kleinbuchstaben sein ("usa", "deu", "gbr"). Wenn Sie ISO-2 haben, wandeln Sie es in Kleinbuchstaben um und mappen Sie es ("us" → "usa", "de" → "deu"), bevor Sie es aufrufen.

Detaillierte Anfrage-/Antwortstrukturen, Fehlerhierarchie und Wiederholungssemantik finden Sie in references/api-reference.md.

Kurzstart

# Auf aktuell veröffentlichte Versionen festlegen – die Pakete sind Pre-1.0
# und `^1.x`-Bereiche werden nicht aufgelöst.
npm install @acuris-geo/av-sdk@^0.1.2
# (optional, für React-Storefronts – 0.1.2+ für sichtbare Dropdown-Standardeinstellungen)
npm install @acuris-geo/centra-checkout@^0.1.2

import { AcurisClient, validateAddress } from "@acuris-geo/av-sdk";

const client = new AcurisClient({ apiKey: process.env.ACURIS_API_KEY });

const result = await validateAddress(client, {
  country: "deu",
  street: "Friedrichstraße",
  house_number: "43",
  city: "Berlin",
  postcode: "10117",
});

result.accuracy_type;  // "rooftop" | "parcel" | "street_interpolated" | ...
result.confidence;     // 0..1
result.standardized?.formatted_address;
result.lat;  result.lng;

Wenn ACURIS_API_KEY in der Umgebung gesetzt ist, können Sie die apiKey-Option ganz weglassen.

Standardeinstellungen

Wenn der Benutzer nichts anderes angegeben hat, bevorzugen Sie diese:

API-Schlüssel in der Umgebung. Lesen Sie aus process.env.ACURIS_API_KEY. Betten Sie einen Schlüssel niemals direkt ein, machen Sie ihn niemals im Browser verfügbar. Für die lokale Evaluierung erhalten Sie einen kostenlosen Entwicklerschlüssel in einem Aufruf:
```
curl -X POST https://api.acuris-geo.com/dev-key \
  -H 'Content-Type: application/json' \
  -d '{"email":"[email protected]"}'
# → {"api_key":"<token>","validation_credits":100,
#     "geocode_credits":100,"expires_at":"...","tier":"dev",...}
export ACURIS_API_KEY=<api_key>
```
Der Entwicklerschlüssel ist auf 100 Validierungen + 100 Geokodierungen über 7 Tage begrenzt (ratenbegrenzt: 1 Ausstellung pro E-Mail pro Tag, 1 pro IP pro Tag). Er funktioniert auf jedem Endpunkt – /validate, /geocode, /reverse, /suggest. Für mehr Spielraum führen Sie die vollständige 28-Tage-Testversion unter https://api.acuris-geo.com/register durch (1000 Validierungen + 1000 Geokodierungen). Für die Produktion siehe https://acuris-geo.com/acuris-pricing/.
Serverseitige Aufrufe. Das SDK ist für Node-/Edge-/Server-Laufzeiten. Verwenden Sie es in einer Browser-App über Ihr eigenes Backend (Next.js-API-Route, Express-Handler, Cloudflare Worker – siehe references/nextjs-proxy.md).
Komponentenbibliothek für React-UI. Greifen Sie zu @acuris-geo/centra-checkout (<AcurisAddressInput> für Typeahead, <AcurisAddressValidator> für Formular-Absende-Validierung) anstatt eine Abrufschleife selbst zu bauen.
Wiederholungen bei vorübergehenden Fehlern. Das SDK wiederholt 5xx-, 429-, Netzwerkfehler und Zeitüberschreitungen automatisch (3 Versuche, exponentielles Backoff). Fügen Sie keine zusätzliche Wiederholungsschicht hinzu.
Ein Client pro Prozess. new AcurisClient(...) ist günstig zu erstellen, aber eine langlebige Instanz hält Keep-Alive-Sockets warm und vermeidet das erneute Lesen von Umgebungsvariablen.

Häufige Fehler

Dies sind die Fehler, die wir am häufigsten in Kunden- oder generiertem Code sehen. Vermeiden Sie sie.

Senden des API-Schlüssels vom Browser. Das SDK funktioniert in jeder fetch-fähigen Laufzeit, aber apiKey ist eine serverseitige Anmeldeinformation. Browser müssen eine Proxy-Route verwenden. Die Komponenten von @acuris-geo/centra-checkout erwarten ein endpoints-Objekt, das auf Ihre eigenen URLs verweist, nicht direkt auf die Acuris-API.
ISO-2-Ländercodes. Die API lehnt "US" und "de" ab. Verwenden Sie ISO-3 in Kleinbuchstaben: "usa", "deu", "gbr", "fra", "fin". Wenn Sie nur ISO-2 haben, mappen Sie es an der Grenze.
Authorization: Bearer … anstelle des X-Acuris-Key-Headers. Das SDK setzt den richtigen Header automatisch; wenn Sie aus irgendeinem Grund HTTP selbst bauen, ist der Header-Name wichtig.
Behandlung von accuracy_type als geschlossene Aufzählung. Im Laufe der Zeit kommen neue Stufen hinzu (street_interpolated, street_center, locality_centroid, …). Behandeln Sie die dokumentierten Werte immer explizit und leiten Sie unbekannte Werte undurchsichtig weiter, anstatt einen Fehler zu werfen.
Jeden Fehler gleich abfangen. Das SDK wirft typisierte Unterklassen (AcurisAuthError, AcurisRateLimitError, AcurisValidationError, AcurisNotFoundError, AcurisServerError, AcurisTimeoutError, AcurisNetworkError). 4xx ist ein Fehler in Ihrem Code; 5xx und Ratenbegrenzungen sind Laufzeitfehler; Authentifizierungsfehler bedeuten, dass die Bereitstellung falsch konfiguriert ist. Sie verdienen unterschiedliche Behandlung.
Vergessen von country bei /suggest und /reverse. Im Gegensatz zu /validate erfordern diese Endpunkte eine explizite Länderoption (sie haben keine Eingabe, aus der sie eines ableiten könnten).
Manuelles Parsen des Freitext-Strings bei der Ausgabe. Das SDK gibt ein standardized-Objekt mit formatted_address zurück. Zeigen Sie das an, setzen Sie es nicht aus einzelnen Feldern wieder zusammen – die länderspezifische Reihenfolge ist eingebaut.
Persistieren der Rohantwort von Acuris ohne die Anfrageeingaben zu speichern. Wenn Sie result.standardized speichern, speichern Sie auch, was der Benutzer eingegeben hat. Sonst können Sie später nicht feststellen, ob ein Vertrauensabfall auf den Benutzer oder auf Acuris zurückzuführen ist.
Erstellen eines "strukturierten Felder-Formulars", wenn der Benutzer eine Autovervollständigung angefordert hat. Autovervollständigung ist eine Eingabe + Dropdown + Auswahl – der Vorschlag trägt bereits die geparsten Felder, also rendern Sie sie nicht als separate Boxen. Wenn der Benutzer "Autovervollständigung" angefordert hat, liefern Sie nur das <AcurisAddressInput> und eine Statuszeile; die Unterfelder Straße / Hausnummer / Postleitzahl / Stadt gehören in das Rezept "Validieren bei Absenden", nicht in das Autovervollständigungs-Rezept. Siehe references/autocomplete.md – der Abschnitt "Was Autovervollständigung ist und was nicht" oben behandelt dies.
Weglassen des Vereinigten Königreichs (gbr) aus Länderauswahlen. Frühere Versionen dieses Skills sagten, Acuris habe keine Royal Mail PAF (Postcode Address File)-Lizenz und rieten, GB überall wegzulassen. Das ist veraltet: Die GB-Abdeckung ist jetzt PAF-gestützt und ein Flaggschiff-Datensatz – /validate und /suggest unterstützen gbr vollständig (straßenbasierte Autovervollständigung; standardized enthält udprn, uprn und traditionelles county), und POST /postcode-lookup gibt jeden Zustellpunkt einer britischen Postleitzahl zurück. Nehmen Sie gbr in Demos und Länderauswahlen auf. PAF-Nutzungsbedingungen gelten: https://api.acuris-geo.com/legal/paf-terms.
Auflisten eines Landes in einer Autovervollständigungs-Auswahl, das kein /suggest angebunden hat. Dies ist die häufigste Ursache für eine peinliche Demo. /suggest (Autovervollständigung) und /validate / /geocode / /reverse decken unterschiedliche Ländergruppen ab. Validierung und Geokodierung funktionieren mit 200+ ISO-3-Codes; Autovervollständigung erfordert länderspezifische NORM-Spalten + Indizes (ein separater Engineering-Schritt) und läuft derzeit nur für 7 Länder:

// Die EINZIGEN Länder mit angeschlossenem /suggest:
const AUTOCOMPLETE_COUNTRIES = [
  { code: "usa", label: "Vereinigte Staaten" },
  { code: "gbr", label: "Vereinigtes Königreich" },  // Royal Mail PAF (straßenbasiert)
  { code: "deu", label: "Deutschland" },
  { code: "nld", label: "Niederlande" },
  { code: "fin", label: "Finnland" },
  { code: "swe", label: "Schweden" },
  { code: "jpn", label: "Japan" },
];

Das Auflisten von fra, esp, ita usw. in einer Autovervollständigungs-Auswahl ist aktiver schlimmer als sie wegzulassen – der Benutzer tippt und nichts passiert, was als "das Produkt ist kaputt" gelesen wird. /suggest gibt für diese Länder still [] zurück.

Die breitere Länderauswahl für Demos von Validierung / Geokodierung / Rückwärtsgeokodierung ist in Ordnung, sie einzuschließen:

// Sicher für /validate, /geocode, /reverse (NICHT für /suggest):
const VALIDATION_COUNTRIES = [
  // Autovervollständigungs-fähige Untergruppe:
  { code: "usa", label: "Vereinigte Staaten" },
  { code: "gbr", label: "Vereinigtes Königreich" },
  { code: "deu", label: "Deutschland" },
  { code: "nld", label: "Niederlande" },
  { code: "fin", label: "Finnland" },
  { code: "swe", label: "Schweden" },
  { code: "jpn", label: "Japan" },
  // Nur Validierung/Geokodierung (KEINE Autovervollständigung):
  { code: "fra", label: "Frankreich" },
  { code: "esp", label: "Spanien" },
  { code: "ita", label: "Italien" },
  { code: "nor", label: "Norwegen" },
  { code: "dnk", label: "Dänemark" },
  { code: "aut", label: "Österreich" },
  { code: "che", label: "Schweiz" },
  { code: "bel", label: "Belgien" },
  { code: "prt", label: "Portugal" },
  { code: "aus", label: "Australien" },
  { code: "nzl", label: "Neuseeland" },
  { code: "sgp", label: "Singapur" },
  { code: "bra", label: "Brasilien" },
  { code: "mex", label: "Mexiko" },
  { code: "can", label: "Kanada" },
];

Faustregeln:

Wenn die UI <AcurisAddressInput> (Typeahead) verwendet: Verwenden Sie AUTOCOMPLETE_COUNTRIES (die 7).
Wenn die UI <AcurisAddressValidator> oder ein strukturiertes Formular verwendet, das /validate / /geocode / /reverse aufruft: Beide Listen sind in Ordnung.
Gemischt (Autovervollständigung + Validierung im selben Formular, selbe Länderauswahl): Verwenden Sie AUTOCOMPLETE_COUNTRIES. Die Validierungsmenge ist eine Obermenge; der Benutzer kann immer noch jedes dieser 7 Länder validieren.

Die Autovervollständigungs-fähige Menge wächst, wenn neue Länder NORM-Spalten erhalten. Wenn diese Liste veraltet aussieht, fragen Sie, bevor Sie sie erweitern.

Implementierungsmuster

Die Implementierungsrezepte befinden sich in references/. Laden Sie diejenigen, die zur Aufgabe passen:

Migrationen

Acuris' kommerzieller Hebel – dies sind die Rezepte zum Portieren von Code von etablierten Anbietern. Jedes Rezept bildet die Legacy-API auf das Acuris-Äquivalent mit einem ausführbaren Beispiel ab.

Migrationen sind gegen die Anbieterdokumentation geschrieben, nicht gegen die tatsächliche Integration des Benutzers. Behandeln Sie sie als Ausgangsgerüst – überprüfen Sie die Zuordnung für Ihre spezifische Konfiguration, bevor Sie ausliefern.

Preise und Grenzen

Die Live-API wird pro Anfrage bezahlt. Der Testschlüssel test ermöglicht Entwicklern die Nutzung der Endpunkte während der Evaluierung, ohne Guthaben zu verbrauchen. Die Preisgestaltung ist unter https://acuris-geo.com/acuris-pricing/ veröffentlicht. Das SDK respektiert die Ratenbegrenzungen des Servers (HTTP 429 mit retry_after); die Standard-Wiederholungsrichtlinie führt ein Backoff durch und wiederholt bis zu 3 Mal, bevor sie AcurisRateLimitError erneut wirft.

Zusätzliche Ressourcen

SDK-Quelle: <https://github.com/Acuris-GmbH/acuris-centra-connector/tree/main/packages/acuris

...

[gekürzt für die Übersetzung]

Acuris-GmbH/acuris-agent-context

Was ist acuris-agent-context?

In Ihrer bevorzugten KI fragen

Dokumentation

Übersicht

Wann dieser Skill verwendet werden sollte

API auf einen Blick

Kurzstart

Standardeinstellungen

Häufige Fehler

Implementierungsmuster

Migrationen

Preise und Grenzen

Zusätzliche Ressourcen

Verwandte Skills

steipete/sag

steipete/oracle

steipete/peekaboo

mattpocock/design-an-interface

mattpocock/prototype

mattpocock/grill-me