Programming with Microsoft MapPoint Location Server, Version 1.0

Chandu Thota
Microsoft Corporation

March 2004

Applies to:

   Microsoft® MapPoint® Location Server, version 1.0

Summary: Take a first look at Microsoft MapPoint Location Server and learn how to develop powerful location-based applications and services using MapPoint Location Server and MapPoint Web Service (20 printed pages).

Contents

Introduction
MapPoint Location Server Terminology
How MapPoint Location Server Works
MapPoint Location Server Architecture
Programming with MapPoint Location Server
Conclusion

Introduction

Location-based services are services that are provided to a user based on the user's real-time location. These services can range from a simple service, such as listing nearby restaurants, to more complex features, such as analyzing real-time traffic conditions and finding the least-congested route to a destination. For location-based services to work, a locatable device, such as a wireless mobile device, is usually necessary to identify the geographical location of the user. In essence, location-based services are all about identifying the best and nearest possible service based on where the user is, in real time.

Developing location-based services conventionally is tedious and expensive because GPS hardware and software are required. But with the advent of Microsoft® MapPoint® Location Server, the need for expensive hardware and software to develop location-based services is history. Now you can develop powerful real-time, location-based service applications that target mobile devices such as Smartphones and Pocket PCs by using MapPoint Location Server and the Microsoft .NET Compact Framework.

MapPoint Location Server Terminology

Before we delve into the details of how MapPoint Location Server works, you'll need to familiarize yourself with the following terminology:

• mobile operator
  A company that provides communication services for mobile devices such as cell phones and pagers.
• provisioning
  The process of registering an enterprise user with MapPoint Location Server. A user who is registered with MapPoint Location Server is also called a provisioned user. Each provisioned user must have an associated mobile device number that is used by the mobile operator to identify the real-time location of the user.
• provider
  A software plug-in for MapPoint Location Server, developed to communicate with a network carrier, such as a cell phone company, either to obtain the location of a mobile device or to send a Short Message Service (SMS) message to a mobile device. Providers that are used for getting the location of a mobile device are called location providers. Providers that are used for sending SMS messages are called notification providers. Location and notification providers are unique to each mobile operator.
• locatable contact
  A provisioned user who can be contacted by another provisioned user.
• notification
  An SMS or e-mail message that is sent to a provisioned user's mobile device when another user attempts to locate her. A notification is also sent the user is added to another user's contact list.
• Find Nearby category
  A group of points of interest of the same type, such banks or restaurants. You can use the MapPoint Web Service Find service to find members of a particular Find Nearby category within a specified proximity and render them on a map.

How MapPoint Location Server Works

As mentioned earlier, MapPoint Location Server does not require GPS-like hardware to get real-time locations; instead, it locates a provisioned user's mobile device by communicating with a mobile operator. In a typical scenario, a user requests his position using a mobile device equipped with a client that communicates with MapPoint Location Server. When MapPoint Location Server receives the request from the client, it identifies the mobile operator (the location service provider in Figure 1) for the user and sends a location request to the mobile operator. The mobile operator responds by sending back the real-time location of the user, expressed as latitude and longitude coordinates. MapPoint Location Server then requests a map from MapPoint Web Service to display the user's real-time location. All communications that are specific to a mobile operator are hidden from end-users and developers. Thus, MapPoint Location Server works as an aggregator for mobile operators by abstracting implementation details that are specific to the mobile operator to obtain a real-time location. Once the location is obtained, it can be used for many purposes, such as finding nearby points of interests, finding nearby contacts and so on. Figure 1 illustrates how MapPoint Location Server works.

Figure 1. Typical user scenario

The accuracy of the locations returned by mobile operators differs, depending on the technology they use to locate mobile devices. The following table provides an overview of technologies used by network carriers and approximate location accuracy of each method.

Table 1. Location accuracy

MapPoint Location Server Architecture

MapPoint Location Server has three core components:

• MapPoint Location Server Web Service
• MapPoint Location Server database
• MapPoint Location Server providers

This section discusses each component in detail.

