Programming with Microsoft MapPoint Location Server, Version 1.0
Chandu Thota takes a first look at Microsoft MapPoint Location Server anddemonstrates how to develop powerful location-based applications and services usingMapPoint Location Server and MapPoint Web Service
Chandu Thota
Microsoft Corporation
March 2004
Applies to:
Microsoft® MapPoint® Location Server, version 1.0
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
Technology |
Approximate location accuracy |
Cell Sector |
Urban areas: 1 – 3 kilometers Suburban
areas: 3 - 20 kilometers |
Assisted GPS (AGPS) |
10 – 50 meters |
Time Difference of Arrival (TDOA) |
100 meters |
Angle of Arrival (AOA) |
100 meters |
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
Functionality |
MapPoint Location Server
Web Service |
MapPoint Location Server
management API |
Get real-time location |
Y |
N |
Manage contacts |
Y |
Y |
Manage Find Nearby categories |
N |
Y |
Provision and manage users |
N |
Y |
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:
You can also write to me through my BLOG if you have specific
programming questions about MapPoint Location Server.
Credits: MapPoint User Experience Team
Chandu has published several articles related to the Microsoft .NET Framework and founded an online .NET Web Services portal, http://www.esynaps.com. He is also a co-author of the books Understanding the .NET Framework and Building an ASP.NET Intranet, both published by Apress.