Data Model

The Address Validation API checks and corrects addresses. The first section, The Address, gives you enough background on the data model to understand input and output of the API. The second section, Quality of an Address, describes how to interpret the result in order to perform appropriate actions (e.g. automatic processing or manual post-processing).

The Address

Addresses exist in every country. However, each country has its own specific characteristics.
What’s the same in all countries is that an address always consists of an address type and associated fields.

The different address types and the individual address fields are explained below.

Address Types

There are several address types, but they do not always exist in all countries. In Austria, for example, there are no major-customer addresses.

The individual types are explained below:

delivery: The delivery address is the most commonly used address type, which exists in all countries. Validation requests both in autocompletion and address validation will check only for this type by default. To ensure that the other address types are also considered, this must be explicitly requested (see API spec).

In addition to the recipient, the delivery address usually consists of the street, house number, postal code and locality.

Example:
Herr
Max Müller
Hauptstr. 1
13055 Berlin

po-box: A post office box address (P.O. Box address) is a service offered by most postal companies. The post office provides a lockable box to which mail can be sent.
In addition to the recipient, the po-box address usually consists of a keyword like "P.O. Box", "Postfach", etc., the number of the post office box, postal code and locality.

Example:
Herr
Max Müller
Postfach 80301
10003 Berlin

major-customer: A major-customer address is a recipient with a high volume of incoming mail or packages per day. These recipients have the option of having their own postcode assigned.
Typically, the major-customer address consists only of the company name, the postal code and the locality.

Example:
Allianz Versicherung
10900 Berlin

parcel-pick-up-station: A parcel-pick-up-station address is a service by DHL, which is an automated parcel storage facility where customers can pick up their parcels.
This address type is currently only supported in Germany.
In addition to the recipient, the parcel-pick-up-station address usually consists of a customer-specific identifier, street, house number, postal code, and locality. The postal number cannot be entered and validated, as this is the recipient’s personal customer number. The street field always contains the keyword "Packstation". The number of the parcel-pick-up-station can be entered in the house number field.

Example:
Herr
Max Müller
[postal number] - Not part of the service
Packstation 510
12559 Berlin

post-office: A post-office address is a service by DHL. Parcels can be delivered to a post office or agency.
This address type is currently only supported in Germany.
In addition to the recipient, the post office address usually consists of a customer-specific identifier, street, house number, postal code, and locality. The postal number cannot be entered and validated, as this is the recipient’s personal customer number. The street field always contains the keyword "Postfiliale". The number of the post office can be entered in the house number field.

Example:
Herr
Max Müller
[postal number] - Not part of the service
Postfiliale 637
12526 Berlin

Address Fields