For development and testing purposes, you may want to install all MapPoint Location Server components on a single computer located behind a firewall, as shown in Figure 2. However, this is not recommended for a production system. In a production system, the MapPoint Location Server database should be installed on a computer behind an inner firewall. For more information, see the "Microsoft MapPoint Location Server Administrator's Guide, Version 1.0."

Figure 2. Single-computer deployment

MapPoint Location Server Web Service

MapPoint Location Server Web Service is a programmable Web service that developers can use to build client applications for variety of platforms, such as Microsoft Windows®, Web, and mobile devices. This Web service exposes an API for finding the locations of users and their contacts, finding points of interest, and managing contacts. Unlike MapPoint Web Service, which is hosted by Microsoft, MapPoint Location Server Web Service is hosted within the enterprise. You must have Internet Information Services (IIS) version 5.0 or later with Secure Sockets Layer (SSL) enabled to host this Web service.

Important  MapPoint Location Server Web Service is always hosted with Secure Socket Layers (SSL) enabled. In order to communicate with MapPoint Location Server Web Service, your client (Pocket PC, Pocket PC emulator, or development computer) must be able to establish a trusted connection. A client can establish a trusted connection when MapPoint Location Web Service is deployed with a root certificate issued by authorities such as Verisign, Cybertrust, Thawte, or Entrust. However, during development, if MapPoint Location Server Web Service is deployed using a certificated generated by your enterprise, you must install the certificate on the client manually. For more information, see the Microsoft Knowledge Base article, Sample to Add Root Certificates to Pocket PC 2002.

MapPoint Location Server Database

The MapPoint Location Server database is a Microsoft SQL Server™ 2000 database that is used for storing information about provisioned users, contacts, and mobile operators along with data related to Find Nearby categories. MapPoint Location Server exposes a set of rich management APIs for performing tasks such as provisioning users, managing contacts, and managing Find Nearby categories.

You'll need SQL Server 2000 with Service Pack 3 (SP3) or later to install the MapPoint Location Server database.

MapPoint Location Server Providers

MapPoint Location Server providers are software plug-ins that are required for communication with mobile operators. Usually, there is a location provider and a notification provider for each mobile operator. Because the implementation of location and notification providers is unique to each mobile operator, MapPoint Location Server does not expose APIs for developing location or notification providers.

**Note  **MapPoint Location Server includes a demonstration location provider for testing purposes. This demo provider simulates real-time location scenarios against a configurable file with phone numbers and associated latitude and longitude pairs. For more information about the demo provider, see the Microsoft MapPoint Location Server Administrator's Guide, Version 1.0, which is included with MapPoint Location Server.

Programming with MapPoint Location Server

MapPoint Location Server exposes APIs for building location-based applications as well as server-management-and-administration applications. You develop location-based applications by using MapPoint Location Server Web Service, and you develop management-and-administration applications by using the MapPoint Location Server management API. The Web service and the management API both expose much of the same functionality, but with one important difference: the Web service runs under the context of the current user, whereas the management API runs under the context of the administrator.

You'll need the following software to develop applications for MapPoint Location Server:

• Microsoft Visual Studio® .NET 2003
• Microsoft .NET Compact Framework with Service Pack 2 (SP2) or later
• Microsoft .NET Framework, version 1.1 or later

Programming with MapPoint Location Server Web Service

MapPoint Location Server Web Service provides APIs for functionality such as finding real-time locations, finding nearby points of interest, finding contacts, adding and removing contacts, and so on.

Because this Web service is hosted within your enterprise, you need your network domain credentials to access it.

In the following sections we'll explore the major API features of MapPoint Location Server Web Service.

**Note  **The sample code in this section assumes that you have added the Web Reference for MapPoint Location Web Service. The name of the proxy class that is generated by Microsoft Visual Studio .NET is assumed to be LocationServiceSoap.

Finding a Real-Time Location

MapPoint Location Web Service exposes the GetPositions method, which you can use to request a real-time location. You need to pass the domains and aliases of the users whose location you want to find as an argument to this method. When a location request succeeds, GetPositions returns an instance of the PositionResults class, which contains the positions for the domains and aliases passed to the method. The PositionResults class instance contains a property that exposes an array of Position class instances contains the position information expressed as latitude and longitude coordinates. The order of Position array elements corresponds to the order of the domain and alias pairs that are passed to this method. The following code snippet shows how to invoke the GetPositions method.

