Autocomplete/typeahead. Returns ranked standardized addresses (with formatted_address, and lat/lng whenever the reference row carries a coordinate — never invented) for the partial input q (or prefix) and country.

Authentication is required — there is no anonymous access. A caller must present either:

• a paid API key (Stripe X-Acuris-Key / Authorization: Bearer, X-API-Key, or RapidAPI gateway) — full access, billed against the key's own transaction pool; or
• a short-lived widget token (X-Acuris-Widget-Token header, or ?t=) minted by /widget/token — origin-locked to acuris-geo.com pages, so not usable by third-party integrations (partners use API keys). Widget callers are capped at 15 results and a per-token call quota.

Requests with neither are rejected: 403 (no widget origin / no token) or 401 (token invalid, expired, or quota exhausted).

Metering here depends on the AV_GEO_REQUIRE_SIGNUP launch flag (see Free tier (verified account) above for the full explanation — this endpoint never draws from the UK daily cap described there, on either side of the flag, and draws from the 1,000/day free-tier allowance only once the flag is on):

• As of this writing, flag off in production: a genuinely valid API key is completely exempt from metering. Anonymous widget-token callers are bounded only by a per-IP flask-limiter soft cap of 5/second, 60/minute, 500/day (per gunicorn worker — a first-line burst backstop, not an authoritative cross-fleet limit); the handler does not authenticate against a quota pool or decrement one in this state.
• Once the flag is on: a registered key (any class except the policy-exempt stripe/integration/partner) draws from the same shared recurring 1,000/day allowance as /validate//geocode//reverse (free_limit_reached, 403, once exhausted); anonymous callers are capped at 40/day per IP instead (rate_limit_exceeded, 429, once exhausted), and the flask-limiter decorator's daily figure drops from 500 to 40 at the same moment as a redundant first-line backstop. country: "gbr" requests carry one further, independent per-IP velocity cap (PAF_SUGGEST_IP_RPM, 600/minute by default — 10x that for a genuinely valid, non-test API key; allowlisted keys exempt), which degrades to an empty result set ({"suggestions": [], "limit": "reached"}) rather than an error, on either side of the flag.

UK note: country: "gbr" is served exclusively from https://paf.acuris-geo.com (identical path, parameters, and auth). Requests for gbr sent to api.acuris-geo.com return 400 {"error": "country_not_served_by_this_endpoint", "country": "gbr", "use_instead": "https://paf.acuris-geo.com"}.

Postcode-first input: the query may lead with (or be) a postal code. GBR: a full or partial postcode returns every delivery point at that postcode, each labelled with building_name / organisation_name / department; a premise name may precede the postcode (Gate House DL12 0NQ). DEU / FIN / SWE / NLD / CAN: a leading postcode scopes the street search (67549 Eckenbert, M5V 3L9). JPN: a postcode returns chōme suggestions; then pass zip, oaza, chome with the house-number keystrokes to get banchi-gō lot suggestions.

Suggestions do not carry udprn / uprn / county. To obtain the Royal Mail / OS identifiers for a chosen suggestion, submit it to /validate (returns uprn, udprn) or use /postcode-lookup.

Suggestion lat/lng are the reference row's own point, unrefined. /validate may refine that point for the same address (France: a point lying just outside its building is moved onto the building footprint, by at most 8 m, and the response carries coord_snapped: true). List rows never carry that refinement; for the refined point, submit the chosen suggestion to /validate.

Typeahead is tuned and verified for 19 countries today — GBR, USA, CAN, DEU, AUT, CHE, FRA, BEL, NLD, LUX, DNK, SWE, FIN, IRL, PRT, ESP, SGP, JPN, HKG. Any /geocode country code is accepted; countries outside this set may return empty results.