The following table describes the input and output 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	string	Country code of the address (must be set for autocompletion or address validation). iso-3166-1 alpha2 or alpha3 codes can be used Example: DE, DEU
postalCode	10	string	Postal code of the address. Example: 10625
locality	60	string	Locality name of the address. Example: Berlin
localityAbbreviation		string	Locality abbreviation of the address (can be the same name as the locality). Example: Berlin
localityAddition		string	Addition of the locality name of the address. Example: locality = Aach postalCode = 78267 → localityAddition = Hegau postalCode = 54298 → localityAddition = b Trier
subLocality	60	string	Sub locality name of the address. Example: Charlottenburg
subLocalityAbbreviation	60	string	Sub locality abbreviation of the address (can be the same name as the sub locality). Example: Charlottenburg
street	60	string	Street name of the address. Example: Marie-Elisabeth-Lüders-Str.
streetAbbreviation		string	Street abbreviation of the address (can be the same name as the street). Example: M.-E.-Lüders-Str.
houseNumber	40	string	House number of the address. Tip: Customers often enter additional information in this field (like "ring 2x"; "leave behind the garage", etc.). An extra field for delivery instructions enables the customer to enter all relevant information for delivery and improve the validation results because less additional information ends up in the actual address fields. Example: 10 A
region	60	string	Region of the address. Note: Only relevant for USA, Canada, Brazil and Russia Example: Florida
subRegion	60	string	SubRegion of the address. Note: Only relevant for Russia Example: Luchskij Rajon
organization	60	string	Organization name of the address. Example: Uniserv GmbH
organizationAddition	60	string	Organization name of the address. Example: Department Sales
dependentStreet	60	string	Organization name of the address. Note: Only relevant for UK, Canada and Portugal. Example: Rua Professor Damião Peres (PT), M61 (UK)
poBoxNumber	30	string	Post office box number of the address. It’s sufficient or recommended to enter only the post office box number, even if the keyword (e.g. Postfach or Case Postale) can also be entered. Only the number is returned in the response. The keyword is returned separately (see field poBoxKeyword). Example: only numbers: 1101 with keyword: Postfach 1101 → keyword Postfach is returned as poBoxKeyword in the response.
poBoxKeyword		string	Contains the post office keyword depending on the address or its language. For example, in German-speaking areas of Switzerland the keyword "Postfach" is returned and in French-speaking areas of Switzerland the keyword "Case Postale" is returned. Example: Postfach; P.O. Box; Case Postale
building	60	string	Building name of the address. Example: Hotel Sonne; Halle 3
localityLine	100	string	The field can be used if the fields postalCode, locality, and subLocality are not separated and must be entered together. Note: The field cannot be combined with the individual fields mentioned above. Example: 13507 Berlin
addressLine	100	string	The field can be used if the fields street, houseNumber, poBox, and building are not separated and must be entered together. Note: The field cannot be combined with the individual fields mentioned above. Example: Berliner Str. 10 A Hotel Sonne
customAddressId	100	string	An Id set by the customer to identify which result matches the request. It is usually used in Batch.
houseNumberChoice		object	List of several house number ranges. The list of house number ranges are only returned if a list of address candidates is returned (result class E). The list of house number ranges is especially necessary for subdivided streets in order to select the correct address (the house number ranges of subdivided streets can have different postal codes, for example). A house number consist of following attributes: from: Start of the range. to: End of the range. step: Steps within the range. Can be odd, even or mixed. Example: from=1; to=5; step=odd → house number 1, 3, 5 are in this range. from=4; to=8; step=even → house number 4, 6, 8 are in this range. from=50; to=80; step=mixed → all house numbers between 50 and 80 are valid.

Field

Length

Type

Description

country

string

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

postalCode

string

Postal code of the address.
Example: 10625

locality

string

Locality name of the address.
Example: Berlin

localityAbbreviation

string

Locality abbreviation of the address (can be the same name as the locality).
Example: Berlin

localityAddition

string

Addition of the locality name of the address.
Example:

locality = Aach
postalCode = 78267 → localityAddition = Hegau
postalCode = 54298 → localityAddition = b Trier

subLocality

string

Sub locality name of the address.
Example: Charlottenburg

subLocalityAbbreviation

string

Sub locality abbreviation of the address (can be the same name as the sub locality).
Example: Charlottenburg

street

string

Street name of the address.
Example: Marie-Elisabeth-Lüders-Str.

streetAbbreviation

string

Street abbreviation of the address (can be the same name as the street).
Example: M.-E.-Lüders-Str.

houseNumber

string

House number of the address.
Tip: Customers often enter additional information in this field (like "ring 2x"; "leave behind the garage", etc.). An extra field for delivery instructions enables the customer to enter all relevant information for delivery and improve the validation results because less additional information ends up in the actual address fields.
Example: 10 A

region

string

Region of the address.
Note: Only relevant for USA, Canada, Brazil and Russia
Example: Florida

subRegion

string

SubRegion of the address.
Note: Only relevant for Russia
Example: Luchskij Rajon

organization

string

Organization name of the address.
Example: Uniserv GmbH

organizationAddition

string

Organization name of the address.
Example: Department Sales

dependentStreet

string

Organization name of the address.
Note: Only relevant for UK, Canada and Portugal.
Example: Rua Professor Damião Peres (PT), M61 (UK)

poBoxNumber

string

Post office box number of the address. It’s sufficient or recommended to enter only the post office box number, even if the keyword (e.g. Postfach or Case Postale) can also be entered. Only the number is returned in the response. The keyword is returned separately (see field poBoxKeyword).
Example:

only numbers: 1101
with keyword: Postfach 1101 → keyword Postfach is returned as poBoxKeyword in the response.

poBoxKeyword

string

