Geocoder API Developer's Guide

Understanding result relevance

This section describes how Geocoder API 'relevance' and 'match quality' information can be used to determine result confidence. Be aware that the decision logic may depend on the use case, typical user behavior and the country specific addressing schema.

Relevance

Relevance is a precentage value ranging from 0 to 1 representing the percentage of the input that matches the returned address. "1" means that all input tokens were matched and there was no typo or any other difference.

If the input query contains any additional information – name of the person, phone number or a hint to ring twice – the relevance will be low, but the address returned may be correct.
Low relevance may indicate that the Geocoder API was not able to match some relevant part of the address in the input query.
To separate the above cases one may look at match quality of the fields. These values show how well each of the address elements (e.g. street, city, country etc.) in the results matched to the input that was provided. If all the fields that are important for addressing in the country were matched with high match quality, one can assume that relevance is low because of the additional non-address information. And the result is still highly confident.

MatchCode

The Geocoder API returns a matchCode when adding responseattributes=matchCode to the request. matchCode can be one of the following:

exact
ambiguous
upHierarchy
ambiguousUpHierarchy

Ambiguous indicates that the input was not specific enough for the Geocoder API to prefer a single result. An example query for this case is 148th Ave, Bellevue

MatchLevel

Another important response information is matchLevel. It specifies the most specific address field that matches the query.

matchLevel can be one of the following:

country
state
county
city
district
street
intersection
houseNumber
postalCode
landmark

A MatchLevel 'houseNumber' can be returned for

an exact house number match and
a match to a neighboring house number, e.g. if the newly build house is not yet in the map data.

Exact and neighboring house numbers can be distinguished with help of information returned in the block of AdditionalData:

houseNumberFallback: true. This attribute is included only if matchLevel equals 'houseNumber'. The value is always set to true. It indicates that the requested house number was corrected to match the nearest known house number.
houseNumberFallbackDifference: Difference between the requested house number and the matched house number. This attribute is only included if houseNumberFallback is set to true.

Depending on use case one can decide to accept or reject neighboring house numbers and decide on acceptable house number difference.

As an example, in the US we would consider the non-ambiguous house number result to be of higher confidence under either of the below conditions:

Relevance=1
matchQuality.postalCode=1 and matchQuality.street=0.85.
Postal codes in US can reliably point to the area; Street match quality above 85% tolerates typos or omitted street type. Examples of not perfect queries for which the Geocoder API returns confident result with relevance below 1:
- Case: extra info in the query.
  Query: "Hair Replacement Systems 31275 Northwestern Hwy Farmington Hills MI 48334-2558",
  Result: "31275 Northwestern Hwy, Farmington Hills, MI 48334, United States"
- Case: discrepancy in street name.
  Query: "725 NARDO South, J-4 Solana Beach, CA 92075",
  Result: "725 S Nardo Ave, Solana Beach, CA 92075, United States"
matchQuality.city>=0.9 and matchQuality.state=1 and no matchQuality.postalCode and matchQuality.street=0.85.
If the input does not contain a postal code, then the result can be considered confident if both city and state has been successfully matched. Examples of imperfect queries for which Geocoder API returns confident result with relevance under 1:
- Case: typo in street name.
  Query: "112 talgarth ct, exton, pa",
  Result: "112 Talgrath Ct, Exton, PA 19341, United States"
- Case: extra info in query.
  Query: "petsmart locations 6409 castlefin way, alexandria, va",
  Result: "6409 Castlefin Way, Alexandria, VA 22315, United States"
matchQuality.city>=0.9 and matchQuality.state=1 and matchQuality.postalCode>=0.8 and matchQuality.street>=0.85.
If the postal code in the result is not the same as the input, but city and state are matched, the result is still confident. Postal code match quality above 80% tolerates a one-digit difference Examples of not perfect queries, for which Geocoder API returns confident result with relevance under 100%:
- Query: "1906 N. Hamilton St.,Richmond,VA,23220",
  Result: "1906 N Hamilton St, Richmond, VA 23230, United States"
- Query: "NW 37 AVE 1200, Miami, FL 33126",
  Result: "1200 NW 37th Ave, Miami, FL 33125, United States"

Please note that these rules are rather strict. More relaxed rules still would give high percentage of confident results.

In other countries the important parts of the queries may be different. E.g., in Australia people rather use for addressing suburb (district) name than the city name. And the rules and thresholds also would be different.