Historical address data

A walkthrough of the historical feature

One of the outstanding features of our service is the possibility to find historical data. For example, the user can still find a renamed street by its old street name, or a locality by its old postal code or name.
A possible use case is that you check your address data regularly (for example once a quarter). Once the initial correction has been made, only the renamings of the last 3 months (i.e. since the last validation) need to be taken into account afterward.

This feature is activated by adding the since parameter to the request:

Example for request with since-parameter

{
    "country": "DE",
    "postalCode": "39539",
    "locality": "Havelberg",
    "street": "Otto-Grotewohl-Ring",
    "houseNumber": "12",
    "_options": {
        "since": "1992-06-12",
        "include": ["metadata", "coordinates-wgs84"],
        "addressTypes": [
            "parcel-pick-up-station",
            "post-office",
            "po-box",
            "major-customer",
            "special-delivery"
        ]
    }
}

Various input formats exist for the new parameter:

Format	Examples	Description
yyyy-MM-dd	1992-06-12, 2023-15-02	Only renamings that took place at or after the given date are taken into account.
<number of days>[dD]	200d, 200D	Only renamings that are no more than x days in the past are taken into account.
<number of months>[mM]	9m, 9M	Only renamings that are no more than x months in the past are taken into account.
<number of years>[yY]	2y, 2Y	Only renamings that are no more than x years in the past are taken into account.

Format

Examples

Description

yyyy-MM-dd

1992-06-12, 2023-15-02

Only renamings that took place at or after the given date are taken into account.

<number of days>[dD]

200d, 200D

Only renamings that are no more than x days in the past are taken into account.

<number of months>[mM]

9m, 9M

Only renamings that are no more than x months in the past are taken into account.

<number of years>[yY]

2y, 2Y

Only renamings that are no more than x years in the past are taken into account.

When an address is found by its historical data (e.g. old street name), the current address data is returned. The metadata (if requested) indicates historical data in the field historicName for comparison.

Example with the historical street name 'Otto-Grotewohl-Ring'

{
    "resultClass": "B",
    "results": [
        {
            "addressType": "delivery",
            "country": "DE",
            "postalCode": "39539",
            "locality": "Havelberg",
            "localityAbbreviation": "Havelberg",
            "subLocality": "Havelberg",
            "subLocalityAbbreviation": "Havelberg",
            "street": "Mühlenweg",
            "streetAbbreviation": "Mühlenweg",
            "houseNumber": "16",
            "coordinates": {
                "wgs84": {
                    "precision": "house-number",
                    "lat": 52.83363,
                    "lon": 12.08429
                }
            },
            "_meta": {
                "fields": {
                    "country": {
                        "relevance": "MANDATORY",
                        "status": "IDENTIFIED"
                    },
                    "postalCode": {
                        "relevance": "MANDATORY",
                        "status": "IDENTIFIED"
                    },
                    "locality": {
                        "relevance": "MANDATORY",
                        "status": "IDENTIFIED"
                    },
                    "subLocality": {
                        "relevance": "OPTIONAL",
                        "status": "ADDED"
                    },
                    "street": {
                        "relevance": "MANDATORY",
                        "status": "IDENTIFIED",
                        "historicName": "Otto-Grotewohl-Ring"
                    },
                    "houseNumber": {
                        "relevance": "IMPORTANT",
                        "status": "IDENTIFIED",
                        "historicName": "12"
                    },
                    "building": {
                        "relevance": "OPTIONAL",
                        "status": "EMPTY"
                    },
                    "organization": {
                        "relevance": "OPTIONAL",
                        "status": "EMPTY"
                    },
                    "organizationAddition": {
                        "relevance": "OPTIONAL",
                        "status": "EMPTY"
                    }
                }
            }
        }
    ]
}

Renamings of the postal code, locality and sublocality, street and house number are taken into account.

Examples

For the following examples, we set the since parameter to '1950-01-01' to find all relevant changes.
Given are a historical street name and a historical house number.

Field	Input	Result
Country	DE	DE
PostalCode	39539	39539
Locality	Havelberg	Havelberg
Street	Otto-Grotewohl-Ring	Mühlenweg
HouseNumber	12	16

Field

Input

Result

Country

PostalCode

39539

Locality

Havelberg

Street

Otto-Grotewohl-Ring

Mühlenweg

HouseNumber

Field	Input	Result
Country	DE	DE
PostalCode	06132	06132
Locality	Halle (Saale)	Halle (Saale)
Street	Str. des Roten Oktober	Gustav-Staude-Str.
HouseNumber	6	2

Field

Input

Result

Country

PostalCode

06132

Locality

Halle (Saale)

Street

Str. des Roten Oktober

Gustav-Staude-Str.

HouseNumber

Here, not only the street name has changed, but also the name of the sublocality:

Field	Input	Result
Country	DE	DE
PostalCode	75179	75179
Locality	Pforzheim	Pforzheim
SubLocality	Pforzheim	Brötzingen
Street	Brühlweg	Theodor-Mohr-Str.
HouseNumber	4	4

Field

Input

Result

Country

PostalCode

75179

Locality

Pforzheim

SubLocality

Pforzheim

Brötzingen

Street

Brühlweg

Theodor-Mohr-Str.

HouseNumber

Here is an example with a changed postal code:

Field	Input	Result
Country	DE	DE
PostalCode	16321	16356
Locality	Ahrensfelde	Ahrensfelde
Street	Kirschenallee	Kirschenallee

Field

Input

Result

Country

PostalCode

16321

16356

Locality

Ahrensfelde

Street

Kirschenallee