services / location / cloud / 1.0 / autocomplete

Data Model

The Autocomplete API is intended to simplify the entry of addresses by making it easier and faster to enter an address and to avoid incorrect entries by making suitable suggestions. For this purpose, each keystroke during input narrows down the result to a list of matching addresses.

Nevertheless, an address should always be validated after it has been entered completely. Through the final validation, the address can be checked again in detail without incurring additional costs (see Billing).

By default, autocomplete only considers delivery addresses. To consider other address types (the other address types are described here: Address Types) during input, the request must be extended (see API spec).

When using autocomplete, you have to decide between two different input modes: structured and single line completion, which are described below.

Autocomplete - Structured

With structured autocomplete, the address can be entered field by field, and the suggestions are also returned per field. In addition, a suggestion with a combination (postalCode and locality) is returned, as well as entire address results. The usage of the entire address results are described in the chapter Autocomplete - SingleLine, because the usage of the address results is mainly recommended for the single-line autocompletion.

The following table describes the structured input fields and the returned suggestions fields.

The following icons are used in the table to classify the fields:

  • This is an input field

  • This is an output field

Field Length Type Description

country

3

Char

Country code of the address (must be set for autocompletion or address validation). iso-3166-1 alpha2 or alpha3 codes can be used. This field must be set, before suggestions can be returned.
Example: DE, DEU

postalCode

10

string

Postal code of the address.
Example: 10

postalCodesLocalities

object

List of possible postal codes with the corresponding localities. The postal code is returned together with the locality, so that the associated locality can be set more easily.
The list is sorted by postalCode (the postal codes of the delivery addresses are returned before the other address types). Normally, only 10 combinations are returned, unless a postcode has more than 10 localities.
Example:
* First combination: postalCode=10115; locality=Berlin
* Second combination: postalCode=10117; locality=Berlin
* Third combination: postalCode=10119; locality=Berlin
* …​

locality

60

string

Locality name of the address.
Example: Ber

localities

array

Array of possible locality names of the address. In this case, the array is sorted by relevance (localities with many streets have more weight).
Example: Berlin, Bergisch Gladbach, Bergheim, etc.

subLocality

60

string

SubLocality name of the address.
Example: frie

subLocalities

array

Array of possible subLocality names of the address.
Example: Friedberg, Friedrichshafen, Friedrichshain, etc.

addressLine

100

string

Street name and house number of the address.
Example: Mari 13

addressLine

object

List of possible streets with the entered house number.
Note: It is only a house number recognition in this step. The validity is to be checked via a validation request after the address is entered completely. Example:

  • First combination: street=Marienstr.; houseNumber=10

  • Second combination: street=Marie-Curie-Str.,; houseNumber=10

  • Third combination: street=An der Marienkirche; houseNumber=10

  • …​

street

60

string

Street name of the address.
Example: Mari

streets

array

Array of possible street names of the address.
Example: Marienstr., Marie-Curie-Str., An der Marienkirche, etc.

Autocomplete - SingleLine

Entering an Address

As the name suggests, single-line autocomplete requires only one field, "singleLine", to enter an address. The autocomplete service currently only considers the following address fields when searching for suggestions:

  • postalCode

  • locality

  • subLocality

  • street or poBoxKeyword

  • houseNumber or poBoxNumber

Note: The houseNumber and the poBoxNumber fields are only checked syntactically and not checked whether they are really exists. It is recommended to validate the returned address.

PoBox addresses are also allowed to enter, if they contain postal code, it will be treated as normal postal code and PoBox keywords like "Postfach" proved for validity (whether such addresses exist for given postal code), following numbers are returned as it is. User input

77601 Postfach 110122

would be interpreted as:

  • postalCode: 77601

  • poBoxKeyword: Postfach

  • poBoxNumber: 110122

Address Results

When using single-line autocomplete, no field-level suggestions are returned (see Autocomplete - Structured above). This input format always returns complete addresses. The list of addresses always consists of the following fields:

  • addressType

  • postalCode

  • locality

  • subLocality

  • street or poBoxKeyword

  • houseNumber or poBoxNumber (if entered by user)