Overview

Geocoding is the process of converting a written address into a co-ordinate, usually using a 3rd party service. In the context of Mercury, geocoding is taking the address of Contacts and Vacancies and being able to pin them on a map and work out how far away they are from each other. We currently use Bing to to do the actual Geocoding and then cache the result to avoid repeated calls to Bing for the same or similar address. This reduces cost and improves performance. Depending on the usage, the resulting co-ordinate may be stored against the address such as on Contact records in Dataverse.

Rules

The service will only geocode an address if it meets one of these rules. Case is ignored in all rules and all values have leading and trailing white spaces removed, but no other pre-processing takes place unless otherwise described. If an address could match more than one rule, then only the first matching rule is considered:

Rule 1 - Postcode

If the “Postcode” property is a non-empty string then the cache is searched for a matching postcode that has no “TownCity”, “State” or “Country” values. All white space is removed before doing this, so a postcode of “B46 3BP” would be searched as “B463BP”.

Rule 2 - City, State, Country

If “TownCity”, “State” and “Country” are non-empty strings then the cache is searched for an exact match on “TownCity”, “State” and “Country” that has no “PostCode” values.

Rule 3 - City, Country

If “TownCity” and “Country” are non-empty strings then the cache is searched for an exact match on “TownCity” and “Country” that has no “PostCode” or “State” values.

Rule 4 - City, State

If “TownCity” and “State” are non-empty strings then the cache is searched for an exact match on “TownCity” and “State” that has no “PostCode” or “Country” values.

If no rules are met, the service will respond with "939310003: Insufficient address detail to geocode" and will not proceed to Bing.

Bing

If a rule is met but no cache result is found, all of the supplied address elements are sent to Bing. If a single result is returned, the location is cached along with only the address elements that are applicable to whichever rule was met. If no results are returned, the service will return "939310001: Bing returned 0 results”. If multiple results are returned and they are all within 15 miles of each other, the result with the smallest circle radius is cached and returned, otherwise "939310003: Bing returned multiple results” is returned.