Using MapPoint Web Service in a Web Application

  • Article

Using MapPoint Web Service in a Web Application

This topic describes four different scenarios that use MapPoint Web Service to provide mapping functionality on a Web site:

  • Scenario 1 - Showing a location

  • Scenario 2 - Showing a route

  • Scenario 3 - Simple Web page without using the MapPoint Web Service cache

  • Scenario 4 - Using your own cache

Scenario 1 - Showing a location

This scenario allows the end-user to type the name of a location into a Web page, and then view a map with that location highlighted. The location could be a street address or the name of a place, such as "United States" or "Paris, France". The Web application takes information from the end-user and passes it to the appropriate method of the FindServiceSoap class (either the Find or FindAddress method). If MapPoint Web Service finds a single correct response, the Web application immediately returns a new Web page with a map. If MapPoint Web Service finds more than one match (for example "Paris" could match to "Paris, France" or "Paris, Texas"), the Web application prompts the end-user to identify the correct match, and then returns a Web page with a map.

The following diagram shows the typical interaction of the client (the end-user's Web browser), the Web server (your application), and MapPoint Web Service for this scenario:

In this example, the end-user views a Web page with a text box that allows them to enter a location to find and a button to send the request via HTTP Post (step 1). The Web page may also contain other controls, such as to identify the country within which to limit the search, the type of entity to find (for example, city, county, state, or country), or other controls that can limit the result set. The end-user types a location and clicks the button. Your Web server takes the information that the end-user posts and makes a Find SOAP request to MapPoint Web Service (step 2). MapPoint Web Service returns the possible matches as a FindResults object (step 3).

If the FindResults object contains multiple valid matches, a new HTML page is generated (step 4) that lets the end-user choose the one that is closest to what they were looking for (step 5).

Once your Web application has the Entity object that the end-user was looking for, it sends a map view of that entity, along with any other rendering options, to MapPoint Web Service using the RenderServiceSoap.GetMap method (step 6). Depending on the MapOptions.ReturnType property, either the map is returned directly, or, as in this case, a URL is returned to use in the HTML to display the map (step 7). Other information that can be returned includes an updated view of what the map is showing and hot area information for generating an image map from any pushpins you may return on the map. Your Web server then generates HTML that uses the URL and sends it back to the client (step 8).

The client renders the HTML, and when it gets to the IMG tag with the URL (that was returned by the GetMap method), it asks for the .gif file from MapPoint Web Service directly (step 9). MapPoint Web Service returns the image and the Web page is complete (step 10).

Security implications of using a returned URL

If your Web application is secure and you do not want others to see the maps that are returned, you have two options:

  • Use the SecureURL option (MapReturnType enumeration) in the MapOptions.ReturnType property for the image returned. This makes the returned URL use the SSL protocol (https:// instead of https://). MapPoint Web Service does not authenticate or authorize the end-user in this case; however, it encrypts the data sent over the wire.

  • Use the MimeData option (MapReturnType enumeration) in the MapOptions.ReturnType property for the image returned, and then return the image to the end-user directly. This allows your application to authenticate or authorize the end-user.

Scenario 2 - Showing a route

In this scenario, an end-user enters two or more locations (most likely addresses), and then sees turn-by-turn driving directions between the two locations and a map with the route highlighted. Getting a map that shows a route is very similar to any other map, but does involve additional calls to MapPoint Web Service. The following diagram shows the typical interaction and data flow using MapPoint Web Service in this scenario:

This scenario has only a few minor differences from Scenario 1. In this case, the FindServiceSoap.FindAddress method is used rather than the Find method, because the end-user is using addresses (step 2). Both of these methods return a FindResults object (step 3), and the results can be used interchangeably; you simply call the one that is needed for your particular case. The FindAddress method (or Find method) call is made several times (steps 2 and 3), once each for the beginning and end of the route, and once for each stop along the route.

After the end-user has (if necessary) chosen the correct result from the potential results (steps 4 and 5), the route must be calculated. Your Web application makes a call to the RouteServiceSoap.CalculateRoute method, passing the list of waypoints (beginning, stops, and end point) and any other route options (step 6). A set of calculated turn-by-turn instructions is returned (step 7). The Web application makes a call to the RenderServiceSoap.GetMap method, including the route to highlight (step 8). The GetMap method returns a URL to the image (step 9), along with additional information about the map, such as the returned MapViewRepresentations object and the MIME Type of the resulting image.

The Web application then generates the HTML for the route page that includes the turn-by-turn instructions, and an IMG tag with the URL returned from the GetMap method (step 10).

The client then renders the HTML, which uses the URL in the IMG tag to return the actual map (steps 11 and 12).

Caching

Both Scenarios 1 and 2 require MapPoint Web Service to cache information that you have sent it. It is important to understand how the MapPoint Web Service caching works and what the limitations of the caching are.

When you call the RenderServiceSoap.GetMap method, one of the options you can specify is how you want the map returned. You do this by using the MapOptions.ReturnType property passed in the MapSpecification.Options property. The MapOptions.ReturnType property can be set to one of three values: ReturnUrl, ReturnSecureUrl, or ReturnImage (MapReturnType enumeration). A value of ReturnImage means that the image is returned directly as a .gif file (in the MimeData.Bits property returned in the MapImage.MimeData property). A value of ReturnUrl or ReturnSecureUrl means that the image is returned simply as the URL to the cached image (in the MapImage.Url property). In all cases, other information in the MapImage object is also returned (for example, an array of HotArea[] objects for creating image maps and the map view).

If you choose to have the GetMap method return the map as a URL, the MapPoint Web Service servers (which normally do not store state) actually generate the map and then cache the .gif file until you (or your client) use the URL to get the map. MapPoint Web Service does not indefinitely store the cached .gif file. The map is stored for 5 minutes or until the URL has been accessed 10 times, whichever occurs first. After 5 minutes or 10 cache hits, a different bitmap is returned that states that the session has timed out.

Important You must design your Web pages such that when an end-user refreshes the page, the page repopulates the MapPoint Web Service cache by calling the GetMap method again; otherwise, the end-user does not receive maps on subsequent views (for example, after 5 minutes or 10 hits). You can do this by having your page include a script (for example, an ASP.NET page) that makes the SOAP calls to generate the map.

Scenario 3 - Simple Web page without using the MapPoint Web Service cache

You may not want to be constrained by the MapPoint Web Service caching or security limitations. It is possible to create maps without using the MapPoint Web Service URL mechanism. For example, the following diagram shows the steps for creating a Web page that shows a map (similar to Scenario 1), but requests a map image rather than a URL in the call to the GetMap method:

In this scenario, your Web application creates its own IMG tag that includes parameters for pushpins and view, and the path points to a separate page on your site (returned as part of step 6). You decide which parameters are necessary to pass through the URL based on the exact details of your application. For example, you could pass the latitude, longitude, and scale of a map view, as in the following code (assumes that you are using ASP.NET).

[Visual Basic]

MapImage.ImageUrl = "RenderMap.aspx?Lat=" & MyLat & "&Long;=" & MyLong & "Scale=" & MyScale
>


[C#]
 
MapImage.ImageUrl = "RenderMap.aspx?Lat=" + MyLat + "&Long;=" + MyLong + "Scale=" + MyScale;

Your application may require more information than this (for example, identifying the pushpins to display or the map style to use).

In the next page (defined as RenderMap.aspx in the previous code snippet), your application uses the information from the parameters to request the .gif file from MapPoint Web Service with the GetMap method, and sets the MapOptions.ReturnType property to ReturnImage (MapReturnType enumeration) to request the .gif file directly.

The final .gif file image is returned to the end-user (step 10) with code similar to the following (this assumes that you are using ASP.NET).

[Visual Basic]

Response.Clear
   Response.ContentType = myImage.MimeData.MimeType
   Response.BinaryWrite(myImage.MimeData.Bits)
   Response.End
   


[C#]

Response.Clear;
   Response.ContentType = myImage.MimeData.MimeType;
   Response.BinaryWrite(myImage.MimeData.Bits);
   Response.End;

Scenario 4 - Using your own cache

Scenario 3 introduces its own limitations. Because the call to the GetMap method is not made before the HTML is generated, it is not possible in that scenario to create an image map around the image (based on a returned array of HotArea[] objects) or to use the returned MapViewRepresentations object. You may also want to set more options for the map than can be passed in a URL (for example, a highlighted route with many pushpins).

In these rare circumstances, you may want to do your own caching. One way to implement this is highlighted in the following example:

The first steps in this example are similar to Scenario 2. The call to the GetMap method requests the image to be returned as a MimeData object (step 8), and it gets back the .gif file directly (step 9). Then, the Web application caches the .gif file (step 10). The HTML is returned to the end-user as in Scenario 2, but the returned page calls a second page in your Web application that retrieves the cached .gif file (step 13).

This scenario allows you to make your choices about the length of time that the image is cached, and allows you to authenticate and authorize your end-users.

You can use the ASP.NET Cache class to cache data in your Web application. When you create the cache, save it to the ASP.NET Cache object (step 10), as shown in the following code.

[Visual Basic]
 Cache("TheMap") = MyImage


[C#]
    Cache["TheMap"] = MyImage;

To retrieve the data from the Cache object (step 13):

[Visual Basic]
   MyImage = Cache("TheMap")


[C#]
   MyImage = Cache["TheMap"];

Making the most of your cache

You can also store other information necessary for rendering—such as pushpins, routes, and map views—using the Cache object or other cache, and then generate the map on the fly when the end-user sends the IMG tag request. One way to make the application dynamic is to use a combination of scenarios. You can cache the pushpins and route, and include the map view in the URL that is part of the IMG tag. Then if the end-user clicks a "Pan west" button on your Web page, you can regenerate the URL and refresh the image without refreshing the entire page. This allows the end-user to pan and zoom on your page without having to reload page after page.

ASP.NET provides additional ways to store data for each client, including state-caching. See the Microsoft® .NET Framework online Help for more information.