📋 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 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
Pre-processing
If a country is provided, the service will carry out some pre-checks to improve the geocoding outcome:
State cleaning - If an address is for a country that is not internationally recognised as using a state, any supplied state value is removed. These rules are held centrally and do not reflect any changes a customer may make to their state rules.
See Appendix A at the bottom of this article for the list of countries that this service recognises as using a state.
Postcode cleaning - If an address is for a country that is not internationally recognised as using a postal code, any supplied postal code value is removed.
See Appendix B at the bottom of this article for the list of countries that this service recognises as using a postal code.
The service will only geocode an address if it meets one of the rules below. Case is ignored in all rules, and all values have leading and trailing white spaces removed, but no other pre-processing of address elements 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, Country
If the “Postcode” and “Country” properties are non-empty strings then the cache is searched for a matching postcode and country that has no “TownCity” or “State” values. All non-word characters (spaces, hyphens, etc) are removed from the postcode before doing this, so a postcode of “B46 3BP” would be searched as “B463BP”, and “12-345” would be searched.
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, subject to state and postcode cleaning, 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, the Bing confidence rating will also be assessed to try and disambiguate the results, 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.
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.
Appendix A️
Australia
Brazil
Canada
India
United States
Appendix B️
Afghanistan
Aland
Albania
Algeria
American Samoa
Andorra
Anguilla
Argentina
Armenia
Ascension
Ashmore and Cartier Islands
Australia
Australian Antarctic Territory
Austria
Azerbaijan
Bahamas
Bahrain
Baker Island
Bangladesh
Barbados
Belarus
Belgium
Belize
Bermuda
Bhutan
Bolivia
Bosnia and Herzegovina
Brazil
British Antarctic Territory
British Indian Ocean Territory
British Sovereign Base Areas
British Virgin Islands
Brunei
Bulgaria
Burkina Faso
Cambodia
Canada
Cape Verde
Cayman Islands
Chile
China
Christmas Island
Clipperton Island
Cocos (Keeling) Islands
Colombia
Congo - Kinshasa
Coral Sea Islands
Costa Rica
Cote d'Ivoire (Ivory Coast)
Croatia
Cuba
Cyprus
Czech Republic
Denmark
Dominican Republic
Ecuador
Egypt
El Salvador
Estonia
Falkland Islands (Islas Malvinas)
Faroe Islands
Finland
France
French Guiana
French Polynesia
Georgia
Germany
Ghana
Gibraltar
Greece
Greenland
Guadeloupe
Guam
Guatemala
Guernsey
Haiti
Heard Island and McDonald Islands
Honduras
Howland Island
Hungary
Iceland
India
Indonesia
Iran
Iraq
Ireland
Isle of Man
Israel
Italy
Japan
Jarvis Island
Jersey
Johnston Atoll
Jordan
Kazakhstan
Kenya
Kingman Reef
Kiribati
Korea, South
Kuwait
Kyrgyzstan
Laos
Latvia
Lebanon
Lesotho
Liberia
Liechtenstein
Lithuania
Luxembourg
Macedonia
Madagascar
Malawi
Malaysia
Maldives
Mali
Malta
Marshall Islands
Martinique
Mauritius
Mayotte
Mexico
Micronesia
Midway Islands
Moldova
Monaco
Mongolia
Montenegro
Montserrat
Morocco
Mozambique
Myanmar (Burma)
Nagorno-Karabakh
Namibia
Nauru
Navassa Island
Nepal
Netherlands
Netherlands Antilles
New Caledonia
New Zealand
Nicaragua
Niger
Nigeria
Niue
Norfolk Island
Northern Cyprus
Northern Mariana Islands
Norway
Oman
Pakistan
Palau
Palmyra Atoll
Panama
Papua New Guinea
Paraguay
Peru
Peter I Island
Philippines
Pitcairn Islands
Poland
Portugal
Pridnestrovie (Transnistria)
Puerto Rico
Queen Maud Land
Reunion
Romania
Ross Dependency
Russia
Saint Barthelemy
Saint Helena
Saint Kitts and Nevis
Saint Lucia
Saint Martin
Saint Pierre and Miquelon
Saint Vincent and the Grenadines
Samoa
San Marino
Saudi Arabia
Senegal
Serbia
Singapore
Slovakia
Slovenia
South Africa
South Georgia & South Sandwich Islands
South Ossetia
Spain
Sri Lanka
Svalbard
Swaziland
Sweden
Switzerland
Taiwan
Tajikistan
Tanzania
Thailand
Trinidad and Tobago
Tristan da Cunha
Tunisia
Turkey
Turkmenistan
Turks and Caicos Islands
U.S. Virgin Islands
Uganda
Ukraine
United Kingdom
United States
Uruguay
Uzbekistan
Vatican City
Venezuela
Vietnam
Wake Island
Wallis and Futuna