Address Autocomplete

Universe: Umbrella
Status: beta

As a user types an address, the service returns matching suggestions. When the user picks one, it resolves to a structured address: street, house number, postal code, city, country and coordinates. The data comes from a licensed address reference database.

How it works

user types  ->  predict  ->  up to 5 suggestions        (repeat per keystroke, same session)
user picks  ->  resolve  ->  structured address         (the session ends)

1. Your form sends what the user has typed so far to predict and gets back suggestions, each with an opaque id, plus a session value.
2. Every further keystroke goes to predict again with the same session.
3. When the user picks a suggestion, you send its id and the session to resolve and get the structured address, including how precisely it was resolved (precision).

The session is what ties the keystrokes and the final pick together as one address entry. Always pass it back: without it every call counts as its own session.

Try it without credentials

Mock holds invented addresses only, so your own address will not be found; try Haupt, Bahnhofstr 12 Wien or 1010. Mock answers predict and resolve from a fictional dataset of about 3,000 streets in German and Austrian cities, so a type-ahead field works in minutes. Mock covers Germany and Austria only; that is the size of the sample, not the coverage of the service. Start with the Quickstart, which uses Mock first. The widget demo runs the real dropdown against it.

Two ways to integrate

Both use the same backend and the same two calls. See Widget, Build your own UI and Integration guide.

Coverage and limits

• Countries: international. The address sources behind the service cover many countries, and the countries enabled for a deployment are configuration, extended on request. DE and AT are the examples used in these pages and the current default, not the scope. A country code that is not enabled for your deployment returns 422. A request can restrict results to one or more countries with countries, for example ["DE"], see Country and address type. Pending verification: the list of countries enabled on sandbox and production, and the quality of results per country.
• Address type: there is no filter for residential, commercial or mixed addresses today, and the response does not report one.
• Language: German (de) by default; set language to a BCP 47 tag to change it.
• Minimum input: 3 characters by default, a service-wide setting.
• Input: up to 200 characters. Under the minimum returns an empty list, not an error.
• Suggestions: at most 5 per call by default, a service-wide setting.
• Rate limits and quotas: pending, not yet defined.

Things to know before you build

• Sessions. The service groups one user's keystrokes and the final pick into one session. Pass the returned session back on every following call. Skipping it works, but each call is then a separate session.
• Attribution. When the response carries a non-empty attribution, you must show it next to the suggestion list. The widget does this for you.
• Precision. resolve tells you how far the address was resolved: house, street or area. A street-level pick has no house number; check precision instead of looking for empty fields.
• The data source is not part of the contract. It is chosen per country on the server and can change without any change to the API. Do not parse or depend on id values.

Status of this documentation

This service is part of Umbrella API: use the Umbrella base URLs from Environments with the Umbrella bearer token. Pages show the base URL as BASE_URL. The gateway sub-path (/address/autocomplete/...) is pending verification. Request and response samples are illustrative and have been checked against the service's offline test mode and the source code only. Pending verification against the live service.