Geocoding refers to enhancing an address with additional information, typically latitude and longitude. This serves two common QBO use cases: calculating distance between entities, and correcting (or normalizing) an address. Geocoding is invoked by calling:
- Contact/Geocode?Address=X&City=Y&State=Z, or
Calling Contact/Geocode is an excellent unit test for a power user, and a useful API for third party systems, but it does not change or save any data in the QBO database. To persist the results of a geocode, call Contact/Normalize which will call Contact/Geocode, and save the results if the confidence returned is high enough.
// Create a Contact for us to play with
// Assume this returns a ContactID=27
// Normalize will overwrite the Address, City, State, PostalCode, Country, Latitude, Longitude, VerifiedSource, VerifiedDate and VerifiedConfidence fields in the contact table.
Note that the Property class in qbo.Mortgage also supports the Normalize method.
QBO has built-in mapping providers that perform geo-coding for us, including Google, Bing, Yahoo, and Qualified Address. When calling Contact/Geocode, the following logic is applied:
- for each mapping provider configured in the QBO installation
- invoke the provider's geocode API
- calculate the confidence that the result matches the input
- if the confidence > minimum confidence required (80, by default), stop
Note that a given mapping provider (Google, for instance) may return more than 1 address for a given input. Contact/Geocode will return all results sorted by confidence descending, including the calculated confidence for each result.
Optional parameters include:
- Confidence: this will override the default minimum confidence expected; e.g. Contact/Geocode?...&Confidence=0 will simply return the first hit, regardless of confidence level
- Provider: if specified, only that provider will be used; e.g. Contact/Geocode?...&Provider=Bing will only call Bing's geocoding API
If a geocodeed address confidence is returns a value of 80 or more, it is considered a 'good' match. Confidence is calculate by comparing the input address to the output address. Specifically:
- Start with an assumed confidence of 100
- If the postal codes don't match, reduce the confidence by 20
- If the states don't match, reduce the confidence by 50
- If the cities don't match, reduce the confidence by 10
- If the house numbers don't match, reduce the confidence by 20
- If the street names don't match, reduce the confidence by 5
- If the street types (Rd. vs. St. vs Pkwy) don't match, reduce the confidence by 3
- If the full addresses don't match, reduce the confidence by 1
All of these thresholds are configurable from Design > Configuration > Contact > Settings.