Section 8.1. Understanding Render APIs

8.1. Understanding Render APIs

The Render Service end point is located at the RenderService.asmx, and the APIs available for it are exposed via the RenderServiceSoap class in the Web Service proxy (Reference.cs or Reference.vb).

The RenderServiceSoap class contains methods related to render functionality , namely GetMap, GetBestMapView, ConvertToLatLong, and ConvertToPoint, which can be used to get maps, get map views, and to convert a point on a map to a pixel coordinate or vice versa. Table 8-1 describes the methods of the RenderServiceSoap class.

Table 8-1. RenderServiceSoap methods

Method	Description
ConvertToLatLong	Converts pixel coordinates on a given map to latitude and longitude coordinates. Returns an array of LatLong objects from a given array of PixelCoord objects.
ConvertToPoint	Converts latitude and longitude coordinates to pixel coordinates. Returns an array of PixelCoord objects from a given array of LatLong objects.
GetBestMapView	Creates a single best map view for displaying a set of locations. A best map view is the largest scale map that can be centered over the set of locations while displaying the entire location along with a small buffer. This method returns a MapViewRepresentations object for a specified Location object or array of Location objects.
GetMap	Creates one or more rendered images of a map. Returns a MapImage object or an array of MapImage objects based on a specified map view or array of map views.
GetLineDriveMap	Renders a line-drive map and returns an array of LineDriveMapImage objects.

Before getting into the details of using the render-related methods, let's look at the essential basics to understand in rendering maps.

8.1.1. Introduction to Views

A view defines a specific area that needs to be rendered on a map and can be expressed in four ways using MapPoint Web Service.

8.1.1.1. View by bounding locations

In this case, a map view is defined using a set of locations, and the map is rendered to contain all of the locations on the map. Programmatically, this view is represented by the ViewByBoundingLocations class, which takes an array of Location objects to define the map view. All input Location objects must have a valid LatLong property. This view is useful if you want to render Location objects from different find calls on one map. When this view is requested, MapPoint Web Service calculates the best possible map view to fit all locations on the map. The following code shows how to define and use the ViewByBoundingLocation object to render a map:

     //Define an array of locations     //In this case 4 has been randomly chosen     Location[] myLocations = new Location[4];     //Obtain LatLong values for each Location object     . . .     //Define view by     Location and assign locations        ViewByBoundingLocations viewByBoundingLocations                         = new ViewByBoundingLocations( );     viewByBoundingLocations.Locations = myLocations;     //Get a map     MapSpecification mapSpec  = new MapSpecification( );        mapSpec.Views = new MapView[] {viewByBoundingLocations};     . . .

These four locations are rendered on the map shown in Figure 8-1.

8.1.1.2. View by height and width

In this case, a map view is defined by the height and width of the area that you want to cover on the ground. The height and width you express essentially equal the ground distance in either miles or kilometers. It is important to keep in mind that this height and width is different from the height and width of the map image that you want to render. If you want to render 50 km of height and 100 km of width on the ground, you can do so on a 200 x 200 pixel map image. Although the height and width specified for the map are different from the height and width of the map image, they are related to each other via map scale, which we will look at in detail later in this chapter.

Figure 8-1. View by bounding locations map

When a map is rendered using ground height and width, it is rendered to contain at least the requested area, which means that MapPoint Web Service may render more area than requested depending on the aspect ratio. Programmatically, this view is represented by the ViewByHeightWidth class, which defines the map view using height and width specifications as integers. When this view is requested, MapPoint Web Service calculates the best possible map view to fit the requested area on the map. The following code shows how to define a ViewByHeightWidth object to render a map:

     //Define a center point     LatLong centerPoint = new LatLong( );     centerPoint.Latitude = centerLatitude;     centerPoint.Longitude = centerLongitude;     //Define view by height and width     ViewByHeightWidth viewByHW = new ViewByHeightWidth( );     viewByHW.CenterPoint = centerPoint;     //Define height and width on the ground     //In this case area covering     //200 km and     //300 km     //on the ground        viewByHW.Height = 200;     viewByHW.Width = 300;     //Create map specification     MapSpecification mapSpec = new MapSpecification( );     mapSpec.Views = new ViewByHeightWidth[] {viewByHW};     //Get a map     . . .

The rendered map requested in the previous code is shown in Figure 8-2.

Figure 8-2. Map rendered with 200 x 300 KM in ground distance

The same map rendered with 20 x 30 km height and width, respectively, is shown in Figure 8-3.

Although the image (bitmap) size here is constant, a change in the map's height and width caused the scale to change, creating a "zoom in" effect.