Contains the post office keyword depending on the address or its language. For example, in German-speaking areas of Switzerland the keyword "Postfach" is returned and in French-speaking areas of Switzerland the keyword "Case Postale" is returned.
Example: Postfach; P.O. Box; Case Postale

building

string

Building name of the address.
Example: Hotel Sonne; Halle 3

localityLine

100

string

The field can be used if the fields postalCode, locality, and subLocality are not separated and must be entered together.
Note: The field cannot be combined with the individual fields mentioned above.
Example: 13507 Berlin

addressLine

100

string

The field can be used if the fields street, houseNumber, poBox, and building are not separated and must be entered together.
Note: The field cannot be combined with the individual fields mentioned above.
Example: Berliner Str. 10 A Hotel Sonne

customAddressId

100

string

An Id set by the customer to identify which result matches the request. It is usually used in Batch.

houseNumberChoice

object

List of several house number ranges. The list of house number ranges are only returned if a list of address candidates is returned (result class E). The list of house number ranges is especially necessary for subdivided streets in order to select the correct address (the house number ranges of subdivided streets can have different postal codes, for example).
A house number consist of following attributes:

from: Start of the range.
to: End of the range.
step: Steps within the range. Can be odd, even or mixed.

Example:

from=1; to=5; step=odd → house number 1, 3, 5 are in this range.
from=4; to=8; step=even → house number 4, 6, 8 are in this range.
from=50; to=80; step=mixed → all house numbers between 50 and 80 are valid.

Quality of an Address

There are two concepts for determining the quality of the entered address:

Result classes: The result class determines the quality of the result.
Meta information: In addition to the result classes, further detailed information can be evaluated at field level.

Result classes

The following table describes the available result classes.

Result class	Description
A	Perfect match: The address entered is correct and complete. This means that all mandatory address elements match exactly. There are only two exceptions, when a mandatory address element mustn’t match exactly and that is when the necessary reference data is not available or does not have the necessary quality to validate the input.
B	Normalized match: For result class B, the same rules apply as for result class A. But in addition to result class A, the address has been changed slightly, such as for normalization (like upper/lower case conversion) or for translating the address to a different language. Historical addresses (e.g. renamed streets) can be given a result class B in the best case.
C	Corrected match (high certainty): The given address wasn’t complete or with small spelling errors, but it is highly likely that Uniserv identified the correct address.
D	Probable match (no other candidates): The given address wasn’t complete or with several spelling mistakes. Worse compared to result class C, but it was still possible to identify a candidate address unambiguously. However, it is recommended to review addresses of this result class.
E	Ambiguous match: The address could not be unambiguously identified. Therefore, this result class returns a list of at least two possible candidates from which you have to select the correct address.
F	No match: The address could not be identified or is incomplete. Not identified means that one or more address fields could not be corrected. In this case, the input is returned. Not complete means that at least one mandatory field (e.g. street for a delivery address) is missing.

Result class

Description

Perfect match: The address entered is correct and complete. This means that all mandatory address elements match exactly.
There are only two exceptions, when a mandatory address element mustn’t match exactly and that is when the necessary reference data is not available or does not have the necessary quality to validate the input.

Normalized match: For result class B, the same rules apply as for result class A. But in addition to result class A, the address has been changed slightly, such as for normalization (like upper/lower case conversion) or for translating the address to a different language.
Historical addresses (e.g. renamed streets) can be given a result class B in the best case.

Corrected match (high certainty): The given address wasn’t complete or with small spelling errors, but it is highly likely that Uniserv identified the correct address.

Probable match (no other candidates): The given address wasn’t complete or with several spelling mistakes. Worse compared to result class C, but it was still possible to identify a candidate address unambiguously. However, it is recommended to review addresses of this result class.

Ambiguous match: The address could not be unambiguously identified. Therefore, this result class returns a list of at least two possible candidates from which you have to select the correct address.

No match: The address could not be identified or is incomplete. Not identified means that one or more address fields could not be corrected. In this case, the input is returned. Not complete means that at least one mandatory field (e.g. street for a delivery address) is missing.

Meta information

For each field, there can be the following detailed information:

Relevance: The relevance field defines the importance of the field per address type and country.
Status: The status field describes for each field whether or how much the field has changed compared to the input.
unidentifiedElements: A list of tokens in that field that couldn’t be matched.

