The scores describe how well a result location and the request match. They can be used to determine whether a result is good enough to automatically accept it, e.g. in batch processing.
The scores are part of the quality element of a resulting location.
"quality": {
"totalScore": 90,
"addressScores": {
"country": 0,
"state": 0,
"province": 0,
"postalCode": 0,
"city": 100,
"district": 0,
"street": 100,
"houseNumber": 100
}There are two types of scores:
Total Score
A total score is calculated for the complete result address to indicate how well the input and result match overall. This score is used to sort the result list.
The calculation of the total score is based on
- the address field scores (i.e. how well the result is matched in the input)
- which fields were given in the input, and
- how well the input words are matched in the result.
| Input | Result | Total Score | Explanation |
|---|---|---|---|
| 76227 Karlsruhe | 76227 Karlsruhe | 100 | All found words are matched exactly, so all relevant field scores are good, and no input word is missing in the result. |
| Karlsruhe, Karl-Jäck-Weg | 76227 Karlsruhe, Karl-Jäck-Weg | 100 | We still have an excellent score. The bad postal code score does not contribute to the total score, because the postal code was not given in the input. |
| 76229 Karlsruhe Karl Weg | 76229 Karlsruhe, Karl-Jäck-Weg | e.g. 93 [1] | The total score is less than 100 because some street words are missing in the input. |
| 76227 Karlsruhe, Karl | 76227 Karlsruhe, Karl-Jäck-Weg | e.g. 84 [1] | The total score is less than 100 because the bad street score contributes to it. |
| 76227 Karlsruhe, Karl-Friedrich-Jäck-Weg | 76227 Karlsruhe, Karl-Jäck-Weg | e.g. 85 [1] | The total score is less than 100 because a word from the input is not in the result. |
| 76227 Kaslruhe | 76227 Karlsruhe | e.g. 88 [1] | The total score is less than 100 because Kaslruhe is only a fuzzy match. |
| 76227 Karlsru | 76227 Karlsruhe | e.g. 93 [1] | The total score is less than 100 because Karlsru is only a prefix match. |
| 76227 Karlsr uhe | 76227 Karlsruhe | 100 | Words were successfully merged. |
Address field scores
The address field scores are returned in the addressScores member of the quality element.
They are only returned if the input parameter results includes the value ADDRESS_SCORES.
For every field of a result address, an address field score is calculated to indicate how well it is matched by the respective input of the request.
- If result and input of the field match perfectly, the address field score is 100.
- If the input field is completely different or empty, the address field score is 0.
- If only some of the words match, or they only match partially, the address field score is between 0 and 100 (see examples below).
| Input | Result | Address field score | Explanation |
|---|---|---|---|
| Rue de la Gare | Rue de la Gare | 100 | All result words are matched in the input. |
| Brussels | Bruxelles | 100 | The input is a full match for the result in another language. |
| Arlon Cedex | Arlon | 100 | All result words are matched in the input. Extra words in the input are not considered for the field scores, but for the total score. |
| Bahnhofstraße | Friedrichstaler Allee | 0 | None of the two result words are present in the input |
| Iverson Road | 0 | None of the two result words are present in the input | |
| Bachstraße | Bach Straße | e.g. 100 [1] | This is a good match when concatenating the two words. |
When calculating an address field score, each word in the found record's field is matched individually. If applicable (e.g. for country names but not for country codes), prefix and fuzzy matches are also considered and the score of the best match is used.
The resulting address field score is determined as a weighted sum of these word-wise scores.
Alternative names in other languages are also considered if available.
Additionally, words are split and concatenated to find better matches.
Number of matched words
The more words of a result field are matched by words in the input field, the better the address field score.
| Input | Result | Address field score | Explanation |
|---|---|---|---|
| Rue de la Gare | Rue de la Gare | 100 | All result words matched |
| Rue de la Gare | Rue Quartier de la Gare | e.g. 80 [1] | "Quartier" is not matched |
Prefix matches
If a word in an input field is a prefix for a word in the result field or vice versa, it can be matched partially.
| Input | Result | Address field score | Explanation |
|---|---|---|---|
| Welling | Welling | 100 | Exact match |
| Welling | Wellington | e.g. 70 [1] | Welling is a prefix for Wellington |
Fuzzy matches
Similar words in the result and input fields can be matched partly based on their similarity.
| Input | Result | Address field score | Explanation |
|---|---|---|---|
| Karslruhe | Karlsruhe | e.g. 90 [1] | Two letters of the input are swapped, but it still matches most of the result word |
| Londn | London | e.g. 85 [1] | One letter is missing in the input, but it still matches most of the result word |
[1] Possible changes
To allow for improvements, the calculation and therefore the values of specific scores may be adjusted in the future.
Check the release notes to be informed about possible changes.
If you rely on concrete values, be prepared to adapt your thresholds or re-train your models.