acuris-geo-com Versioned aliases (v1) API

openapi: 3.2.0
info:
  title: Acuris Geo Versioned aliases (v1) API
  description: 'REST API for **address validation**, **geocoding**, and **address suggestions**

    across supported countries (see **Country codes** below). **AI agents / MCP:** the same capabilities are exposed as self-describing MCP

    tools at `https://api.acuris-geo.com/mcp` (streamable HTTP; authenticate with

    `Authorization: Bearer `). See /docs/mcp. ### Authentication

    Present your API key using any of the following (listed in priority order):

    - **`X-Acuris-Key: `** header — preferred for keys issued via Stripe Checkout. - **`Authorization: Bearer `** header — standard OAuth-style bearer; works for any key. - **`X-API-Key: `** header. - **`?key=`** query parameter (legacy). - **`{"key": "..."}`** JSON body field on `POST /validate` (legacy). Header auth is preferred: query-param secrets can leak into access logs, Referer

    headers, and browser history. A `password` parameter is **not** an API-key

    channel anywhere (query or body) — it is reserved for account login. Without a key, **anonymous free tier** access is rate-limited per IP, and per-product

    daily free limits apply. Check remaining free calls via `/validate-credits` and

    `/geocode-credits`; see the pricing page at https://www.acuris-geo.com/acuris-pricing/ for details. **This anonymous path is being retired for validate/geocode/reverse/postcode-lookup in favor of

    requiring a free account** — see **Free tier (verified account)** below for the allowance you get

    once you sign up, and the forthcoming anonymous-access change. ### Versioned namespace (`/v1/*`)

    A stable, versioned `/v1/*` namespace mirrors the core endpoints (e.g. `/v1/validate`,

    `/v1/validate/batch`, `/v1/geocode`, `/v1/reverse`). Behavior is identical to the unversioned

    routes; prefer `/v1/*` for long-lived integrations. Details are documented on the individual

    path items. #### RapidAPI

    When consumed via the RapidAPI marketplace, the RapidAPI gateway is the identity

    provider: it injects `X-RapidAPI-Proxy-Secret` (a shared secret verified server-side),

    `X-RapidAPI-Key`, `X-RapidAPI-User`, and `X-RapidAPI-Subscription` on every request. Plan quotas are enforced upstream by RapidAPI; no Acuris account or transaction balance is required

    for traffic routed through RapidAPI. Direct (non-RapidAPI) calls continue to use the

    authentication methods above. ### Country codes (validation & geocode `country`)

    We hold reference databases for **~250 countries**, roughly **130** of them

    with house-number-level data, and a street-segment interpolation cascade

    live in **~95 countries**. Full multi-tier precision (an address-level

    reference DB plus the street-segment cascade) covers a flagship set

    including `usa`, `can`, `gbr`, `deu`, `aut`, `che`, `fra`, `esp`, `bel`,

    `nld`, `dnk`, `fin`, `swe`, `nor`, `ita`, `jpn`, `sgp`, among others. The United Kingdom is served at full Royal Mail PAF precision (UPRN / UDPRN)

    on its dedicated host — see **United Kingdom host** below. Belgium is fully

    trilingual (NL / FR / DE). The **acceptance set is far larger than the full-precision tier**: any country in the

    `COUNTRY_GEOCODE` table validates (~223 live today, and growing), returning the

    best tier its reference data supports — from a point coordinate down to an

    admin-area centroid. Inspect `accuracy_type` in each response to see which tier was returned for a

    given lookup. Additional countries are being onboarded — see the roadmap on

    acuris-geo.com. ### United Kingdom host

    All `country=gbr` traffic — `/validate`, `/suggest`, `/reverse`, and the

    UK-only endpoints `/postcode-lookup` and `/geocode-uk` — is served from

    **https://paf.acuris-geo.com** (see Servers). A `gbr` request sent to the

    main host is refused rather than silently degraded: it returns **400**

    `{"error": "country_not_served_by_this_endpoint", "use_instead": "https://paf.acuris-geo.com"}`.'
  version: 1.9.6
  x-last-updated: '2026-10-28'
  x-changelog: 'One free evaluation key for every caller (2026-10-28, additive): POST /dev-key now mints the same free evaluation key a registered account gets (1,000 lookups shared by validation and geocoding plus 50 UK lookups, valid 30 days) for every caller, instead of 100 validations + 100 geocodes for 7 days; DevKeyResponse documents trial_days, trial_model, shared_pool and uk_evaluation_total. No field removed. Prior entry: UK evaluation parity (2026-10-23, additive): a free evaluation key gets 50 UK (Royal Mail PAF) lookups in total inside its 30-day evaluation instead of 5 per UTC day; the UK refusal is 403 uk_evaluation_ended with an uk_evaluation object (used, total, remaining, days, started_at, ends_at); uk_trial on /check-key and /account/balances reports cap 50 for such keys. The Excel add-in instant key is now a free evaluation key. No field removed. Prior entry: Free evaluation replaces the daily free allowance (2026-10-23, additive): a verified free_av_geo key now has ONE allowance of 1,000 lookups valid 30 days with no daily limit; /check-key and the balance endpoints gain trial_model and an evaluation object; metered endpoints answer 402 evaluation_ended when it is used up (/suggest: limit reached + evaluation_ended true); free_daily_limit stays 1000 for compatibility; the attribution requirement is dropped; anonymous signup_required 403 documented as live. No field removed. Prior entry: United States /validate time limit (2026-10-22, additive): search_budget_exhausted is no longer 404-only; a United States 200 answer whose search was cut short by a per-call time limit carries it in reasons, and ValidateResponse and ValidateErrorBody document the boolean truncated. No field removed, no code or status changed. Prior entry: UK PAF evaluation terms (2026-10-11, additive): /dev-key accepts accept_terms (boolean) and may return 400 terms_acceptance_required when terms acceptance is enforced; its response may carry uk_evaluation_expires_at; /check-key gains a uk_eval block (mode, accepted_at, uk_eval_expires_at, days_remaining); UK lookups on free keys may be refused with 403 uk_terms_acceptance_required or uk_evaluation_expired. Prior entry: Daily-cap reset info (2026-10-08, additive): free_limit_reached and uk_trial_cap_reached 403 bodies gain resets_at and retry_after_seconds plus a Retry-After header, and their message now says when the daily allowance resets (UTC, UK and Germany time). The UK free cap is documented as 5/day registered, 3/day anonymous (was 40/day). No field removed, no code or status changed. Prior entry: Netherlands postcode + house number (2026-10-07, additive, NLD only): /validate accepts postcode + house_number with no street and no city; postcode spellings 3999NN / 3999 nn are accepted; FailureReason gains postcode_house_number_ambiguous and house_number_extension_missing; ValidateResponse documents city_backfilled_from_postcode and gains street_backfilled_from_postcode; ValidateErrorBody did_you_mean entries gain house_number (NLD). Prior entry: Free-tier allowance doc fix (2026-10-01, docs only, no API change): the verified-account (free_av_geo) daily allowance has been 1,000 per UTC day since 2026-09-28, not 3,000, and it is ONE shared bucket for validate, geocode, reverse and (once the signup flag is on) suggest, not one bucket per product. Corrected the Free tier prose, the /suggest metering prose, free_daily_limit (example and "Always 1000") on /check-key and ForwardGeocodeResponse, and the /check-key free_remaining schema, which the server returns as a single integer, not a {validate, geocode} object. Prior entry: Portugal explanations (2026-10-01, additive, PRT only): FailureReason gains city_not_found, city_missing, street_found_in_multiple_localities, street_type_mismatch, street_particle_mismatch, street_spelling_mismatch, locality_ambiguous, street_missing, fell_back_to_locality, house_number_not_in_reference, house_number_missing (city_missing and street_found_in_multiple_localities were already emitted for some other countries and are now documented). ForwardGeocodeErrorBody gains optional reasons, did_you_mean, did_you_mean_truncated (PRT); ValidateErrorBody did_you_mean documents the PRT entry fields (municipality, district, doors, match) and gains did_you_mean_truncated. ValidateResponse and ForwardGeocodeResponse gain optional nearby_house_numbers, approximate, resolved_level, resolved_name (ForwardGeocodeResponse also reasons, PRT only). New component schemas NearbyHouseNumbers, NearbyHouseNumber, ResolvedLevel, DidYouMeanEntry. /geocode documents the PRT city-only labelled approximate point, the ambiguous-place 404 and the street-without-city 404. No field removed, no type changed. Prior entry: /geocode facade doc fix (2026-09-04): ForwardGeocodeResponse was missing digipin — _attach_digipin (usa-app.py) adds it to real /geocode and /v1/geocode responses whenever country=ind and ACURIS_DIGIPIN is enabled (it is, on this deployment), so the schema''s "no key outside this list ships" claim was false the moment it shipped. Added digipin (string, IND-only, present only when the feature flag is on and a coordinate resolved) to the schema and to both endpoints'' response-vocabulary prose; corrected the same omission in docs/superpowers/specs/2026-09-03-geocoding-product-design.md §2, the spec these docs derive from. No other post-projection response mutation was missed — walked the full route tail (usa-app.py ~29746 through its single `return jsonify(resp)` at ~29799) key by key. Prior entry: /geocode facade cutover (2026-09-04, ratified breaking change — pre-customer, ~139 lifetime geocode calls, essentially all internal): GET /geocode and POST /v1/geocode now run the same parse -> infer -> lookup chain as /validate, so the fielded gate ("Missing parameters. Street, City and State are required.") is gone for all 8 countries that used to hit it (aus, bra, can, jpn, mex, mys, tur, usa) — street/city/state are optional everywhere, including USA/CAN, and a single-line q= now resolves any supported country. The response is a strict geocoding-only whitelist (ForwardGeocodeResponse): lat, lng, accuracy_type, point_coordinate, standardized, formatted_address always; arrival_point, input_modified, attribution (gbr) and uprn (gbr) conditionally. No AV vocabulary (status, match_type, match_score, confidence, corrections, etc.) ships on these two routes any longer. A miss is a plain {"error": "no_match", "message": "..."} body (ForwardGeocodeErrorBody) at 404, the same shape at 422 for uninterpretable input, and a genuine engine/server failure is 503 or 500 — never a match-quality verdict with everything zeroed out. The legacy /geocode-usa and /geocode-uk shorthand routes are unchanged and still return the original AV-vocabulary shape (GeocodeResponse/GeocodeErrorBody). Prior entry: Whole-branch review fixes (2026-08-27): reconciled the two /suggest metering descriptions with the code — they previously said /suggest "is metered by neither the 3,000/day allowance nor the 40/day UK cap" and quoted a flat 500/day, which the metering commits in this same branch (2455789d, e4f047a1) had already made untrue, AND which the launch-flag fix (P0-1) then made conditional. Both /suggest sections now state the honest, flag-conditional truth: unmetered/500-per-day-soft-cap while AV_GEO_REQUIRE_SIGNUP is off (the production state as of this writing), 40/day anonymous + 3,000/day per registered key once the flag flips on. Also deleted the unbacked "Service level" block (99.9% uptime target, p95 < 500ms latency target, contractual SLA with uptime credits) — the company is pre-revenue with zero paying customers and none of that is backed by an actual agreement. Prior entry: AV/GEO free-tier relaunch: replaced the "four independent trial pools (1,000 credits / 28 days each)" description with the real model — a verified free_av_geo account now gets a recurring, non-expiring 3,000-requests-per-UTC-day allowance per product for validate/geocode/reverse, never a depleting pool. Added the explicit UK carve-out (Royal Mail PAF licensed per lookup, capped separately at 40/UTC day, never drawn from the 3,000) and stated /postcode-lookup is UK-only and therefore always under the 40/day cap, never 3,000. Split email/phone verification into their own subsection: unchanged, still 1,000 credits / 28 days each. Documented key_class, free_remaining, and free_daily_limit on /check-key; corrected uk_trial from "lifetime cap" to "per UTC day". Added the free-tier commercial-use attribution requirement and the forthcoming (not yet live in production) signup_required 403 for anonymous validate/geocode/reverse/postcode-lookup calls behind AV_GEO_REQUIRE_SIGNUP. Prior entry: Retired GET /search (now 410 gone); added the UK (PAF) server entry and country=gbr routing note; corrected coverage prose (~250 reference DBs, ~130 with house numbers, ~95 street-segment countries, flagship tier named); documented the 11-country free enrichment; removed the password auth channel (use ?key= or headers); phone verdict not_in_service + range_coverage; txn_pack_* Stripe plans; email spam-trap / domain-age fields; identity sanctions / area_deprivation additions; refreshed stale examples. Endpoint-level corrections: /validate — canonical form always in standardized (corrected key reserved), non_deliverable MatchType + 400 body, FailureReason now an open set with the live codes, reasons/suggestions on 200 partials, disclosure fields documented (unverified_fields, postcode_unverified, postcode forensics, accuracy_label, uprn_match_m), 402/403 bodies, alternative_matches marked reserved; /suggest — 19-country coverage, postcode-first input, state + lat/lng bias params, JPN two-stage zip/oaza/chome, SuggestItem schema (count, locality, UK delivery-point labels, kanji fields), hint/limit response fields, /widget/token documented; /reverse — Stripe billing is flat 1/request (per-address applies to trial keys), irl now serves reverse; /postcode-lookup — full PAF element set (post_town, address_lines, administrative_county, uprn_match_m); /geocode — city/town required in practice, q accepted on GET; /check-key — key_type, uk_trial, plan fields + 402; phone batch/match response codes completed.'
  contact:
    name: Acuris Geo Support
    email: support@acuris-geo.com
    url: https://www.acuris-geo.com/
servers:
- url: https://api.acuris-geo.com
  description: Production
- url: https://paf.acuris-geo.com
  description: United Kingdom (PAF) — all country=gbr requests are served here
security:
- acurisKeyHeader: []
- bearerAuth: []
- apiKeyHeader: []
- apiKeyQueryLegacy: []
- {}
tags:


# --- truncated at 32 KB (147 KB total) ---
# Full source: https://artifacts.apis.io/acuris-geo-com/openapi/acuris-geo-com-versioned-aliases-v1-api-openapi.yml