Relevance

Relevance	Description
MANDATORY	A mandatory field of an address type is absolutely necessary for postal delivery. For example, the field "street" is a mandatory field for the address type "delivery". However, this is not the case for the address type "po-box".
IMPORTANT	The relevance "Important" also denotes a mandatory field. For example, the street of a delivery address has the relevance "Mandatory", as explained above, while the house number of a delivery address only has the relevance "Important". The reason for this distinction is that a delivery with an unidentified street typically will not succeed, whereas a delivery with a missing or incorrect house number can still be delivered in most cases.
OPTIONAL	Optional means that the fields are not relevant for delivery, such as the subLocality (in most countries) or the organization. However, when the fields are entered, they are also checked and considered for result class detection if data is available.
NOT_RELEVANT	If a field has been entered but is not relevant for the delivery of the respective address type, the field will not be checked.

Description

MANDATORY

A mandatory field of an address type is absolutely necessary for postal delivery. For example, the field "street" is a mandatory field for the address type "delivery". However, this is not the case for the address type "po-box".

IMPORTANT

The relevance "Important" also denotes a mandatory field. For example, the street of a delivery address has the relevance "Mandatory", as explained above, while the house number of a delivery address only has the relevance "Important".
The reason for this distinction is that a delivery with an unidentified street typically will not succeed, whereas a delivery with a missing or incorrect house number can still be delivered in most cases.

OPTIONAL

Optional means that the fields are not relevant for delivery, such as the subLocality (in most countries) or the organization. However, when the fields are entered, they are also checked and considered for result class detection if data is available.

NOT_RELEVANT

If a field has been entered but is not relevant for the delivery of the respective address type, the field will not be checked.

Status

Status Description

Status	Description
IDENTIFIED	The entered value is identical to the output value.
NORMALIZED	The entered value matches the output value. There were only normalizations (e.g. upper/lower case conversion, umlauts). Additional spaces, hyphen (-) and forward slash (/) are recognized as normalized as well (Examples: `Rastatter-Str.` will be matched as Normalized to `Rastatter Str.`, `annettevondrostehülshoffweg` will be matched to `Annette-von-Droste-Hülshoff-Weg`)
IN_RANGE	The entered value is part of a range. Currently this status is only used for the housenumber field, when there are no exact housenumbers in the reference data.
CHANGED	The input value has been corrected. This can be minor or major changes, or a substitution based on other fields. The magnitude of the correction is considered in the evaluation of the result class.
EMPTY	The field wasn’t entered, but has the relevance "Mandatory", "Important" or "Optional".
ADDED	The field wasn’t entered, but was added due to other fields entered.
NOT_IDENTIFIED	The input value could not be identified because it was incomplete or needed too much correction.
NOT_CHECKED	The input value wasn’t checked because it is not considered relevant or no data is available.

IDENTIFIED

The entered value is identical to the output value.

NORMALIZED

The entered value matches the output value. There were only normalizations (e.g. upper/lower case conversion, umlauts). Additional spaces, hyphen (-) and forward slash (/) are recognized as normalized as well (Examples: Rastatter-Str. will be matched as Normalized to Rastatter Str., annettevondrostehülshoffweg will be matched to Annette-von-Droste-Hülshoff-Weg)

IN_RANGE

The entered value is part of a range. Currently this status is only used for the housenumber field, when there are no exact housenumbers in the reference data.

CHANGED

The input value has been corrected. This can be minor or major changes, or a substitution based on other fields. The magnitude of the correction is considered in the evaluation of the result class.

EMPTY

The field wasn’t entered, but has the relevance "Mandatory", "Important" or "Optional".

ADDED

The field wasn’t entered, but was added due to other fields entered.

NOT_IDENTIFIED

The input value could not be identified because it was incomplete or needed too much correction.

NOT_CHECKED

The input value wasn’t checked because it is not considered relevant or no data is available.

unidentifiedElements

The unidentifiedElements field contains additional tokens that could not be identified. Fields with the following "Status" can have unidentifiedElements:

Identified
Normalized
Changed

Example:

Input = Hauptstr. in der Innenstadt
Output = Hauptstrasse | Status=NORMALIZED | unidentifiedElements=in der Innenstadt