8.1.1.3. View by scale

In order to understand view by scale , you need to understand the notion of scale first. Scale can be defined as (map image size) / (map size in real world); so, if you have a map of the world as a globe rendered on a 1 inch map image, the scale is 1: 520,000,000, since the world's diameter is 520,000,000 inches. This means that one inch on the image represents 520,000,000 actual inches in the world. Remember though, that the image size (such as 400 x 600 pixels and 2,000 x 2,000 pixels) has no impact on the scale; to control the scale of a rendered map, you need to use view by scale. This view is represented by the ViewByScale object. To use this object, set a center point as LatLong object and scale value. The scale ranges are dependent on the MapPoint data sources. The following code shows how to use the ViewByScale object:

Figure 8-3. Map rendered with 20 x 30 KM in ground distance

     //Define a center point     LatLong centerPoint = new LatLong( );     centerPoint.Latitude = centerLatitude;     centerPoint.Longitude = centerLongitude;     //Define view by scale     ViewByScale viewByScale = new ViewByScale( );     viewByScale.CenterPoint = centerPoint;     //Define scale value     viewByScale.MapScale = 20000;     //Create map specification     MapSpecification mapSpec = new MapSpecification( );     mapSpec.Views = new ViewByScale[] {viewByScale};     //Get a map     . . .

This view is extremely useful in controlling the zoom levels for rendered maps. Also, note that you can use this view for device-specific resolution map rendering ; by default, MapPoint Web Service renders maps at 96 dpi; however, you can alter this value to match your device-specific resolution, as shown below:

     //Define scale value     viewByScale.MapScale = 20000 * 96/120; 

A resolution of 120 dpi is applied to the scale to match the device's dpi resolution.

8.1.1.4. View by bounding rectangle

This view defines the map area by a bounding rectangle. Unlike the view by bounding locations, there are only two LatLong objects involved in defining the rectangle: one for the northeast corner and one for the southwest corner. When a bounding rectangle is defined using a LatLongRectangle object, a map that covers the specified area is rendered. This view is useful if you want to render a specific area on the map (unlike the area dictated by the number of points, as in ViewByBoundingLocations). This view is programmatically represented by the ViewByBoundingRectangle object. The following code shows how to use this view:

     //Define northeast point     LatLong northEastPoint = new LatLong( );     . . .     //Define southwest point     LatLong southWestPoint = new LatLong( );     . . .        //Define view by bounding rectangle      ViewByBoundingRectangle vbr = new ViewByBoundingRectangle( );     vbr.BoundingRectangle = new LatLongRectangle( );     vbr.BoundingRectangle.Northeast = northEastPoint;     vbr.BoundingRectangle.Southwest = southWestPoint;     //Create map specification     MapSpecification mapSpec = new MapSpecification( );     mapSpec.Views = new ViewByBoundingRectangle[] {vbr};     //Get Map     . . .

This code generated the map shown in Figure 8-4.

The map has covered the corners defined by the northeast and southwest latitude, longitude combinations.

Now that you know what map views are, let's look at map styles before moving on to look at the Render APIs in detail.

Figure 8-4. Map rendered for view by bounding rectangle

8.1.2. Understanding Map Styles

Map Style in MapPoint Web Service is a rendering -specific flag that indicates what kind of detail is rendered on the map. To that end, Map Style can be used to control which information is rendered on the maps.

For example, when you use Road map style, the maps are rendered with full road data; however, when you choose to use Political map style, maps display only political entities (such as countries, and regions). Map Style in MapPoint Web Service is programmatically represented using the MapStyle enumeration. There are currently 31 Map Styles supported in MapPoint Web Service; it is important to keep in mind that Map Styles are data source-dependentnot all map styles are supported by all data sources.

With this introduction to map views and map styles, let's next look at how Rendering APIs works.

8.1.3. Anatomy of Render APIs

MapPoint Web Service provides Render APIs for you to render maps using the RenderServiceSoap.GetMap method. The GetMap method takes a MapSpecification object as an argument that defines the map to be rendered and returns an array of MapImage objects. The MapSpecification object defines the map to be rendered in terms of the view, data source, route (only for rendering a route), pushpins, or polygons (only to render polygons), along with optional map options that give you control over map features such as size and style. Table 8-2 shows the fields of the MapSpecification class, and Table 8-3 shows the MapOptions class fields.

Table 8-2. MapSpecification fields

