The Imagery Service provided by the Bing Maps Rest Service is quite beastly as it supports a large number of permutations that can be requested from the endpoint. In order to successfully wrap up these calls we have encapsulated the url templates used and provided by the service. As with Routes there are a number of sub categories that then have further permutations as to what you can request from the endpoint. The Imagery service is very powerful but we believe that its most important usage on the phone is that it allows you to calculate a route and then have this route visualised as an image rather than you have to process the points and plot them onto a map like we saw in the Routes Service. Therefore, its very useful for improving performance in your app.
Once again you will see very familiar code when compared to the other services Location, Route and Search and our good mate Criterion Factory makes the construction of the request super simple, all of our requests are done using Rx and all the code you see here can be found in the spikes folder up on Codeplex.
The two main categories and their sub categories for the Imagery service are :-
Static Maps
- Get a map that is centered at a specified point.
- Get a map that shows a specified area based on a bounding rectangle supplied.
- Get a map that is centered at a specified point and displays a route.
- Get a map that displays a route without specifying a center point, this allows the caller to specify a route by using waypoints. When a map area or center point and a zoom level are not specified, a map area is chosen to optimise the display of the route.
- Get a map that is based on a query.
The sample code has an example of each of the sub categories which will take a look at in this post. In the sample app there are some list selectors where you can pick different options and then request the type of static map you require.
As I mentioned at the start the Imagery service is very powerful and also helps to improve performance as what is returned from the Bing Maps endpoint is an image that we can display in the visual tree.
Lets start with the get a static map that is centered at a specific point. This does what it says on the tin. In the code below we set the current location of the device using the location service and then we ask the Criterion Factory to create a request to deal with creating an image for the specified location. The static map property is a Uri and this is bound up the image source of an image control in the View.
private void ExecuteSelectCenterPointCommand()
{
this.currentLocationObserver = this.locationService
.Location()
.ObserveOnDispatcher()
.Subscribe(geoCoordinate =>
{
var criterion = CriterionFactory.CreateImageryUrlForCenterPoint(
this.imagerySetInUse,
geoCoordinate,
this.CurrentlySelectedZoomLevel,
new Size(456, 535));
this.StaticMap = this.bingMapsService.ImageryUrlForCenterPoint(criterion);
});
}
A couple of things to note with regards to the parameters being passed to the method being called on the factory :-
- this.imagerySetInUse is the imagery set of which there are 3 supported options;Aerial; Aerial with labels; and Road without imagery.
- geoCorodinate is the current location of the device.
- this.CurrentlySelectedZoomLevel is the zoomlevel.
- new Size(456, 535) is the requested size of the image that we want returned from the endpoint.
There are a number of overloaded methods so that you can pick the one which suits your needs best, this is also replicated for the other methods exposed for each of the subcategories.
Next up, get a static map that is for a calculated Route between waypoints and centered at a point.
private void ExecuteSelectCenterPointWithRouteCommand()
{
var start = new GeoCoordinate(40.77, -73.98);
var end = new GeoCoordinate(41.51, -87.39);
var wayPoints = new List<WayPoint>
{
new WayPoint { Point = start },
new WayPoint { Point = end }
};
var criterion = CriterionFactory.CreateImageryUrlForCentrePointWithRoute(
this.imagerySetInUse,
this.modeOfTravelOptionInUse,
start,
this.CurrentlySelectedZoomLevel,
wayPoints,
new Size(456, 535),
this.avoidOptionInUse);
this.StaticMap = this.bingMapsService.ImageryUrlForCenterPointWithRoute(criterion);
}
A couple of things to note with regards to the parameters being passed to the method being called on the factory :-
- this.imagerySetInUse is the imagery set of which there are 3 supported options;Aerial; Aerial with labels; and Road without imagery.
- this.modeOfTravelOptionInUse is the mode of travel of which there are 3 supported option; Driving, Walking and Transit.
- start is the point around which the image is centered.
- this.CurrentlySelectedZoomLevel is the zoom level that we want the image
- wayPoints is a list of GeoCoordinates that make up the Route that you want to travel
- the avoidOptionInUse is the road types that you want to avoid there are 4 options; Highways; Tolls; minimise Highways and minimise Tolls.
Next up, get a static map for a specific area that has a calculated route.
private void ExecuteSelectSpecificAreaWithRouteCommand()
{
const double south = 37.317227;
const double west = -122.318439;
const double north = 37.939081;
const double east = -122.194565;
var start = new GeoCoordinate(south, west);
var end = new GeoCoordinate(north, east);
var wayPoints = new[]
{
new WayPoint { Point = start },
new WayPoint { Point = end }
};
var criterion = CriterionFactory.CreateImageryUrlForSpecificAreaWithRoute(
this.imagerySetInUse,
this.modeOfTravelOptionInUse,
wayPoints,
new LocationRect(north, west, south, east));
this.StaticMap = this.bingMapsService.ImageryUrlForSpecificAreaWithRoute(criterion);
}
A couple of things to note with regards to the parameters being passed to the method being called on the factory :-
- this.imagerySetInUse is the imagery set of which there are 3 supported options;Aerial; Aerial with labels; and Road without imagery.
- wayPoints is a list of GeoCoordinates that make up the Route that you want to travel
- new LocationRect(north, west, south, east) is a bounding box that we create using lat and long values to represent the area.
Next up, get a static map for a specific area.
private void ExecuteSelectSpecificAreaCommand()
{
const double south = 37.317227;
const double west = -122.318439;
const double north = 37.939081;
const double east = -122.194565;
var criterion = CriterionFactory.CreateImageryUrlForSpecificArea(
this.imagerySetInUse,
new LocationRect(north, west, south, east));
this.StaticMap = this.bingMapsService.ImageryUrlForSpecificArea(criterion);
}
A couple of things to note with regards to the parameters being passed to the method being called on the factory :-
- this.imagerySetInUse is the imagery set of which there are 3 supported options;Aerial; Aerial with labels; and Road without imagery.
- new LocationRect(north, west, south, east) is a bounding box that we create using lat and long values to represent the area.
Next up, get a static map for a specific calculated Route.
private void ExecuteSelectRouteCommand()
{
var start = new GeoCoordinate(40.77, -73.98);
var end = new GeoCoordinate(41.51, -87.39);
var wayPoints = new[]
{
new WayPoint { Point = start },
new WayPoint { Point = end }
};
var pushPins = new List<PushPin>();
var criterion = CriterionFactory.CreateImageryUrlForRoute(
this.imagerySetInUse,
this.modeOfTravelOptionInUse,
wayPoints,
DateTime.Now,
this.optimizeRouteOptionInUse,
pushPins, TimeType.Departure);
this.StaticMap = this.bingMapsService.ImageryUrlForRoute(criterion);
}
And the final option for static maps is the ability to get a map showing the query result centered on a map, in our example this is the Space Needle in Seattle.
private void ExecuteSelectQueryCommand()
{
var criterion = CriterionFactory.CreateImageryUrlForQuery(
this.imagerySetInUse,
"space needle,seattle");
this.StaticMap = this.bingMapsService.ImageryUrlForQuery(criterion);
}
And that completes the overview for each of the pillars that compose the Bing Maps REST API Location, Route and Imagery services. Hopefully you have found them useful and they help to supplement the code example in the Spikes folder for WP7C.
As always it would be great to hear your feedback good and bad to help make these wrappers fit your requirements.
Enjoy!
