Overview

Acuris is a commercial address validation, geocoding, reverse geocoding, and autocomplete API at https://api.acuris-geo.com. This skill teaches agents how to wire it correctly into TypeScript / JavaScript code using the published SDK packages and how to migrate from other AV vendors.

Two npm packages cover the full integration surface:

Package What it is
@acuris-geo/av-sdk Platform-agnostic TypeScript SDK. Zero runtime dependencies. Works on Node 18+, modern browsers (server-only role), edge runtimes with fetch.
@acuris-geo/centra-checkout React component library: <AcurisAddressInput> (typeahead), <AcurisAddressValidator> (headless), checkout-shaped hooks.

Use the SDK directly for backend or non-React frontends. Use the component package when you want a drop-in React UI; it calls your API proxy routes, which call the SDK on the server.

When to use this skill

Use this skill when the user is:

Do NOT use this skill for:

API at a glance

Four endpoints. All live on https://api.acuris-geo.com. Auth is a single header — X-Acuris-Key: <ACURIS_API_KEY>.

Operation SDK function HTTP
Validate validateAddress(client, input, opts) POST /validate
Forward geocode geocodeAddress(client, input, opts) GET /geocode (or string → /validate)
Reverse geocode reverseGeocode(client, {lat,lng}, opts) GET /reverse
Autocomplete suggestAddress(client, q, opts) GET /suggest

Country must be ISO-3 alpha, lowercase ("usa", "deu", "gbr"). If you have ISO-2, lowercase-it and map ("us" → "usa", "de" → "deu") before calling.

Detailed request/response shapes, error hierarchy, and retry semantics live in references/api-reference.md.

Quick start

# Pin to current published versions — the packages are pre-1.0
# and `^1.x` ranges will not resolve.
npm install @acuris-geo/av-sdk@^0.1.2
# (optional, for React storefronts — 0.1.2+ for visible dropdown defaults)
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;

If ACURIS_API_KEY is set in the environment, you can omit the apiKey option entirely.

Defaults

When the user hasn’t specified otherwise, prefer these:

Common mistakes

These are the bugs we see most often in customer code or generated code. Avoid them.

  1. Sending the API key from the browser. The SDK works in any fetch-enabled runtime, but apiKey is a server-side credential. Browsers must go through a proxy route. The @acuris-geo/centra-checkout components expect an endpoints object pointing at your own URLs, not the Acuris API directly.

  2. ISO-2 country codes. The API rejects "US" and "de". Use ISO-3 lowercase: "usa", "deu", "gbr", "fra", "fin". If you only have ISO-2, map it at the boundary.

  3. Authorization: Bearer … instead of the X-Acuris-Key header. The SDK sets the right header automatically; if you’re hand-rolling HTTP for any reason, the header name matters.

  4. Treating accuracy_type as a closed enum. New tiers are added over time (street_interpolated, street_center, locality_centroid, …). Always handle the documented values explicitly and pass through unknown values as opaque rather than throwing.

  5. Catching every error the same way. The SDK throws typed subclasses (AcurisAuthError, AcurisRateLimitError, AcurisValidationError, AcurisNotFoundError, AcurisServerError, AcurisTimeoutError, AcurisNetworkError). 4xx is your code’s bug; 5xx and rate limits are runtime; auth errors mean the deploy is misconfigured. They deserve different handling.

  6. Forgetting country on /suggest and /reverse. Unlike /validate, these endpoints require an explicit country option (they have no input from which to infer one).

  7. Hand-parsing the freeform string on the way out. The SDK returns a standardized object with formatted_address. Display that, don’t reassemble from individual fields — locale-specific ordering is baked in.

  8. Persisting Acuris’s raw response without snapshotting the request inputs. If you store result.standardized, also store what the user typed. Otherwise you can’t tell later whether a confidence drop is the user’s fault or Acuris’s.

  9. Building a “structured-fields form” when the user asked for autocomplete. Autocomplete is one input + dropdown + pick — the suggestion already carries the parsed fields, so you don’t render them as separate boxes. If the user asked for “autocomplete,” ship just the <AcurisAddressInput> and a status line; the street / house-number / postcode / city sub-fields belong in the validate-on-submit recipe, not the autocomplete one. See references/autocomplete.md — the “What autocomplete is and is not” section at the top covers this.

  10. Listing the United Kingdom (gbr) in a country picker. Acuris does not currently hold a Royal Mail PAF (Postcode Address File) licence, which is required for commercial use of UK address data. /validate and /suggest may return technically-shaped results for gbr inputs, but shipping UK in a customer-facing country picker exposes the integrator (and Acuris) to licensing liability. Until that licence is in place, omit gbr from any demo, autocomplete country list, or requested_fields country set.

  11. Listing a country in an autocomplete picker that doesn’t have /suggest wired. This is the most common source of an embarrassing demo. /suggest (autocomplete) and /validate / /geocode / /reverse cover different country sets. Validation and geocoding work against 200+ ISO-3 codes; autocomplete requires per-country NORM columns + indexes (a separate engineering step) and currently runs for only 5 countries:

   // The ONLY countries with /suggest wired (as of 0.2.2):
   const AUTOCOMPLETE_COUNTRIES = [
     { code: "usa", label: "United States" },
     { code: "deu", label: "Germany" },
     { code: "nld", label: "Netherlands" },
     { code: "fin", label: "Finland" },
     { code: "swe", label: "Sweden" },
   ];

Listing fra, esp, ita, etc. in an autocomplete picker is actively worse than omitting them — the user types and nothing happens, which reads as “the product is broken.” /suggest returns [] silently for those countries.

The broader country picker for validation / geocoding / reverse geocoding demos is fine to include them:

   // Safe for /validate, /geocode, /reverse (NOT for /suggest):
   const VALIDATION_COUNTRIES = [
     // Autocomplete-enabled subset:
     { code: "usa", label: "United States" },
     { code: "deu", label: "Germany" },
     { code: "nld", label: "Netherlands" },
     { code: "fin", label: "Finland" },
     { code: "swe", label: "Sweden" },
     // Validation/geocoding-only (NOT autocomplete):
     { code: "fra", label: "France" },
     { code: "esp", label: "Spain" },
     { code: "ita", label: "Italy" },
     { code: "nor", label: "Norway" },
     { code: "dnk", label: "Denmark" },
     { code: "aut", label: "Austria" },
     { code: "che", label: "Switzerland" },
     { code: "bel", label: "Belgium" },
     { code: "prt", label: "Portugal" },
     { code: "aus", label: "Australia" },
     { code: "nzl", label: "New Zealand" },
     { code: "jpn", label: "Japan" },
     { code: "sgp", label: "Singapore" },
     { code: "bra", label: "Brazil" },
     { code: "mex", label: "Mexico" },
     { code: "can", label: "Canada" },
   ];

Rules of thumb:

The autocomplete-enabled set grows as new countries get NORM columns. If this list looks stale, ask before extending it.

Implementation patterns

The implementation recipes are in references/. Load whichever ones match the task:

Migrations

Acuris’s commercial wedge — these are the recipes for porting code off incumbent vendors. Each recipe maps the legacy API to the Acuris equivalent with a runnable example.

Migrations are written against vendor documentation, not against the user’s actual integration. Treat them as a starting scaffold — review the mapping for your specific configuration before shipping.

Pricing and limits

The live API is paid per request. The test key test lets developers exercise endpoints during evaluation without burning credits. Pricing is published at https://acuris-geo.com/acuris-pricing/. The SDK respects the server’s rate limits (HTTP 429 with retry_after); the default retry policy backs off and retries up to 3 times before re-throwing AcurisRateLimitError.

Additional resources