Data Model

The Reverse Geocoding API checks addresses based on coordinates and a defined tolerance.

Request Fields

The following table describes the input fields.

Field	Range	Type	Description
lat	-90 to 90	BigDecimal	Latitude of the WGS-84 coordinate. Examples: 48.89855 or -17.77016
lon	-180 to 180	BigDecimal	Longitude of the WGS-84 coordinate. Examples: 8.66726 or -149.48018
tolerance	0 to 30	int	Defines how far in meters can houses be from the best matching house to be included in the result

Field

Range

Type

Description

lat

-90 to 90

BigDecimal

Latitude of the WGS-84 coordinate.
Examples: 48.89855 or -17.77016

lon

-180 to 180

BigDecimal

Longitude of the WGS-84 coordinate.
Examples: 8.66726 or -149.48018

tolerance

0 to 30

int

Defines how far in meters can houses be from the best matching house to be included in the result

Response Fields

The following table describes the output fields.

Field	Type	Description
distance	int	Distance from the address house to search point
country	string	Country code of the address
region	string	Region of the address.
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
coordinates	object	includes the wgs84 coordinates with latitude, longitude and precision. Precision is the accuracy level of the coordinates. The most accurate coordinate is at the house number level. The following levels exist: 1. locality 2. street 3. house-number-range 4. house-number

Field

Type

Description

distance

int

Distance from the address house to search point

country

string

Country code of the address

region

string

Region of the address.

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

coordinates

object

includes the wgs84 coordinates with latitude, longitude and precision.

Precision is the accuracy level of the coordinates. The most accurate coordinate is at the house number level.
The following levels exist:

1. locality
2. street
3. house-number-range
4. house-number

Tolerance

The search for coordinates will always return the candidate that is the closest to the entered coordinates.This candidate might not be the wanted address.With the tolerance the area, in witch the address will be searched, will be wider.After finding the nearest candidate the distance to the entered coordinates will be determined, to that distance the tolerance value will be added.

Figure 1. Tolerance

i.e.: There are 3 possible candidates in the search radius from the entered coordinates. First candidate: 6m Second candidate: 12m Third candidate: 16m If the tolerance is between 0 and 2m the result will only be candidate 1, because it is the nearest. A tolerance between 3m and 9m the result will also include candidate 2, because the search radius will be the 15m distance from candidate 1 plus the tolerance value. Tolerance between 10m and 12m, the result will be candiate 1, 2 and 3.