Creating Geocoding Exceptions for MapPoint Web Service Applications

IMPORTANT: MapPoint Web Service was retired on November 18, 2011. Please see Bing Maps for a list of current Bing Maps APIs.

Steven Pushee
Microsoft Corporation

June 2005

Applies to:

Microsoft MapPoint Web Service

Summary: Learn how to create a geocoding exceptions file for instances when you want to override a geocode provided by MapPoint Web Service. (6 printed pages)

Contents

Introduction
Creating a Geocoding Exceptions List
Storing a Geocoding Exceptions List
Using GeoException Objects in an Application
Conclusion

Introduction

In many MapPoint Web Service applications, a user supplies a postal code or city name, which is then sent to MapPoint Web Service to be geocoded (assigned latitude and longitude coordinates). At times, you may need to override the geocode provided by MapPoint Web Service or provide a geocode for an entity that the geocoder does not recognize. For example, a user might supply St. Thomas as a city name when searching for St. Thomas the island, not knowing that Charlotte Amalie is the main city on St. Thomas.

You can work around this issue by using a GeoException. A GeoException is an object consisting of a name (usually a postal code or city) and its corresponding latitude and longitude. By compiling a list of GeoException objects and making that list available in your application, you can ensure that your application returns the results that you expect.

This article describes how to create a geocoding exceptions list as an XML document, make the list available in your application, and implement geocoding exceptions in your application.

This article assumes that you are already familiar with the MapPoint Web Service SOAP API and MapPoint Web Service in general. For more information about MapPoint Web Service or to sign up for a free evaluation account, visit the MapPoint Web Service Web site. For more information about programming with MapPoint Web Service, see the MapPoint Web Service SDK.

Creating a Geocoding Exceptions List

A common method of creating an exceptions list is to create an XML file, which you then add to your project.

The following example shows the contents of an XML file that contains a list of GeoException objects.

<GeoExceptions>
   <CorrectedLocations>
      <GeoLocation>
         <Name>03755</Name>
         <LatLong>
            <Latitude>43</Latitude>
            <Longitude>-72</Longitude>
         </LatLong>
      </GeoLocation>
      <GeoLocation>
         <Name>Hanover, New Hampshire</Name>
         <LatLong>
            <Latitude>44</Latitude>
            <Longitude>-73</Longitude>
         </LatLong>
      </GeoLocation>
   </CorrectedLocations>
</GeoExceptions>  

To add another GeoException to the list, you simply add another GeoLocation element.

Storing a Geocoding Exceptions List

After you create the geocoding exceptions list, the next task is to store the list in a format that is easily accessible and available in your application. The Microsoft .NET Framework XmlSerializer class makes it easy to deserialize an XML document into a predefined object that can be stored at the application level and accessed from code.

The following code example defines the MapPointGeoExceptions class, whose members correspond to the XML elements illustrated in the previous section. The constructor of this class takes the XML file path as a parameter and deserializes the file into an object.

[Visual Basic .NET]
Imports System.Xml.Serialization
Imports System.IO

Public Class MapPointGeoExceptions

    Public Exceptions As GeoExceptions
    Public Sub New(ByVal GeoExceptionsFilePath As String)

        Try

            Dim strReader As New StringReader(GeoExceptionsFilePath)
            Dim XSerializer As XmlSerializer = _
New XmlSerializer(GetType(GeoExceptions))
            Me.Exceptions = XSerializer.Deserialize(strReader)
            strReader.Close()

        Catch ex As Exception
' Add exception handling here.
        End Try

    End Sub
' LocationName corresponds to the Name property of a GeoLocation
' in the XML file.
    Public Function GetLatLong(ByVal LocationName As String) As LatLong

        Try

            For Each gLocation As GeoLocation In Me.Exceptions.CorrectedLocations
                If gLocation.Name.ToUpper = LocationName.ToUpper Then _
                    Return gLocation.LatLong
                End If
            Next
            Return Nothing

        Catch ex As Exception
' Add exception handling here.
        End Try

    End Function

    Public Class GeoExceptions
        Public CorrectedLocations() As GeoLocation
    End Class

    Public Class GeoLocation
        Public Name As String
        Public LatLong As New LatLong
    End Class

    Public Class LatLong
        Public Latitude As Double
        Public Longitude As Double
    End Class

End Class

Now you have an XML file and a class in which to store the geocoding exceptions. Next, you need to determine when and how to create an instance of the class. For a Web application, this is best handled in the Application_Start method of the Global file. The following code example shows how to pass the XML to the constructor of the MapPointGeoExceptions class and store the object in the Application object of the Web application.

[Visual Basic .NET]
Sub Application_Start(ByVal sender As Object, ByVal e As EventArgs)
     Call LoadGeoExceptions()
End Sub 

    Private Sub LoadGeoExceptions()

        Try

            ' Load exceptions list.
            Dim stmReader As StreamReader = _
New StreamReader _
(Path.Combine(HttpContext.Current.Request.PhysicalApplicationPath, _
"GeoExceptions.xml"))
            Application("gblGeoExceptions") = _
New MapPointGeoExceptions(stmReader.ReadToEnd)
            stmReader.Close()

        Catch ex As Exception
' Add exception handling here.
        End Try

    End Sub

Using GeoException Objects in an Application

In a MapPoint Web Service application, a user frequently supplies a location, such as a postal code or city, which is sent to MapPoint Web Service to be geocoded. Because you already have a geocoding exceptions list stored in the Application object, your application can easily check that list to determine whether to call MapPoint Web Service for a new geocode or use the latitude and longitude coordinates from the list.

[Visual Basic .NET]
        Try

            Dim myGeoExceptions As MapPointGeoExceptions = _
CType(Application("gblGeoExceptions"), MapPointGeoExceptions)
            Dim myLatLong As MapPointGeoExceptions.LatLong = _
myGeoExceptions.GetLatLong(txtPostalcode.Text)
            If Not myLatLong Is Nothing Then
' Use the latitude and longitude from the  list.
            Else
' Add code to call MapPoint Web Service to geocode the location.
            End If

        Catch ex As Exception
' Add exception handling here.
        End Try

Conclusion

At times, you may need to provide your own geocodes to make sure that your application returns the results that you expect. Creating a geocoding exceptions list in XML format and making it available in your application is an easy-to-implement and scalable solution for these situations.

Steven Pushee is a Support Engineer in the Microsoft MapPoint Business Unit and a member of the Client Services team.