Grace Qiu
Microsoft Corporation
March 2005
Applies to:
Microsoft MapPoint Location Server
Microsoft MapPoint Web Service
Summary: Learn how to create a geofence and use it in a MapPoint Location Server application.
Contents
Introduction
Geofence Applications
Creating a GeoFence
Conclusion
Resources
Introduction
With MapPoint Location Server, you can incorporate powerful location-based services into applications for mobile devices such as Pocket PCs, wireless-enabled portable computers, and Smartphones. This article introduces geofences, outlines how to use them in MapPoint Location Server applications, and shows you how to create a geofence.
A geofence is a geographical region that you define and use to trigger an event when a user enters the region. For example, you can create an application that sends an Short Message Service (SMS) message about a current sales promotion to provisioned users when they come within a one-mile radius of your store location. The following section outlines scenarios for several types of applications that include geofences and describes the features, requirements, and implementation for each one. This article assumes that you are familiar with MapPoint Location Server and MapPoint Web Service. For more information, see "Resources" later in this article.
Geofence Applications
The scenarios in this section use a circle region as the geofence, with the radius of the circle defined in miles. All scenarios assume that MapPoint Location Server is installed and running. To use MapPoint Location Server, you must have a valid MapPoint Web Service account and an account with a mobile operator that provides location services. For more information, see "Resources" later in this article.
In-Store Kiosk
A retail store installs an in-store kiosk where users can add their phone numbers to a list so they can receive SMS messages containing coupons or information about sales promotions when they are within the store's geofence. Users can also use the kiosk to stop receiving messages, or they can opt out by sending a text message or by calling the store directly.
The kiosk includes a settings page that the store manager can use to set the geofence radius, update the SMS message of the day, and specify how often the application runs. Optional features of the kiosk include maps, driving directions, and "find nearby" functionality, such as the capability to find nearby bank machines and gas stations.
Requirements
The kiosk application requires a database to store information about users who sign up for the service. The information includes a telephone number, a unique alias, the latitude, longitude of the user, a flag to indicate whether the user wants to receive messages, and a flag to indicate whether a coupon has already been sent (because duplicate SMS messages can annoy users). This database can be installed on the computer that is running MapPoint Location Server or on another server that MapPoint Location Server can access.
Implementation
The application runs periodically, based on a frequency that the store manager specifies. When the application runs, it calls the MapPoint Location Server LocationServiceSoap.GetPositions method to get the current location for all users by passing an array of aliases (see the code example later in this section), and then determines which users are within the store's geofence.
There are two ways to determine whether a user is within the geofence:
- Call the MapPoint Web Service CalculateSimpleRoute or CalculateRoute method by passing the user's location and the store's location to determine the user's distance from the store. If the distance returned is smaller than the radius of the geofence, the user is within the geofence.
- Save the latitude and longitude of all users' current positions in the user database and then perform a proximity search to find only the users who are within the geofence. This method requires a stored procedure for the user database that performs a proximity search. For more information, see Implementing a Proximity Search with SQL Server 2000.
After the application determines which users are within the geofence, the application can send an SMS message to the users' phones. Finally, the application updates the flag in the user database to indicate which users have received the SMS message for the day.
The following code example illustrates how to determine a user's location.
[Visual Basic]
'Create an instance of the LocationServiceSoap proxy.
Dim MyLocationService As New LocationServiceSoap
'Create and add the credentials required to access MapPoint 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
'Exception processing goes here.
End Try
[C#]
//Create an instance of the LocationServiceSoap proxy.
LocationService MyLocationService = new LocationService();
//Create and add the credentials required to access
//MapPoint Web Service.
NetworkCredential MyCredentials = new NetworkCredential("user",
"password", "domain");
MyLocationService.Credentials = MyCredentials;
try
{
//Get the position from the GetPositions method.
PositionResults MyPositionResults =
MyLocationService.GetPositions(new string[] {@"domain\user"});
//Process the positions here.
}
catch(System.Web.Services.Protocols.SoapException MyException)
{
//Your exception processing goes here.
}
Mobile Device Application with User-Defined Geofence
A retail chain distributes a mobile device application (for Smartphone or Pocket PC) to users so they can receive coupons and sales promotions from stores that are within the user's geofence. In this case, each user defines the geofence for himself or herself.
The application includes a settings page so that the user can set the geofence radius, turn the application off or on, and specify how often the application runs. To add security, the company can require users to log on before using the service. In this case, the application must include a logon page.
Requirements
This application has the following requirements:
- A custom data source that contains store addresses, contact information, and SMS message. This data source must be uploaded to the MapPoint Web Service servers by using either the tools on the Customer Services site (CSS) or the Customer Data Service API.
- A database that contains information about users who sign up for the service. The information includes a telephone number, a unique alias, latitude, longitude, and a flag to indicate whether a coupon has already been sent. If users are required to log on before accessing MapPoint Location Server, the user database should also include a column for a password. This database can be installed on the computer that is running MapPoint Location Server or on another server that MapPoint Location Server can access.
Implementation
When the user turns the application on, it runs periodically, based on the frequency that the user specifies. The application calls the MapPoint Location Server LocationServiceSoap.GetPositions method (see the example code earlier in this article), passing the user's alias to determine the user's location. Once the user's location is obtained, the latitude and longitude is passed to the MapPoint Web Service FindNearby method along with the geofence radius to find stores that are within the user's geofence. The results that the application returns include the SMS message for each store along with its address and contact information.
After the results from the call to FindNearby are returned, there are multiple ways to display the information to the user. For example, the application can display a short message to alert the user that there are SMS messages from the stores nearby, or display a list of SMS messages.
Mobile Device Application with Store-Defined Geofence
A retail chain distributes a mobile device (Smartphone or Pocket PC) application to users that they can use to receive coupons and sales promotions when they enter a store's geofence.
This scenario is similar to the previous one but with the following differences:
- A geofence field must be added to the store's data source because each store has its own geofence radius.
- After the FindNearby method returns the list of stores, the application must filter the list to return only stores with a geofence that includes the user. Results are filtered by comparing the proximity distance of each store (the distance between the user and the store) to each store's geofence radius.
Fleet-Management Application
A delivery company creates an application that dispatchers can use to improve delivery times by locating all of the delivery trucks that are within a certain distance of the customer's location.
The application includes a form in which the dispatcher types the customer's location and the geofence radius and specifies whether to locate either a specific driver by alias or all drivers. After locating the drivers, the dispatcher can select a driver who is within the geofence by clicking the pushpin on the map that represents the driver's location or by selecting a driver from the list. The application can also include the following capabilities:
- Display the driver's location on the map.
- Get driving direction from the driver's location to the customer's location.
- Send an SMS message from the dispatcher to the driver.
Requirements
The fleet-management application requires that each delivery driver have a phone that is provisioned for MapPoint Location Server by using a unique alias.
Implementation
When the dispatcher types in the customer's location, the application finds the location and displays it on a map by using the MapPoint Web Service FindAddress and GetMap methods. If the customer's address is successfully found and displayed, the application searches for drivers by calling the MapPoint Location Server LocationServiceSoap.GetPositions method (see example code in earlier in this article). The application then displays the list of drivers and adds pushpins to the map to represent the drivers’ locations. In addition to the drivers' locations, the map also displays the customer's location and a shaded circle representing the geofence with the customer's location at the center. This way, the dispatcher can tell at a glance which drivers are within the customer's geofence, as shown in Figure 1.
.gif)
Figure 1. Map with geofence
At this point, the dispatcher can select a driver from the result list or click the pushpin that represents the driver to get maps or driving directions, or to send an SMS message to the driver. To determine a driver's distance from the customer, the application can call the MapPoint Web Service CalculateSimpleRoute or CalculateRoute method by passing the driver's and the customer's locations. This way, the dispatcher can select the driver who is closest to the customer to optimize the delivery time.
Creating a Geofence
The following code example shows how to create an ArrayList object containing the points for the geofence (circle region) boundary. You can then draw a geofence on a map by passing the ArrayList to the MapPoint Web Service ConvertToPoint method and use the two-dimensional drawing libraries of the Microsoft .NET Framework (System.Drawing.Drawing2D) to draw the region.
[Visual Basic .NET]
'Define the geofence (the radius of your region).
Dim radius as double = .5
Dim lls As New ArrayList
Dim ll As LatLong
Dim a As Double
Dim fudge As Double = Math.Cos(pnt.Latitude * (Math.PI / 180))
'Create an ArrayList of LatLong coordinates that represents
'the points on the circle that you want to draw.
For a = 15 To 360 Step 15
Dim radians As Double
radians = a * (Math.PI / 180)
ll = New LatLong
ll.Latitude = pnt.Latitude + (Math.Sin(radians) * radius)
ll.Longitude = pnt.Longitude + ((Math.Cos(radians) * _
radius) / fudge)
lls.Add(ll)
Next
[C#]
//Define the geofence (the radius of your region).
double radius = 0.5;
ArrayList lls = new ArrayList();
LatLong ll;
double a;
double fudge = Math.Cos(pnt.Latitude * (Math.PI / 180));
// Create an ArrayList of LatLong coordinates that represents the
// points of your circle that you want to draw.
for (int a = 15; a <= 360; a += 15)
{
double radians;
radians = a * (Math.PI / 180);
ll = new LatLong();
ll.Latitude = pnt.Latitude + (Math.Sin(radians) * radius);
ll.Longitude = pnt.Longitude + ((Math.Cos(radians) * radius) / fudge);
lls.Add(ll);
}Conclusion
A geofence is a powerful element that enhances your MapPoint Location Server applications, so that you can do more than just find users and locations. Because you can use a geofence to trigger events when a user enters a region, you can use it for targeted sales promotions, coupons to drive in-store traffic, or to optimize your fleet-management application.
Resources
To learn more about MapPoint Location Server and MapPoint Web Service, see the following resources:
Grace Qiu is a Web Development Engineer in the Microsoft MapPoint Business Unit, and is a member of the Professional Services team.