📋 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.
⚙️ System 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”.
ℹ️ It is strongly recommended that when entering Postcodes that Country is added also, as not all Postcodes/Zip codes globally are unique, so Postcode + Country is best.
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.
❌ Common reasons Geocoding fails
- Missing or incomplete address details (doesn’t meet any rule).
- Wrong country or postcode (e.g. postcode belongs to a different area).
- Ambiguous locations (Bing found multiple matches too far apart).
- Invalid/old postcodes (sometimes fixed by postcode “probing,” but accuracy may be lower).
ℹ️ Tips for best results
- Always provide a Postcode where applicable (if available) – this is the most accurate.
- Always couple the Postcode with a Country name – not all Postcodes/Zip codes globally are unique, so Postcode + Country is best.
- Do not put data in any address field where it doesn’t belong, if it’s simply to ensure that there is a value. This can result in an inability to locate an address.
- Make sure Country is correct and matches the postcode or city.
- Avoid relying only on City names (some exist in multiple countries).
- There is no need to include extra address lines purely for geocoding purposes (street names are ignored).
✍️ Summary
In short: For the most accurate locations, always include a valid postcode. If that’s not possible, make sure you provide at least a city with its state or country.
ℹ️ It is strongly recommended that when entering Postcodes that Country is added also, as not all Postcodes/Zip codes globally are unique, so Postcode + Country is best.