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.
- 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.
responseattributes=matchCodeto the request. matchCode can be one of the following:
148th Ave, Bellevue
Another important response information is matchLevel. It specifies the most specific address field that matches the query.
- 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.
- 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.
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.