Changelog 2023

Table of Contents

13.12.2023

Features

Validating multiple addresses

A new endpoint enables the possibility to validate multiple addresses at once.
For further information go to: Validating multiple addresses

16.11.2023

Features

Additional Elastic query

An additional new Elastic Search query enables better and more performant search results.

Field	Input	Result
Country	DE	DE
PostalCode	92281	92281
Locality	Königstein Oberpf.	Königstein
Street	Pfarrgasse	Pfarrweg
HouseNumber	5	5

Field

Input

Result

Country

PostalCode

92281

Locality

Königstein Oberpf.

Königstein

Street

Pfarrgasse

Pfarrweg

HouseNumber

Fixed bugs

consider also scoring for the HISTORICAL reference

04.10.2023

Features

Major customer addresses with streets

Major customer addresses usually have no streets. If a client adds a street to a validation request anyway, it will now be returned corrected if a match was found, and as-is otherwise. If metadata is requested, the field _meta.fields.street.status will reflect if there was a match and its class.

Please note that the street will not improve the validation result, it is a purely informative addition.

The following examples demonstrate the new behaviour. Only the first validation is shown in full here, the others are omitted for brevity:

Validation request Validation response

Table 1. Validation for a major customer address in Germany
Validation request	Validation response
`{ "country": "DE", "postalCode": "53250", "locality": "Bonn", "street": "Kurt-Schumacher-Str.", "_options": { "include": [ "metadata" ], "addressTypes": ["major-customer"] } }`	{ "resultClass": "A", "results": [ { "addressType": "major-customer", "country": "DE", "postalCode": "53250", "locality": "Bonn", "localityAbbreviation": "Bonn", "street": "Kurt-Schumacher-Str.", "_meta": { "fields": { "country": { "relevance": "MANDATORY", "status": "IDENTIFIED" }, "postalCode": { "relevance": "MANDATORY", "status": "IDENTIFIED" }, "locality": { "relevance": "MANDATORY", "status": "IDENTIFIED" }, "street": { "relevance": "NOT_RELEVANT", "status": "IDENTIFIED" }, "organization": { "relevance": "OPTIONAL", "status": "EMPTY" }, "organizationAddition": { "relevance": "OPTIONAL", "status": "EMPTY" } } } } ] }

{
  "country": "DE",
  "postalCode": "53250",
  "locality": "Bonn",
  "street": "Kurt-Schumacher-Str.",
  "_options": {
    "include": [
      "metadata"
    ],
    "addressTypes": ["major-customer"]
  }
}

{
  "resultClass": "A",
  "results": [
    {
      "addressType": "major-customer",
      "country": "DE",
      "postalCode": "53250",
      "locality": "Bonn",
      "localityAbbreviation": "Bonn",
      "street": "Kurt-Schumacher-Str.",
      "_meta": {
        "fields": {
          "country": {
            "relevance": "MANDATORY",
            "status": "IDENTIFIED"
          },
          "postalCode": {
            "relevance": "MANDATORY",
            "status": "IDENTIFIED"
          },
          "locality": {
            "relevance": "MANDATORY",
            "status": "IDENTIFIED"
          },
          "street": {
            "relevance": "NOT_RELEVANT",
            "status": "IDENTIFIED"
          },
          "organization": {
            "relevance": "OPTIONAL",
            "status": "EMPTY"
          },
          "organizationAddition": {
            "relevance": "OPTIONAL",
            "status": "EMPTY"
          }
        }
      }
    }
  ]
}

Table 2. Results for the major customer address, depending on the street
User input: `street`	Validation result: `street`	Validation result: `_meta.fields.street.status`	Explanation
Kurt-Schumacher-Str.	Kurt-Schumacher-Str.	`IDENTIFIED`	Exact match
Kurt-Schuhmacher-Str.	Kurt-Schumacher-Str.	`CHANGED`	Match, one corrected letter
Kurt-Schumacher-Straße	Kurt-Schumacher-Str.	`NORMALIZED`	Match, synonymous spelling of "Str."
Does-not-exist	Does-not-exist	`NOT_CHECKED`	No match, user input is returned as-is

Fixed bugs

The country that has been used for issuing session tokens via the start-session endpoint will be mandatory for all subsequent autocomplete or address validation requests using that session token.

Minor improvements

A retry-after header is added if the service returns HTTP 429 Too Many Requests or HTTP 503 Service Unavailable responses.

22.08.2023

Features

Historical streets in Switzerland

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	CH	CH
PostalCode	8704	8704
Locality	Herrliberg	Herrliberg
Street	Kittenmühle	Kappelistrasse
HouseNumber	40	40

Field

Input

Result

Country

PostalCode

8704

Locality

Herrliberg

Street

Kittenmühle

Kappelistrasse

HouseNumber

Technical improvements

Upgrade to Gradle 8

27.06.2023

Features

Historical address data

A walkthrough of the historical feature

For a complete example have a look at Historical address data.

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.

Historical streets

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

Historical postal codes

Validating an address can now optionally match against historical postal codes. How far into the past postal codes are taken into account is controlled by setting the since parameter, which supports both absolute and relative date specifications.

