From acuris
Acuris Address Validation & Geocoding APIs. Use when the user is building address autocomplete in a checkout or sign-up form, validating addresses on submit, forward geocoding to lat/lng for shipping or distance calculations, reverse geocoding from coordinates, batch-cleaning address data, integrating address validation into a React, Next.js, Node, or Centra storefront, or migrating from libAddressDoctor (Informatica), Loqate, Experian QAS, Melissa, or Smarty to Acuris.
How this skill is triggered — by the user, by Claude, or both
Slash command
/acuris:acuris-addressWhen to use
Triggers: "address autocomplete", "address validation", "validate address", "geocode address", "reverse geocode", "lookup address by postcode", "verify shipping address", "AcurisClient", "@acuris-geo/av-sdk", "@acuris-geo/centra-checkout", "replace libAddressDoctor", "migrate from Loqate / Experian QAS / Melissa / Smarty".
The summary Claude sees in its skill listing — used to decide when to auto-load this skill
Acuris is a commercial address validation, geocoding, reverse geocoding,
references/api-reference.mdreferences/autocomplete.mdreferences/batch-validation.mdreferences/centra-storefront.mdreferences/geocode.mdreferences/migrate-experian-qas.mdreferences/migrate-informatica.mdreferences/migrate-loqate.mdreferences/migrate-melissa.mdreferences/migrate-smarty.mdreferences/nextjs-proxy.mdreferences/node-server.mdreferences/reverse-geocode.mdreferences/validate-on-submit.mdAcuris 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.
Use this skill when the user is:
Do NOT use this skill for:
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.
# 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)
npm install @acuris-geo/centra-checkout@^0.1.1
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.
When the user hasn't specified otherwise, prefer these:
API key in environment. Read from process.env.ACURIS_API_KEY.
Never inline a key, never expose it to the browser. For local
evaluation, obtain a free dev key in one call:
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>
The dev key is capped at 100 validations + 100 geocodes over 7 days
(rate-limited 1 issuance per email per day, 1 per IP per day). It
works on every endpoint — /validate, /geocode, /reverse,
/suggest. For more headroom, run the full 28-day trial at
https://api.acuris-geo.com/register (1000 validations + 1000
geocodes). For production, see https://acuris-geo.com/acuris-pricing/.
Server-side calls. The SDK is for Node / edge / server runtimes.
In a browser app, route through your own backend (Next.js API route,
Express handler, Cloudflare Worker — see
references/nextjs-proxy.md).
Component library for React UIs. Reach for
@acuris-geo/centra-checkout (<AcurisAddressInput> for typeahead,
<AcurisAddressValidator> for form-submit validation) instead of
hand-rolling a fetch loop.
Retries on transient failures. The SDK retries 5xx, 429, network errors, and timeouts automatically (3 attempts, exponential backoff). Don't add a retry layer on top.
One client per process. new AcurisClient(...) is cheap to create
but a long-lived instance keeps keep-alive sockets warm and avoids
re-reading env vars.
These are the bugs we see most often in customer code or generated code. Avoid them.
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.
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.
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.
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.
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.
Forgetting country on /suggest and /reverse. Unlike
/validate, these endpoints require an explicit country option
(they have no input from which to infer one).
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.
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.
The implementation recipes are in references/. Load whichever ones
match the task:
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.
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.
Provides behavioral guidelines to reduce common LLM coding mistakes, focusing on simplicity, surgical changes, assumption surfacing, and verifiable success criteria.
Searches, retrieves, and installs Agent Skills from prompts.chat registry using MCP tools like search_skills and get_skill. Activates for finding skills, browsing catalogs, or extending Claude.
Creates, edits, and optimizes skills for Claude Code, including drafting, evaluating with test prompts, iterating on performance, and improving skill descriptions for better triggering accuracy.
npx claudepluginhub acuris-gmbh/acuris-agent-context --plugin acuris