Field	Description
DataSourceName	Name of the data source name as a string.
HighlightedEntityIDs	An array of the IDs of geographic entities that should appear as selected on the map. Valid array range is 0 through 50.
Options	The map rendering options (MapOptions object), such as image format, panning and zooming factors, identification of the requested map as an overview map, route highlight colors, font size, and map style.
Polygons	An array of Polygon objects to render.
Pushpins	An array of pushpins (Pushpin objects) to render on the map. Valid array range is 0 through 100.
Route	The route (Route object) to render on the map. Required if the Views property is null.
Views	An array of map views (MapView objects) to render. One map image is returned for each map view. Valid array range is 0 through 50. Required if the Route property is null.

Table 8-3. MapOption class fields

Field	Notes
ConstructionClosureHighlightColor	The highlight color (RouteHighlightColor enumeration) used for parts of a route that are closed due to construction. Default is red.
ConstructionDelayHighlightColor	The highlight color (RouteHighlightColor enumeration) to use for parts of a route where delays due to construction can be expected. Default is DefaultColor.
FontSize	The relative font size (MapFontSize enumeration) used for map labeling. Default is Medium.
Format	The format (ImageFormat object) of the map image to return.
IsOverviewMap	Identifies whether the requested map should be rendered as an overview map.
PanHorizontal	A positive or negative number reflecting the percentage of the map image to pan west (negative) or east (positive).
PanVertical	A positive or negative number reflecting the percentage of the map image to pan south (negative) or north (positive).
ReturnType	Identifies whether the RenderServiceSoap.GetMap method should return a map image or a standard or secure URL to a cached map image. MapReturnType enumeration.
RouteHighlightColor	The highlight color (RouteHighlightColor enumeration) to use for a route (other than construction areas). Default is Green.
Style	The map style (MapStyle enumeration) to use.
Zoom	Identifies the amount the map image is magnified, expressed as a fractional percentage.

The GetMap method returns an array of MapImage objects out of which the first MapImage contains the actual rendered map. The returned MapImage object contains either the map image serialized into a byte array or the URL to the map image stored on MapPoint Servers. The following code shows how to use MapSpecification object to get a map:

     //Find a place to render     FindServiceSoap findService  = new FindServiceSoap( );     //Assign credentials     . . .     //Find place     FindSpecification findSpec = new FindSpecification( );     findSpec.DataSourceName = "MapPoint.NA";     findSpec.InputPlace = "Seattle, WA";     FindResults foundResults = findService.Find(findSpec);     //Get the view     ViewByHeightWidth view          = foundResults.Results[0].FoundLocation.BestMapView.ByHeightWidth;     //Create a RenderServiceSoap instance     RenderServiceSoap renderService  = new RenderServiceSoap( );     //Assign to credentials     . . .        //Define MapSpecification     MapSpecification mapSpec  = new MapSpecification( );     //Assign DataSource     mapSpec.DataSourceName = "MapPoint.NA";     //Assign view     mapSpec.Views = new MapView[] {view};     //Get Map     MapImage[] mapImages = renderService.GetMap(mapSpec);     //Get the map image stream     System.IO.Stream streamImage              = new System.IO.MemoryStream(mapImages[0].MimeData.Bits);     //Load the image stream into a bitmap     Bitmap bitmapImage = new Bitmap(streamImage);

The MapImage instance returned by the GetMap method contains the map image as a byte array that can be used in your application, which works well for a Windows application. But what if you have a web application where you have an image tag and all you need is a URL to display the map?

8.1.4. Rendering for Windows Versus Rendering for the Web

Using the GetMap method, you can get either a map image as a byte array or a URL that contains the map image stored on MapPoint Web Service servers. Once you have the image URL, you can set it to an image tag for a web application. By default, the GetMap method returns the map image as a byte array, but you can use the MapOptions object to change this option to return the map URL by setting the ReturnType property:

     //Create map specification     MapSpecification mapSpec  = new MapSpecification( );     //Assign data source and views     ..        //Define map options     mapSpec.Options = new MapOptions( );     //Request map URL     mapSpec.Options.ReturnType = MapReturnType.ReturnUrl;     //Get map     MapImage[] mapImages =                 renderService.GetMap(mapSpec);        //Get the URL     string url = mapImages[0].Url; 

From this code, MapPoint Web Service returns a URL to the map image when the MapOptions.ReturnType is set to either the MapReturnType.ReturnUrl or the MapReturnType.ReturnSecureUrl enumeration. This method is very efficient since the SOAP message response from MapPoint Web Service contains only a URL instead of the entire image.

However, keep in mind that a returned URL is valid for returning up to ten images within five minutes of the call to the GetMap method. After five minutes or ten images (whichever occurs first), accessing the URL returns a session time-out message.