Address Autocomplete quickstart

The flow is two calls: predict while the user types, resolve when they pick one. Run it against Mock first, which needs no credentials, then repeat it on sandbox with your bearer token.

1. Against Mock

Mock data: invented addresses only. Your own address will not be found. Inputs that work: Haupt, Bahnhofstr 12 Wien, Schulg, 1010, Gartenweg München, Strasse Muenchen. A request that matches nothing returns an empty suggestions list, not an error.

Mock holds German and Austrian sample addresses only. That is the size of the sample, not the coverage of the service, which is international and configured per deployment. Mock lives on this portal, under /mock/api/services. Set MOCK to the address of the site you are reading this on:

MOCK="https://<this portal>/mock/api/services"

Predict. Send what the user has typed so far, in the field input:

curl -s "$MOCK/address/autocomplete/predict" \
  -H "Content-Type: application/json" \
  -d '{"input": "Hauptstr 12 Graz", "countries": ["AT"]}'

{
  "session": "5d41402abc4b2a76b9719d911017c592",
  "suggestions": [
    {
      "id": "mock:at-2421:12",
      "text": "Hauptstraße 12, 8010 Graz, Österreich",
      "main_text": "Hauptstraße 12",
      "secondary_text": "8010 Graz, Österreich"
    }
  ],
  "attribution": ""
}

Type more, or less, and the list follows: Haupt returns five suggestions spread over different cities (Hauptstraße, Hauptplatz, Hauptgasse and so on), Haupt Graz the Haupt streets of Graz, Hauptplatz Graz one. Send the returned session back on the next call:

curl -s "$MOCK/address/autocomplete/predict" \
  -H "Content-Type: application/json" \
  -d '{"input": "Hauptplatz Graz", "session": "5d41402abc4b2a76b9719d911017c592"}'

Resolve. Send the chosen suggestion's id and the session:

curl -s "$MOCK/address/autocomplete/resolve" \
  -H "Content-Type: application/json" \
  -d '{"id": "mock:at-2421:12", "session": "5d41402abc4b2a76b9719d911017c592"}'

{
  "address": {
    "formatted": "Hauptstraße 12, 8010 Graz, Österreich",
    "street": "Hauptstraße",
    "house_number": "12",
    "postal_code": "8010",
    "city": "Graz",
    "district": "",
    "state": "Steiermark",
    "country": "Österreich",
    "country_code": "AT",
    "lat": 47.07,
    "lng": 15.443,
    "precision": "house"
  },
  "verification": null
}

precision is house because the typed text carried a house number. Pick a suggestion without one and it is street. In the reference, choose the server Mock and use Send request for the same two calls.

What Mock does and does not do is listed in the integration guide.

2. On sandbox

You need Umbrella credentials and a bearer token from POST /auth, see Authentication. The base URL is the Umbrella sandbox URL from Environments, written BASE_URL here. The operations sit under /address/autocomplete. Pending verification: that gateway sub-path is not yet confirmed.

curl -s "$BASE_URL/address/autocomplete/predict" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"input": "Hauptstr 12 Graz", "countries": ["AT"]}'

curl -s "$BASE_URL/address/autocomplete/resolve" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"id": "<id from a suggestion>", "session": "<session from predict>"}'

Show attribution next to the suggestions whenever it is not empty (Mock always returns it empty). Real id values are opaque and look different from the Mock ones; never build or parse them.

Verification status

Request and response shapes follow the service source. Values on sandbox have not been compared with a live call. Pending verification.

Next

• Integration guide: client rules, errors, privacy, accessibility and a minimal client.
• Widget: skip the client code.
• Reference: every field.