Single-Line Autocompletion

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

Introduction

Single-Line Autocompletion uses an address from an input field and returns a list of candidate addresses while the user types. With each keystroke the list is further refined until the user selects one of the candidates.

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 API key will be exposed as part of your JavaScript code. To make sure the key 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 requests 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

While the user types, send a request in the following format for each keystroke:

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

{
    "country": "DE",
    "singleLine": "Pforzheim Ras 13"
}

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

The result contains a list of candidate addresses:

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

{
    "results": [
        {
            "postalCode": "75181",
            "locality": "Pforzheim",
            "subLocality": "Huchenfeld",
            "street": "Rasslerweg",
            "houseNumber": "13"
        },
        {
            "postalCode": "75179",
            "locality": "Pforzheim",
            "subLocality": "Wilferdinger Höhe",
            "street": "Rastatter Str.",
            "houseNumber": "13"
        },
        {
            "postalCode" :"75223",
            "locality": "Niefern-Öschelbronn",
            "subLocality": "Niefern",
            "street": "BAB Rastst. Pforzheim Ost",
            "houseNumber": "13"
        }
    ]
}

In case the session token has expired, you will receive a 403 response. When this happens, please create a new session as described above. If the session token was created for a country that does not match the country in the request, a 401 response will be provided.

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.