disambiguation, virtual earth, and other words to impress your friends

Ah, disambiguation. It's such a great word. I'll use it frequently throughout this posting because it makes me sound smart. I suggest you use it with your friends and co-workers for the same reason.

Disambiguation is the process of narrowing your search criteria in Virtual Earth from something fairly generic or confusing to something exact. For example, if you were to search for McChord, VE wouldn't know for sure if you meant McChord AFB or something else, so VE would need you to clarify before showing you a map.

That's where disambiguation comes into play. Virtual Earth will prompt you with a list of possibilities - forcing you to disambiguate by selecting a specific location.

Disambiguation, disambiguation, disambiguation...

The easiest way to handle disambiguation is to let Virtual Earth handle it for you. The way you do that is to set the ninth argument in the Find method to true. This argument is the useDefaultDisambiguation argument and basically it tells Virtual Earth to prompt the user with a list of possibilities if their criteria isn't specific. The code for this is simple and looks like this:

<script type="text/javascript">
var map = null;
var results = null;

//called from body.onLoad
function GetMap()
{
  map = new VEMap('MapDiv');
  map.LoadMap();
}

function FindLocation()
{
var where = "McChord";
try
{
 map.Find(null,
  where,
  null,
  null,
  0,
  10,
  true,
  true,
  true, //useDefaultDisambiguation
  true,
  ProcessResults);
}
catch(e)
{
 alert(e.message);
}
}

//callback function for map.Find
function ProcessResults()
{
}
</script>

So, in the code block above, the second to last boolean value is the argument called useDefaultDisambiguation. Again, setting this to true uses the default Virtual Earth disambiguation box. The code above should pop a disambiguation box with a list of options.

"But wait," you say in your leather pants and best Zoolander accent. "My users are super smart and sexy. They would be insulted to be questioned by a simple tool such as this computer. Remove that small boxy thing from my sight."

That, my friend, is what we like to call customization. Another big word. That's right. Disambiguation customization. How is my brain so big?

If your users are too smart and sexy for disambiguation, you can set up Virtual Earth to just use the first (what it considers the "best") option from a list of disambiguated locations. In other words, if you typed in McChord, Virtual Earth would guess that you might mean McChord AFB and take you straight there.

Giving you the option to show or hide the disambiguation box allows you to customize the experience to your users. If you have a savvy user base you can probably suppress the dialog box. If you feel that some of your users would be confused or mad if they are brought to the wrong Portland or Bangor, then you will probably want to show them the disambiguation dialog box.

This post is getting long, so I'm going to save custom disambiguation for the next post. Until then, happy coding!