If a historical postal code matches the user input exactly, the result contains the current postal code, the metadata (if requested) indicates the historical one, and the result class gets raised (e.g. from D to C).

Example:
The address 35287 Amöneburg, Dorfwiesenweg 1 historically had the postal code 35274, which got changed on the 28^th December 1998. If the validation input uses the historical one, 35274 Amöneburg, Dorfwiesenweg 1, these are the possible validation results:

Parameter since Validation result

Table 3. Results for Amöneburg, depending on the value of the `since` parameter
Parameter `since`	Validation result
Not set, 1998-12-29 or later	Address has been found, but the historical postal code counts as miss. `{ "resultClass": "D", "results": [ { "addressType": "delivery", "country": "DE", "postalCode": "35287", "locality": "Amöneburg", ... other fields omitted for brevity ... "_meta": { "fields": { "postalCode": { "relevance": "MANDATORY", "status": "CHANGED" }, ... other fields omitted for brevity ... } } } ] }`
1998-12-28 or earlier	Address has been found, and the historical postal code counts as match. `{ "resultClass": "C", "results": [ { "addressType": "delivery", "country": "DE", "postalCode": "35287", "locality": "Amöneburg", ... other fields omitted for brevity ... "_meta": { "fields": { "postalCode": { "relevance": "MANDATORY", "status": "CHANGED", "historicName": "35274" }, ... other fields omitted for brevity ... } } } ] }`

Not set, 1998-12-29 or later

Address has been found, but the historical postal code counts as miss.

{
	"resultClass": "D",
	"results": [
		{
			"addressType": "delivery",
			"country": "DE",
			"postalCode": "35287",
			"locality": "Amöneburg",
			... other fields omitted for brevity ...
			"_meta": {
				"fields": {
					"postalCode": {
						"relevance": "MANDATORY",
						"status": "CHANGED"
					},
					... other fields omitted for brevity ...
				}
			}
		}
	]
}

1998-12-28 or earlier

Address has been found, and the historical postal code counts as match.

{
	"resultClass": "C",
	"results": [
		{
			"addressType": "delivery",
			"country": "DE",
			"postalCode": "35287",
			"locality": "Amöneburg",
			... other fields omitted for brevity ...
			"_meta": {
				"fields": {
					"postalCode": {
						"relevance": "MANDATORY",
						"status": "CHANGED",
						"historicName": "35274"
					},
					... other fields omitted for brevity ...
				}
			}
		}
	]
}

Historical localities

Similar to historical postal codes, validating an address can now also optionally match against historical localities, depending on the since parameter in the same way.

In contrast to historical postal codes, historical localities allow for typing errors and thus don’t need to match exactly to still yield a result. Like above, the result contains the current locality, the metadata (if requested) indicates the historical one, and the result class gets raised (e.g. from D to C).

Example:
The locality Klarahöh is part of 16356 Ahrensfelde since the 6^th February 1998. Validating 16356 Klarahöh, Thomas-Mann-Str. 1 with since set to 1998-02-06 or earlier will yield the following result:

{
	"resultClass": "C",
	"results": [
		{
			"addressType": "delivery",
			"country": "DE",
			"postalCode": "16356",
			"locality": "Ahrensfelde",
			"street": "Thomas-Mann-Str.",
			"houseNumber": "1",
                        ... other fields omitted for brevity ...
			"_meta": {
				"fields": {
					"postalCode": {
						"relevance": "MANDATORY",
						"status": "IDENTIFIED"
					},
					"locality": {
						"relevance": "MANDATORY",
						"status": "CHANGED",
						"historicName": "Klarahöh"
					},
                                       ... other fields omitted for brevity ...
				}
			}
		}
	]
}

The following table shows typing errors in the name "Klarahöh" and their influence on the validation result. Please note: In all these results, Ahrensfelde has been found and returned with its current postal code and locality.

Table 4. Results for Klarahöh, depending on the number of typing errors
User input	Result class	Field `historicName`	Explanation
Klarahöh	C	Klarahöh	Exact match of historical locality
Glarahöh	C	Klarahöh	Match of historical locality with one corrected letter
Grarahöh	C	Klarahöh	Match of historical locality with two corrected letters
Grurahöh	D	not set	Historical locality is not matched due to too many deviations (three changed letters)
Klaarahhö	C	Klarahöh	Match of historical locality with duplicated "a" and swapped letters "öh"
Jlaarhhö	D	not set	Historical locality is not matched due to too many deviations (changed "J", duplicated "a", missing "a", swapped "öh")

30.05.2023

Technical improvements

Performance optimization due to a simple search that can find perfect candidates faster

03.05.2023

Technical improvements

Performance optimization due to early termination of address candidate post-processing for perfect matches
ElasticSearch index performance optimisation

29.03.2023

Technical improvements

Data management improved
Logging and monitoring improved

Fixed bugs

31.01.2023

Features

Added support for lieux-dits in France, which are now included in the subLocality field of validation responses

Technical improvements

Upgraded tech stack to the latest major version

Fixed bugs

Street names that end with a period are now identified correctly

Older changes are documented on the archive page: * Changelog 2022 * Changelog 2021