All fields are returned for every API call. If no data was found for a specific field, the value null will be returned.
Fieldname | Description of attribute | Format (length) | Example |
resultNumber | Incremental identification number of the results | Number [0-5] | 1 |
mailabilityScore | Indication of certainty that the address is mailable (see below) | Number [0-3] | 100 |
resultPercentage | Level of similarity between the input and output address data | Number [0-3] | 95 |
formattedAddress | The full address according to local/national formatting standards | Array of three strings | [“Dam 3”, “1234AB Amsterdam”, “Netherlands”] |
streetName | Street name of the address | String | Dam |
houseNumber | House number of the address | Number | 3 |
houseNumberAddition | House number addition of the address | String | A |
postalCode | Postal code of the address | String | 1234AB |
cityName | City of the address | String | Amsterdam |
countryName | Country of the address, Netherlands | String | Netherlands |
countryIso2 | ISO 3166-1 alpha-2 code of the country of the address, NL | String [2] | NL |
countryIso3 | ISO 3166-1 alpha-3 code of the country of the address, NLD | String [3] | NLD |
localityName | Locality of the address | String | Amsterdam |
stateName | State of the address | String | Noord-Holland |
latitude | Latitudinal coordinate of address | Number [0-15] | 52.07005055399152 |
longitude | Longitudinal coordinate of address | Number [0-15] | 4.325007122144882 |
NOTE: future improvements of the API can add output fields to give more information about addresses.
resultNumber
The index of the address in the list with matched addresses, starting with 1. The addresses are sorted bases on the result score.
mailabilityScore
The mailability score (MS) is defined as how well the input address is matched with the output address from our database and based on the completeness of the input and output. Scores from 0 to 100 are given back in the output. If there are different possible matches to the input provided, then the mailability score varies due to that. What each score means, is shown in the table below.
Score | Definition |
100 | Exact unique match |
80 | Almost exact match. In most cases just 1 element missing, such as a postcode or street name, but match is still unique. |
60 | Lot of discrepancies, but unique match with our database. 5-10 |
40 | House number missing and less than 10 - 20 possible results. |
20 | House number missing more than 20 possible results. |
0 | No results. |
resultPercentage
The result percentage tells how much the output has changed from the input. The score varies from 0 to 100. A score of 100 indicates a perfect match and a score of 0 indicates a complete mismatch. An example: Let’s take the existing valid address Transformatorweg 102, 1014AK, Amsterdam. The following scenarios demonstrate how the result Scores will vary when city name, street name or postcode is different between the input and output.
1) Input: postal code=1014AK, house number = 102
Result Score: 100 Al the fields included in the input are exactly the same as their fields in the output, so a perfect score.
2) Input: street name=Tranfomatorweg, house number=102, city name=Amstdam
Result Score: 93
Some typos in the street name and the city name.