Geocoding

Background

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&PostalCode=Y,

• Contact/Geocode?Address=X&City=Y&State=Z, or

• Contact/Geocode?Address=X&City=Y&State=Z&PostalCode=A

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

Contact/Save?Address=X&City=Y

// Assume this returns a ContactID=27

Contact/Normalize?ID=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.

Mechanics

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

Confidence

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.

Google Maps API Configuration

There are several configuration setting specific to the qbo.Google.Maps class used to do Google Maps-based geocoding, each in the qbo.Google.Properties.Settings configuration section:

• • GeocodeUrl: URL to call for geocoding; can include channel parameters

  • GeocodeUrlPremier: URL for accessing with a client parameter

  • GeocodeUrlRestricted: URL for accessing with a key parameter

  • ApiKey: used with the Premier URL

  • RegstrictedKey: used with the Restricted URL

  • JSVarGoogleMapsKey: passed to the qbo javascript used for browser-based map rendering

  • Signature: signing key used for server-side geocoding requests

To override any of these settings, created a SystemDefault like: qbo.Google.Properties.Settings.{Setting}

For details on usage, see the Source > ... > qbo.Core > Plugins > qbo.Google project.