Structured Autocompletion

In order to try these examples, head over to Uniserv CONNECT and create an API Key (test accounts are free!).

Introduction

Autocompletion supports address input by suggesting postal codes, localities, sub-localities, streets, and other fields while the user types. Each keystroke refines the list of suggestions further, with previously entered fields restricting the results. In a typical example, the user would first enter the postal code, which automatically fills the locality. In a second step, the user enters the street, where suggestions are already restricted by postal code and locality.

In contrast to address validation, autocompletion is designed to be integrated directly into a web page. JavaScript code reads the (partial) address from the input field and sends it to the Uniserv Autocompletion API at https://api.uniserv.com/.

Integrating with the Autocomplete API works as follows:

Start an autocomplete session
Send an autocomplete request for each keystroke
Perform an address validation (recommended)

Note that for client-side integrations like this, the session token will be exposed as part of your JavaScript code. To make sure the token cannot be used on a website other than your own, you have to whitelist your domain in Uniserv CONNECT. For example, if you serve your website at https://www.example.com/, add www.example.com to the list of permitted domains.

Starting a Session

Before completing an address you have to start a new autocomplete session. Requests to the Autocomplete API always require three HTTP headers:

Content-Type to indicate a JSON body
Authorization with your API key
Origin, which the browser sets automatically

Additionally, all request bodies need the country attribute.

POST /location/v1/start-session
Content-Type: application/json
Authorization: Bearer YOUR-API-KEY-HERE
Origin: https://example.com

{
    "country": "DE"
}

You will receive a response with a session token that you have to pass to all subsequent API calls in the Authorization header as described in the next section:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "_sessionToken": "eyJhbGciOiJIUzUxMiJ9..."
}

The token is valid for three minutes and for the country specified in the start-session request, giving a user plenty of time to finish their input. If the session expires before the input is complete, you can create a new session and resend your request.

Sending a Request

In this example, the user is entering the postal code field and has already typed the first two digits:

POST /location/v1/autocomplete
Content-Type: application/json
Authorization: Bearer YOUR-SESSION-TOKEN-HERE
Origin: https://example.com

{
    "country": "DE",
    "postalCode": "76"
}

Note the Authorization header with the session token from the previous section.

The result contains a list of candidate addresses (not very useful yet due to the limited user input) and several lists of suggestions. In this particular case, the combined postalCodesLocalities field is the most useful one:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "results": [
        {
            "postalCode": "76857",
            "locality": "Albersweiler",
            "subLocality": "Albersweiler",
            "street": "Rehbergstr."
        },
        {
            "postalCode": "76530",
            "locality": "Baden-Baden",
            "subLocality": "Innenstadt",
            "street": "Gunzenbachstr."
        },
        ...
    ],
    "suggestions": {
        "postalCodesLocalities": [
            {
                "postalCode": "76131",
                "locality": "Karlsruhe"
            },
            {
                "postalCode": "76133",
                "locality": "Karlsruhe"
            },
            {
                "postalCode": "76135",
                "locality": "Karlsruhe"
            },
            {
                "postalCode": "76137",
                "locality": "Karlsruhe"
            },
            ...
        ],
        ...
    }
}

Note that selecting the city is necessary in some cases even when the postal code has been fully entered because some cities share the same postal code.

After the user has completed the input of the postal code and selected the city, we continue with the addressLine or the street field. The addressLine can be used if the address fields street and house number are entered in one field in the form.

POST /location/v1/autocomplete
Content-Type: application/json
Authorization: Bearer YOUR-SESSION-TOKEN-HERE
Origin: https://example.com

{
    "country": "DE",
    "postalCode": "76131",
    "locality": "Karlsruhe",
    "addressLine": Ka 50"
}

The first two letters in the street field yield the following results:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "results": [
        {
            "postalCode": "76131",
            "locality": "Karlsruhe",
            "subLocality": "Oststadt",
            "street": "Kanalweg"
        },
        {
            "postalCode": "76131",
            "locality": "Karlsruhe",
            "subLocality": "Innenstadt-Ost",
            "street": "Kaiserstr."
        },
        {
            "postalCode": "76131",
            "locality": "Karlsruhe",
            "subLocality": "Oststadt",
            "street": "Käppelestr."
        },
        ...
    ],
    "suggestions": {
        "addressLine": [
            {
                "street": "Kaiserstr.",
                "houseNumber": "50"
            },
            {
                "street": "Kanalweg",
                "houseNumber": "50"
            },
            {
                "street": "Kapellenstr.",
                "houseNumber": "50"
            },
            ...
        ],
        "streets": [
            "Kaiserstr.",
            "Kanalweg",
            "Kapellenstr.",
            ...
        ]
        ...
    }
}

In case the session token has expired, you will receive a 403 response. When this happens, please create a new session as described above.

Performing an Address Validation

As soon as the user has completed their input, you will typically send the web form to your own backend servers. Because the JavaScript execution environment inside the browser is not tamper-proof (or the form may even have been completed by a bot), we recommend that you run a server-side address validation as part of your input checks. You have one validation request in the autocomplete session available, after this request the session becomes invalid.

Please include the session token in the authorization header to make sure the request isn’t billed separately.

Integration Example

In order to get started quickly, you can use our minimal integration sample, which is self-contained and doesn’t have any framework dependencies. Download the HTML file and serve it on an HTTP server of your choice.

To get it up and running, you have to adjust the configuration:

    const _configuration = {
        url: 'https://api.uniserv.com/location/v1/',
        headers: {
            'Content-Type': 'application/json',
            'Authorization': 'Bearer YOUR-API-KEY-HERE'
        }
    };

Replace the marker with your API key and don’t forget to whitelist your domain in Uniserv CONNECT.