In order to get the three components to talk to each other (and Microsoft's MapPoint Web Service farm), we need to use two different communications strategies as shown in Figure 1.

Figure 1: System Architecture

The MapPoint Web Service component (our Geocoding Application) uses HTTP and SOAP to communicate with Microsoft's MWS servers.

Assuming you have started a new ASP.NET 2.0 web application, then you will want to do the following to create the geocoder class:

1. Add a web reference to the MapPoint Web Service. For this article, we will use the staging services at http://staging.mappoint.net/standard-30/mappoint.wsdl. For a production system, you would use http://service.mappoint.net/standard-30/mappoint.wsdl. Name the reference "MapPointService".
   
   
2. Create a new class called RooftopGeocoder. In an ASP.NET 2.0 application, this class should automatically be placed in the App_Code directory.
   
   
3. In the constructor, create an instance of the FindServiceSoap class and set your MapPoint Web Service Credentials:
   
   
   private MapPointService.FindServiceSoap findService;
   public RooftopGeocoder()
     {
       findService = new MapPointService.FindServiceSoap();
       findService.Credentials = new System.Net.NetworkCredential("username", "password");
       findService.PreAuthenticate = true;
     }

   Listing 1: Initializing the Web Service
   
   

4.Next, we need to create a method to use rooftop geocoding on an address line. The method should look something like this:

public string GeocodePoint(string streetAddress)
{
    string latlong = "Unavailable";

    //Define the address specification for MWS
    MapPointService.Address myAddress = new MapPointService.Address();
    myAddress.FormattedAddress = streetAddress;
    
    //Set the search options
    MapPointService.FindOptions myFindOptions = new MapPointService.FindOptions();

    MapPointService.FindAddressSpecification findAddressSpec = 
     new MapPointService.FindAddressSpecification();
    findAddressSpec.InputAddress = myAddress;
    findAddressSpec.Options = myFindOptions;
    findAddressSpec.DataSourceName = "MapPoint.NA";
    
    //Set the ResultMask to include the rooftop geocoding values
    findAddressSpec.Options.ResultMask =
        MapPointService.FindResultMask.RooftopFlag |
        MapPointService.FindResultMask.LatLongFlag |
        MapPointService.FindResultMask.EntityFlag | 
        MapPointService.FindResultMask.MatchDetailsFlag |
        MapPointService.FindResultMask.AddressFlag;

    //Call the MWS FindAddress method
    MapPointService.FindResults myFindResults = findService.FindAddress(findAddressSpec);

    //Parse the Results
    MapPointService.FindResult bestResult = myFindResults.Results[0];
    int matchcode = 0;
    
    MapPointService.EntityPropertyValue[] props = 
      bestResult.BestViewableLocation.Entity.Properties;
    //Find MatchedMethod property which tells you whether rooftop was used 
    for (int i =0; i< props.Length; i++)
    {
        if (props[i].Name == "MatchedMethod")
        {
            matchcode = System.Convert.ToInt32(props[i].Value);
        }
    }
    //Prepare result 
    if (matchcode == 7)
    {
        latlong = "new VELatLong(" + bestResult.BestViewableLocation.LatLong.Latitude 
            + ", " + bestResult.BestViewableLocation.LatLong.Longitude + ")";
    }

    return latlong;
}

Listing 2: Rooftop Geocoding

Our function uses the MapPoint Web Service FindAddress method to find a geocode for the address. If the MatchedMethod property equals "7" then the resulting latitude and longitude are from the rooftop geocoder. If we have a rooftop geocode, the method returns a string defining a VELatLong object containing the geocoded point.

The next step on the server side is to create an HttpHandler that will leverage the RooftopGeocoder class. In your ASP.NET application, add a new Generic Handler named "GeocodingHandler". This handler should expect one parameter (the address).

public void ProcessRequest(HttpContext context)
{
    RooftopGeocoder rg = new RooftopGeocoder();
    context.Response.ContentType = "text/plain";
    string result = rg.GeocodePoint(context.Request.QueryString["addr"]);
    context.Response.Write("CreatePin('Rooftop', "+result+ ")");
}

Listing 3: The HttpHandler

Notice that we pass the "addr" querystring parameter to an instance of RooftopGeocoder. We take the returned VELatLong object and pass it back to a JavaScript method called "CreatePin". We'll write that method in the next section.

Since you already have an ASP.NET web project, create a simple HTML page called Rooftop.html. Replace the contents of the page with the following:

<html >
<head>
<title>Rooftop Geocoding</title>
<script type="text/javascript" 
  src="http://dev.virtualearth.net/mapcontrol/mapcontrol.ashx?v=5"></script>
<script type="text/javascript">
  var map;
  function OnPageLoad()
  {
    map = new VEMap('myMap');
    map.LoadMap();
  }
  //Add Additional Code Here
</script>
</head>
<body onload="OnPageLoad();">
  <div id="myMap" style="position:relative;width:600px;height:400px;"></div>
</body>
</html>

Listing 4: Rooftop.html basic page

This basic page will display a map. In addition to the map, we need a field for the user to input an address and several other functions to help display the pushpins.

Adding a text input box to our map will give the user a place to enter an address. Add the following <div> tag to Listing 4:

<div id="SearchPanel">
  <table border=0 width='100%'>
    <tr><td bgcolor='#C0C0CF'><p align='center'>Search</p></td></tr>
    <tr><td><p align='left'>
      Address
      <INPUT id="txtWhere" type="text" value="" name="txtWhere" style="width: 225px">
    </td></tr>
    <tr><td bgcolor='#E0E0E0'><p align='center'>
      <input type="button" value="Geocode" onclick="Geocode();" 
        id="Geocode" name="Geocode" />
    </td></tr>
  <table>
</div>

Listing 5: Adding the controls

Next, we need to add a CSS style section to make the control easier to see:

<style type="text/css" media="screen">
  #SearchPanel
  {
    width: 300px;
    border-style: solid;
    border-width: 1px;
    border-color: lightgray;
    background: white;
  }
</style>

Listing 6: CSS Styling for Find Control

Finally, we need to change the OnPageLoad method in Listing 4 to register the SearchPanel div and position it properly. Add the following lines to the end of OnPageLoad:

var geocode = document.getElementById('SearchPanel');
map.AddControl(geocode);
geocode.style.left = "300px";
geocode.style.top = "5px";

Listing 7: Registering the control

If we load up the HTML page, it should look like this:

Figure 2: The Basic Page with the Find Control

When a user enters an address and presses the Geocode button, we want to create two pushpins. One pin will be generated using rooftop geocoding. The other will be generated using the default Bing Maps geocoding. We can start by creating a method to draw custom HTML pins for each of our pushpins. Our method will accept a string indicating the geocode method and a VELatLong indicating the point.

function CreatePin(type, point)
{
  if (point != 'Unavailable')
  {
    var icon = "<div style='font-size:12px;font-weight:bold; 
      border:solid 2px Black;background-color:Aqua;width:200px;'>"
    icon += type + ":" + point.Latitude + " : " + point.Longitude;
    icon += "<div>";
    var spec = new VECustomIconSpecification();
    spec.CustomHTML = icon;

    var pin = new VEShape(VEShapeType.Pushpin, point);
    pin.SetCustomIcon(spec);
    map.AddShape(pin);
  }
}

Listing 8: Pin Generation

The next step is to add the methods for creating the default Bing Maps geocoded pin:

function AddRegularGeocode(address)
{
  map.Find(null, address, null, null, 0, 10, false, false, false, true, ProcessResults)
}

function ProcessResults(layer, results, places, hasmore)
{
  CreatePin("Default", places[0].LatLong);
}

Listing 9: Adding a default geocoded pushpin

We need one last method to link our text box to the geocoding methods. Add the following function to respond to when the user pushes the "geocode" button:

function Geocode()
{
  var where = document.getElementById('txtWhere').value;
  AddRegularGeocode(where);
  AddRooftopGeocode(where);
}

Listing 10: The Geocode method

We now only need to figure out the AddRooftopGeocode method, which will be our link between the server side HttpHandler and the client side Bing Maps map.

In order to connect our client side JavaScript to our server side call to the MapPoint Web Service geocoder, we need to add three more methods:

1. A mechanism for creating an XMLHttp Object to allow us to make HTTP calls.
   
   
2. A callback method to handle the response from the HTTP request
   
   
3. The AddRooftopGeocode method to make the HTTP request.
   
   

Creating an XMLHTTP object

var xmlhttp=false;
function InitXmlHttp() {
  // Attempt to initialize xmlhttp object
  try
  {
    xmlhttp = new ActiveXObject("Msxml2.XMLHTTP");
  }
  catch (e)
  {
    // Try to use different activex object
    try
    {
      xmlhttp = new ActiveXObject("Microsoft.XMLHTTP");
    }
    catch (E)
    {
      xmlhttp = false;
    }
  }
  // If not initialized, create XMLHttpRequest object
  if (!xmlhttp && typeof XMLHttpRequest!='undefined')
  {
    xmlhttp = new XMLHttpRequest();
  }
  // Define function call for when Request obj state has changed
  xmlhttp.onreadystatechange=SearchHandler;
}

The SearchHandler function

function SearchHandler()
{
  if (xmlhttp.readyState==4)
  {
    eval(xmlhttp.responseText);
  }
}

The AddRoofTopGeocode Method

function AddRooftopGeocode(address)
{       
  InitXmlHttp();      
  var msg = "GeoCodingHandler.ashx?addr="+escape(address);
  xmlhttp.open("GET", msg, true);
  xmlhttp.send(null);
}