Using Bing Maps Web Services Imagery Service

In my previous post, Using the Bing Maps Web Services for Geocoding Addresses, I talk about geocoding addresses using the Bing Maps Web Services. Now it is time to talk about getting imagery of maps, roads or aerials views for addresses or geocodes.

In order to get started using the Bing Maps Web Services, check out the previous post Getting Started section.

Bing Maps Web Services

Bing Maps Web Services is a set of Web services that allow you to add mapping and search functionality to your application, including location finding, map imagery, and routing capabilities. For example, you can:

Use the Imagery Service to:

  • Return a link to a map with a pushpin at a specific location
  • Provide a roadmap or bird’s eye or aerial imagery to your application

Use the Route Service to:

  • Get directions that include traffic warnings and route hints between multiple locations.
  • Get directions from all major roads to a destination (1-click directions, also referred to as a “party map”) and then use the Imagery Service to map those routes.

For this post, we will cover the Imagery service.

Just like the Geocode Service, there is a request, MapUriRequest, and response, MapUriResponse, object for the Imagery Service.

In order to get the Uri to display a map in your application, you will need to use the imagery service client, ImageryServiceClient. The ImageryServiceClient needs to be instantiated with the WCF endpoint to use, by default it should be ‘BasicHttpBinding_IImageryService’. Then call the GetMapUri method passing your MapUriRequest object.

Building the MapUriRequest

The MapUriRequest has two properties that need to be populated; the Credentials property which should contain you Bing Maps Id and either the Center, MajorRoutesDestination, or Pushpins property.  The code snippet below demonstrates instantiating the MapUriRequest and setting the properties based on values passed into a method (outlined later).

Now you can customize the options for the map using the MapUriOptions property of the MapUriRequest object. Here is a list of the properties from the MSDN documentation:

Property nameDescription
DisplayLayersA string array indicating the layer data to display on the map. Optional. The default value is null.
ImageSizeA SizeOfint Class object specifying the height and width of the image to return. Optional. The default width is 350 and the default height is 350.
ImageTypeAn ImageType Enumeration value specifying the format of the image to return. Optional. The default value is ImageType.Default, which means the default changes depending on the map style specified.
PreventIconCollisionA bool indicating whether or not to separate pushpin icons that are close to each other on the map so that they are more visible. Optional. The default value is false.
StyleA MapStyle Enumeration value specifying the map style of the image to return. Optional. The default value is MapStyle.Road.
UriSchemeA UriScheme Enumeration value specifying the URI scheme to return. Optional. The default value is UriScheme.Http.
ZoomLevelAn int indicating the zoom level of the map to return. Optional.

Assigning some of the options:

Now you are ready to call the image service client to get the MapUriResponse.

Here is a helper class, Imagery.cs,  which wraps the GetMapUri function with 8 different overloads.

Working with the MapUriResponse

The MapUriResponse object has three properties:

NameDescription
BrandLogoUriThe System.Uri of the Bing Maps brand logo image.
ResponseSummaryA ResponseSummary Class object describing the response that was returned by the service.
UriA string that is the URI of the requested map.

For brevity sake, we will just use the Uri property.  You should, though, for good programming practices, check the ResponseSummary property for any exceptions.

This call retrieves the Uri to use to display a 200×200 road map of the area at latitude 47.62 and longitude -122.2 with a zoom of 14, which is downtown Bellevue, WA.

image

If you want to add pushpins or markers similar to the above image you will need to populate the an array of PushPin objects. A PushPin object has an IconStyle which is the type of icon to use, a Label which an optional text to display on the pushpin (only works with certain pushpins) and the Location which contains the latitude and longitude that the pushpin should be located at.

That’s it.  It seems like a lot of work for a one line call.  With the attached Imagery.cs class, a lot of the overhead work was done for you.

Leave a Reply