Validate a full address

Validate a full address, correcting and completing all parts of the address.

Use this for checking existing datasets that contain unvalidated addresses, or in use cases where you receive unvalidated data from external sources.

This method can also be used in real-time settings. For example, after a manual address entry a user can select addresses suggested by the API.

Supported countries

All countries listed by the supported countries method are supported. The country parameter must be an ISO 3166-1 Alpha-3. Use the get country method to convert a country name to the required ISO code.

Match status

For every match in the response, the status field contains important information to help interpret the match correctly. Each element is described below.

Grade

The grade indicates how closely the match corresponds to the input.

A

A perfect match. The match address is an exact match to the input parameters.

B

A great match. There are some minor differences between the match address and the input. There might some typos, for example.

C

A decent match, but the differences between the match address and the input are more significant.

D

A poor match. One or more address elements have significant errors.

E

A very poor match. There are many changes between the match and the input.

F

An extremely poor match. There are critical differences between the match and the input.

Validation Level

The validationLevel indicates up to which address element the match is validated. Possible values:

Building

The locality and street have been validated, as well as the full building name and number.

BuildingPartial

The locality and street have been validated. The building number is valid, but the specified building name is not known.

Street

The locality and street have been validated.

Locality

The locality has been validated.

None

No locality or specific street has been validated.

When you are processing full addresses, the expected validation level should be either Building or BuildingPartial. If the validation level is not one of these values, some parts of the input address are missing or could not be matched.

Is Ambiguous

The isAmbiguous element indicates if there are multiple matches that are equally similar to the input address. When that is the case there is no way to decide the best match without further information. This typically doesn't occur very often, but there can be several reasons for ambiguous matches:

• Typos or other errors in the input address make it hard to decide between potential matches.
• In some countries, the same combination of locality and street name may occur multiple times. A postcode or region parameter is needed to determine the correct match.

Validating an address

To validate and correct an input address, you need to interpret all status elements together.

1. Get the first of the matches in the response, this is always the best match. For bad inputs there might be no matches at all.
2. Check the match validationLevel. When you are processing full addresses, the expected validation level is either Building or BuildingPartial. If the validation level is not one of these values, some parts of the input address are missing or could not be matched.
3. Inspect the match grade. We recommend directly accepting any 'A' or 'B' match. 'C' grade matches could be accepted, but with lower match confidence: you might want to flag any matches of 'C' or lower for manual review. If there is only a single match, you could decide to accept it regardless of its grade.
4. The last step is to check the isAmbiguous indication. If the value is true, we can't automatically use the match. A manual review of the input and its matches is required.

Country specific address details

For results with validation level Building or BuildingPartial, country specific address information will be provided in the details element. The output structure is the same as documented for the get details method.

URL template

The REST API requires GET requests. The country parameter is part of the URL path. All remaining parameters are specified in a query string, and each parameter must be URL-encoded:

https://api.postcode.eu/international/v1/validate/{country}?postcode={postcode}&locality={locality}&street={street}&building={building}&region={region}&streetAndBuilding={streetAndBuilding}

GET /international/v1/validate/nld?locality=haarlem&street=julianapark HTTP/1.1
Host: api.postcode.eu
Authorization: Basic 2eTpkU******…

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "country": {
    "name": "The Netherlands",
    "iso3Code": "NLD",
    "iso2Code": "NL"
  },
  "matches": [
    {
      "status": {
        "grade": "A",
        "validationLevel": "Street",
        "isAmbiguous": false
      },
      "language": "nl-NL",
      "address": {
        "country": "The Netherlands",
        "locality": "Haarlem",
        "street": "Julianapark",
        "postcode": null,
        "building": null,
        "buildingNumber": null,
        "buildingNumberAddition": null,
        "region": "Noord-Holland"
      },
      "mailLines": [
        "Julianapark",
        "Haarlem"
      ],
      "location": null,
      "isPoBox": false,
      "country": {
        "name": "The Netherlands",
        "iso3Code": "NLD",
        "iso2Code": "NL"
      },
      "details": null
    }
  ]
}