[Visual Basic]
    'Create an instance of the LocationServiceSoap proxy class. 
    Dim MyLocationService As New LocationServiceSoap
    'Create an instance of the NetworkCredential class
    'and add the credentials required to access the Web service. 
    Dim MyCredentials As _
        New NetworkCredential ("user", "password", "domain")
    MyLocationService.Credentials = MyCredentials
    Try
        'Get the positions from the GetPositions method.
        Dim MyPositionResults As PositionResults = _
         MyLocationService.GetPositions(New String() {"domain\user"})
        'Process the positions here. 
    Catch ex As System.Web.Services.Protocols.SoapException
        'Process exceptions here. 
    End Try

 
[C#]
  //Create an instance of the LocationServiceSoap proxy class. 
  LocationServiceSoap MyLocationService = new LocationServiceSoap(); 
  //Create an instance of the NetworkCredential class 
  //and add the credentials required to access the Web service. 
  NetworkCredential MyCredentials = 
         new NetworkCredential("user", "password", "domain"); 
  MyLocationService.Credentials = MyCredentials;
  try
  { 
   //Get the positions from the GetPositions method. 
   PositionResults MyPositionResults = 
      MyLocationService.GetPositions(new string[] {@"domain\user"});
   //Process the positions here. 
  } 
  catch(System.Web.Services.Protocols.SoapException MyException)
  { 
   //Process exceptions here. 
  }

MapPoint Location Server Web Service also exposes the GetPositionsAsync method and a corresponding GetPositionsAsyncResults method for invoking asynchronous location requests. The difference between these methods and the proxy-generated asynchronous methods (BeginGetPositions and EndGetPositions) generated by Visual Studio .NET is that the Visual Studio .NET-generated methods run the invocation process on a background thread to free up the UI thread, which keeps HTTP connection open until the response from MapPoint Location Server Web Service is complete. The GetPositionsAsync method closes the HTTP connection as soon as the request is complete, making the request and response truly asynchronous. The GetPositionsAsync method may be required with mobile operators that cannot locate a mobile device when an HTTP connection is open. If you are working with a mobile operator that does not have this issue and if you are developing your client application using the asynchronous model, use the asynchronous methods generated by Visual Studio .NET.

This GetPositions method can be used both for users who want to get their own locations and the locations of their contacts.

Adding and Removing Contacts

MapPoint Location Web Service offers two methods, AddContact and DeleteContact, which can be used to add and remove contacts for provisioned users. You can use the FindProvisonedUser method to look up the provisioned users within your organization so that you can to add them to your contact list. Note that although you can add a contact your contact list, you can locate that contact only if he or she grants you permission to do so. This explicit opt in model is a privacy feature of MapPoint Location Server.

The following code snippet shows how to add a contact to your contact list.

[Visual Basic]
    'Create an instance of the LocationServiceSoap proxy class.
    Dim MyLocationService As New LocationServiceSoap
    'Create an instance of the NetworkCredential class
    'and add the credentials required to access the Web service.
    Dim MyCredentials As _
           New NetworkCredential ("user", "password", "domain")
    MyLocationService.Credentials = MyCredentials

    Try
        'Add a new contact for the current user.
        Dim MyLocatableContact As LocatableContact = _
           MyLocationService.AddContact("domain\contactuser", _
                                         True, _
                                         True)

    Catch MyException As SoapException
        'Process exceptions here.
        If ((Not MyException.Detail Is Nothing) And _
            (Not MyException.Detail("Type") Is Nothing)) Then
            MessageBox.Show(MyException.Detail("Type").InnerText)
        End If

    Finally
        'Clean up.
        MyLocationService = Nothing
    End Try


[C#]
  //Create an instance of the LocationServiceSoap proxy class.
  LocationServiceSoap MyLocationService = new LocationServiceSoap();
  //Create an instance of the NetworkCredential class
  //and add the credentials required to access the Web service.
  NetworkCredential MyCredentials = 
        new NetworkCredential("user", "password", "domain");
  MyLocationService.Credentials = MyCredentials;

  try
  {
   //Add a new contact for the current user.
   LocatableContact MyLocatableContact =
       MyLocationService.AddContact(@"domain\contactuser", 
                                    true, true);
  }
  catch(SoapException MyException)
  {
   //Process exceptions here.
   if (MyException.Detail != null && 
       MyException.Detail["Type"] != null)
    MessageBox.Show(MyException.Detail["Type"].InnerText);
  }
  finally
  {
   //Clean up.
   MyLocationService = null;
  }

Finding Nearby Points of Interest

MapPoint Location Web Service exposes the GetNearbyCategories method, which returns Find Nearby categories that you can use to find nearby points of interest. Find Nearby categories are groups of points of interest of the same type. A system administrator can define specific Find Nearby categories that are useful for provisioned users. You can use this list of categories to search for points of interest that are close to your location. The following code shows how to retrieve Find Nearby categories.

[Visual Basic]
    'Create an instance of the LocationServiceSoap proxy class.
    Dim MyLocationService As New LocationServiceSoap
    'Create an instance of the NetworkCredential class 
    'and add the credentials required to access the Web service.
    Dim MyCredentials As 
        _ New NetworkCredential ("user", "password", "domain")

    MyLocationService.Credentials = MyCredentials

    Try
        'Get the Find Nearby categories.
        Dim MyFindNearbyCategories As FindNearbyCategory()_ 
                      = MyLocationService.GetNearbyCategories()
        Dim MyFindNearbyCategory As FindNearbyCategory
        For Each MyFindNearbyCategory In MyFindNearbyCategories
            Console.WriteLine(MyFindNearbyCategory.KeyName)
        Next

    Catch MyException As SoapException

        'Process exceptions here.
        If ((Not MyException.Detail Is Nothing)_ 
        And (Not MyException.Detail("Type") Is Nothing)) Then
            MessageBox.Show(MyException.Detail("Type").InnerText)
        End If
    End Try


[C#]
  //Create an instance of the LocationServiceSoap proxy class.
  LocationServiceSoap MyLocationService = new LocationServiceSoap();
  //Create an instance of the NetworkCredential class 
  //and add the credentials required to access the Web service.
  NetworkCredential MyCredentials = 
          new NetworkCredential("user", "password", "domain");
  MyLocationService.Credentials = MyCredentials;

  //Get the Find Nearby categories.
  try
  {
   FindNearbyCategory[] MyFindNearbyCategories = 
                MyLocationService.GetNearbyCategories();

   foreach(FindNearbyCategory MyFindNearbyCategory in 
                                          MyFindNearbyCategories)
   {
    Console.WriteLine(MyFindNearbyCategory.KeyName);
   }
  }
  catch(SoapException MyException)
  {
   //Process exceptions here.
   if (MyException.Detail != 
   null && MyException.Detail["Type"] != null)
    MessageBox.Show(MyException.Detail["Type"].InnerText);
  }
  finally
  {
   //Clean up.
   MyLocationService = null;
  }

Programming with the MapPoint Location Server Management API

You use the MapPoint Location Server management API to develop server-side applications for MapPoint Location Server. Server-side applications include applications for provisioning users within an enterprise, automating adding and removing contact lists for provisioned users, removing provisioned users, and so on. Note that the management API does not expose a real-time location API.

To program with the management API, you need to add the following assemblies as references to your project:

• Microsoft.MapPoint.LocationServer.Types.dll—Contains MapPoint Location Server data types.
• Microsoft.MapPoint.LocationServer.Management.dll—Contains classes that provide methods for managing MapPoint Location Server. In this assembly, the type ServerAPI exposes methods to manage MapPoint Location Server.
• Microsoft.MapPoint.LocationServer.Core.dll—Contains classes that are required by the management API types. This assembly should be used only to add as a reference to your project; do not use types from this assembly directly in your source code.

In the following sections we'll explore the major API features of the MapPoint Location Server management API.

**Note  **The sample code in this section assumes that you have imported the following namespaces in your code:

• Microsoft.MapPoint.LocationServer.Management
• Microsoft.MapPoint.LocationServer.Types

**Tip  **If you are using the ServerAPI class to develop applications for MapPoint Location Server, make sure to invoke the Initialize method before calling any other methods of the ServerAPI class. This method call is required to establish a connection to the MapPoint Location Server database.

Provisioning Users

The ServerAPI class in the Microsoft.MapPoint.LocationServer.Management.dll assembly exposes the method AddUser, which is used to provision users for MapPoint Location Server. This method takes a LocatableUser instance as an input parameter. A LocatableUser instance is an object representation of a domain user with a unique locatable endpoint (that is, a phone number). The following code sample shows how to provision a user.

[Visual Basic]
    'Create a new instance of the ServerAPI class.
    Dim MyServerAPI As New ServerAPI

    Try
        'Create a new instance of the LocatableUser class.
        Dim NewUser As New LocatableUser
        'Set the domain and alias.
        NewUser.DomainAlias = "domain\user"
        'Set the culture name.
        NewUser.CultureName = "en-US"
        'Set the locatable endpoint (the user's mobile device number).
        NewUser.LocatableEndpoint = _
              New LocatablePhoneNumber("001", "111", "1111111")
        'Set the location provider name (you can get the name from your 
        'system administrator).
        NewUser.LocationProviderName = "Your Location Provider Name"
        'Set the notification provider name
        '(you can get the name from your system administrator).
        NewUser.NotificationProviderName = _
                  "Your Notification Provider Name"
        'Set the notification end point
        '(an e-mail address or a mobile device number).
        NewUser.NotificationEndpoint = "user email address"

        'Initialize the database connection for ServerAPI operations.
        MyServerAPI.Initialize("Your SQL Server Name", _
                               "LocationServerDB")
        'Add a domain user to MapPoint Location Server.
        MyServerAPI.AddUser(NewUser)
    Catch MyException As Exception
        'Process exceptions here.
        Console.WriteLine(MyException.GetType().Name)
    Finally
        'Clean up.
        MyServerAPI = Nothing
    End Try


[C#]
  //Create a new instance of the ServerAPI class.
  ServerAPI MyServerAPI = new ServerAPI();
  try
  {
   //Create a new instance of the LocatableUser class.
   LocatableUser NewUser = new LocatableUser();
   //Set the domain and alias.
   NewUser.DomainAlias = @"domain\user";
   //Set the culture name.
   NewUser.CultureName = "en-US";
   //Set the locatable endpoint (the user's mobile device number).
   NewUser.LocatableEndpoint = 
          new LocatablePhoneNumber("001", "111", "1111111");
   //Set the location provider name
   //(you can get the name from your system administrator).
   NewUser.LocationProviderName = "Your Location Provider Name";
   //Set the notification provider name
   //(you can get the name from your system administrator).
   NewUser.NotificationProviderName = 
                  "Your Notification Provider Name";
   //Set the notification endpoint
   //(an e-mail address or a mobile device number).
   NewUser.NotificationEndpoint = "user email address";
   //Initialize the database connection for ServerAPI operations.
   MyServerAPI.Initialize("Your SQL Server Name", "LocationServerDB");
   //Add a domain user to MapPoint Location Server.
   MyServerAPI.AddUser(NewUser);
  }
  catch(Exception MyException)
  {
   //Process exceptions here.
   Console.WriteLine(MyException.GetType().Name);
  }
  finally
  {
   //Clean up.
   MyServerAPI = null;
  }

Managing Provisioned Users

The ServerAPI class also provides methods for managing users who are already provisioned. You can use the DeleteUser method to delete a provisioned user from MapPoint Location Server and you can use the UpdateUser method to update the properties of a provisioned user.

Managing Contacts for Provisioned Users

Using the ServerAPI class, you can add, remove, and update contacts for provisioned users. The capability to manage contacts is extremely useful if you are setting up a standard contact list for all provisioned users within your enterprise. The ServerAPI class exposes the methods AddContact, UpdateContact, and DeleteContact for adding, updating, and deleting contacts, respectively. As mentioned earlier, the primary difference between the MapPoint Location Server Web Service methods and the ServerAPI class methods is that the Web service method calls run in the current user's context and the ServerAPI methods calls run under the administrator's context. Therefore, when you call the AddContact method using the MapPoint Location Server Web Service you are adding a contact to your own contact list, whereas when you call the AddContact method of the ServerAPI class, you are adding a contact for the provisioned user whom you specify as an argument to this method.

The following code sample shows how to call the AddContact method to add a contact for a provisioned user.

[Visual Basic]
    'Set SQL Server instance and database names. 
    Const server As String = "Your SQL Server Name"
    Const database As String = "LocationServerDB"
    'Create a new instance of the ServerAPI class. 
    Dim MyServerAPI As New ServerAPI
    Try
        'Call the Initialize method. 
        Call MyServerAPI.Initialize(server, database)
    Catch MyException As SqlConnectionFailedException
        'Process exceptions here.
    End Try
    'If the call to Initialize is successful. 
    Dim MyDomainAlias As String = "domain\user"
    Dim NewContact As String = "domain\newcontact"
    Try
        Dim MyLocatableContact As LocatableContact = _
              MyServerAPI.AddContact(MyDomainAlias, _
                                     NewContact, True, True)
        Console.WriteLine(MyLocatableContact.DisplayName)
    Catch MyException As Exception
        'Process exceptions here. 
    End Try


[C#]
  //Set the SQL Server instance and database instance names. 
  const string server = "your sql server name"; 
  const string database = "LocationServerDB"; 
  //Create a new instance of the ServerAPI class. 
  ServerAPI MyServerAPI = new ServerAPI(); 
  try 
  { 
   //Call the Initialize method.
   MyServerAPI.Initialize(server, database); 
  } 
  catch(SqlConnectionFailedException MyException) 
  {
   //Process exceptions here. 
  }
   
  //If the call to Initialize is successful. 
  string MyDomainAlias = @"domain\user"; 
  string NewContact = @"domain\newcontact"; 
  try 
  { 
   LocatableContact MyLocatableContact =                                
                MyServerAPI.AddContact(MyDomainAlias, 
                                       NewContact, true, true);
   Console.WriteLine(MyLocatableContact.DisplayName); 
  }
  catch(Exception MyException) 
  {
   //Process exceptions here. 
  }

Managing Find Nearby Categories

Using the ServerAPI class you can add, update, and remove Find Nearby categories that are appropriate for your enterprise. The ServerAPI class exposes the methods AddNearbyCategory, UpdateNearbyCategory, and RemoveCategory for adding, updating, and removing Find Nearby categories, respectively.

The following code sample shows how to add Find Nearby categories.

[Visual Basic]
    'Create a new instance of the ServerAPI class.
    Dim MyServerAPI As New ServerAPI
    Try
        'Initialize the database connection for ServerAPI operations.
        MyServerAPI.Initialize _
        ("Your SQL Server Name", "LocationServerDB")

        'Create a new instance of the FindNearbyCategory class.
        Dim category As New FindNearbyCategory
        'Set the default culture.
        category.DefaultCulture = "en-US"
        'Set the distance unit.
        category.DistanceUnit = DistanceUnit.Mile
        'Set the key name.
        category.KeyName = "MyDiningPlaces"

        'Set the localized names.
        'In this case, we have two localized names.
        'Set the name for English (US).
        Dim MyFindNearbyCategoryNames(1) As FindNearbyCategoryName
        MyFindNearbyCategoryNames(0) = New FindNearbyCategoryName
        MyFindNearbyCategoryNames(0).Culture = "en-US"
        MyFindNearbyCategoryNames(0).DisplayName = "My Dining Places"
        MyFindNearbyCategoryNames(0).DisplayDescription _
        = "My Dining Places"
        'Set the name for German (Germany).
        MyFindNearbyCategoryNames(1) = New FindNearbyCategoryName
        MyFindNearbyCategoryNames(1).Culture = "de-DE"
        MyFindNearbyCategoryNames(1).DisplayName _
        = "Meine Speisenden Pl? 
tze"
        MyFindNearbyCategoryNames(1).DisplayDescription _
        = "Meine Speisenden Pl?tze"

        'Assign the localized names to the instance of the 
        'FindNearbyCategory class.
        category.Names = MyFindNearbyCategoryNames

        'Create an instance of the FindNearbySpecification class.
        Dim MyFindNearbyCategorySpecification As New 
FindNearbySpecification
        MyFindNearbyCategorySpecification.DataSourceName _
        = "NavTech.NA"
        MyFindNearbyCategorySpecification.Filter = New FindFilter
        MyFindNearbyCategorySpecification.Filter.EntityTypeName = 
"SIC3578"
        'Assign the instance of FindNearbySpecification 
        'to the category.
        category.FindNearbySpecification = 
MyFindNearbyCategorySpecification

        'Add the category.
        MyServerAPI.AddNearbyCategory(category)

    Catch MyException As Exception
        'Process exceptions here.
        Console.WriteLine(MyException.GetType().Name)

    Finally
        'Clean up.
        MyServerAPI = Nothing
    End Try


[C#]
  //Create a new instance of the ServerAPI class.
  ServerAPI MyServerAPI = new ServerAPI();
  try
  {
   //Initialize the database connection for ServerAPI operations.
   MyServerAPI.Initialize
   ("Your SQL Server Name", "LocationServerDB");

   //Create a new instance of the FindNearbyCategory class.
   FindNearbyCategory category = new FindNearbyCategory();
   //Set the default culture.
   category.DefaultCulture = "en-US";
   //Set the distance units.
   category.DistanceUnit = DistanceUnit.Mile;
   //Set the key name.
   category.KeyName = "MyDiningPlaces";

   //Set the localized names.
   //In this case we have two localized names.
   //Set the name for English (US).
   FindNearbyCategoryName[] MyFindNearbyCategoryNames 
   = new FindNearbyCategoryName[2];

   MyFindNearbyCategoryNames[0] = new FindNearbyCategoryName();
   MyFindNearbyCategoryNames[0].Culture = "en-US";
   MyFindNearbyCategoryNames[0].DisplayName 
   = "My Dining Places";
   MyFindNearbyCategoryNames[0].DisplayDescription 
   = "My Dining Places";
   //Set the name for German (Germany).
   MyFindNearbyCategoryNames[1] = new FindNearbyCategoryName();
   MyFindNearbyCategoryNames[1].Culture = "de-DE";
   MyFindNearbyCategoryNames[1].DisplayName
   = "Meine Speisenden Pl?tze";
   MyFindNearbyCategoryNames[1].DisplayDescription 
   = "Meine Speisenden 
Pl?tze";

   //Assign the localized names to the instance 
   //of the FindNearbyCategory class.
   category.Names = MyFindNearbyCategoryNames;

   //Create a new instance of the FindNearbySpecification class.
   FindNearbySpecification MyFindNearbyCategorySpecification = new 
FindNearbySpecification();
   MyFindNearbyCategorySpecification.DataSourceName = "NavTech.NA";
   MyFindNearbyCategorySpecification.Filter = new FindFilter();
   MyFindNearbyCategorySpecification.Filter.EntityTypeName 
   = "SIC3578";
   //Assign the FindNearbySpecification to the category.
   category.FindNearbySpecification 
   = MyFindNearbyCategorySpecification;

   //Add the category.
   MyServerAPI.AddNearbyCategory(category);
    
  }
  catch(Exception MyException)
  {
   //Process exceptions here.
   Console.WriteLine(MyException.GetType().Name);
  }
  finally
  {
   //Clean up.
   MyServerAPI = null;
  }    

Conclusion

In this article, we have seen how the MapPoint Location Server works and gotten a birds-eye-view of programming with MapPoint Location Server Web Service and the MapPoint Location Server management API. The following table summarizes the functionality available through the APIs for MapPoint Location Server.

Table 2. API functionality

What we've covered in this article should be a good starting point for your foray into programming with MapPoint Location Server. For additional information about programming with MapPoint Location Server, see the following resources:

• MapPoint Location Server SDK
• MSDN BLOG for MapPoint Location Server

You can also write to me through my BLOG if you have specific programming questions about MapPoint Location Server.