Bing Maps REST Service Tips & Tricks

UPDATE: Please see Bing Maps API Best Practices - Microsoft Bing Maps | Microsoft Learn for the latest guidance on using Bing Maps APIs and SDKs.

I’ve been a big fan of the Bing Maps REST services since they were first released several years ago and highly recommend trying them out if you haven’t already. The REST services are much newer than the SOAP services, have more features, are faster and can be consumed by non .NET languages with greater ease. If you have the Bing Maps REST services return JSON the response size of a request is significantly smaller than the response size from the same request using the Bing Maps SOAP services. This blog post will go through and highlight some tips for getting the most out of the Bing Maps REST services.

Using the REST services in managed code

I want to take the time to provide a useful resource for those who have had issues consuming the Bing Maps REST Services APIs using .NET. The documentation on how to consume the JSON responses from the Bing Maps REST services can be found on MSDN here.

If you are using Java then take a look at how the REST services are handled in the Bing Maps Android SDK.

Geocoding

Unless you are geocoding English addresses in the US you should specify a culture parameter to help ensure you get the most relevant results. By default, the culture for all requests is set to en-US. If geocoding addresses in the UK, you will find that in some cases using the culture parameter en-GB will return better results. This becomes even more important when geocoding addresses that are not in English. To specify a culture in a REST request simply use “&c=cultureCode” – you can take a look at the complete list of Supported Cultures.

Encode address and query parameters. This is especially important when working with non-English languages as special characters often will not work correctly. This is also important if you want to use an ampersand (&) in your query. By encoding an ampersand it will appear in the URL as “%26”. Here are the methods that can be used in different programming languages to encode URL parameters.

Language

Method

Example

JavaScript

encodeURI

encodeURIComponent(query)

C#/VB

Uri

Uri.EscapeDataString (query)

When geocoding free form queries use the unstructured URL format rather than the structured format. The unstructured URL format tends to be much more successful for these types of queries. Note: the structured format actually overlaps with the reverse geocoding URL request format and can return odd results if your query is just made up of numbers.

√Unstructured URL

http://dev.virtualearth.net/REST/v1/Locations?query=locationQuery&key=BingMapsKey

X Structured URL

http://dev.virtualearth.net/REST/v1/Locations/locationQuery?key=BingMapsKey

The Bing Maps geocoder will attempt to find the closest match as possible to your query. In some cases, it will not be able to find an exact match. This is where the match code parameter of the returned results becomes useful. The match code parameter is an array of values and can have any combination of the following three values; Good, Ambiguous, and UpHierarchy. If you are only interested in exact matches then keep a look out for UpHierachy as this indicates that your exact query was not found but an upper level address value was found. For example, you attempt to geocode a postal code but instead the associated country is returned as the postal code was not found.

If using the REST services from server side code you may find that the results on in your application may differ from the results found when using the services locally. The reason for this is that the REST services take your IP address into consideration when making a request. To help reduce this issue you can set the userIp parameter of the request to 127.0.0.1. This will trick the service into thinking you are making the call from a local application and cause it to ignore your IP address.

If you have a lot of data you want to geocode at once consider using the Bing Spatial Data Services and the batch geocoding functionality. This service allows you to geocode up to 200,000 addresses in a single request.

Reverse Geocoding

Limit your coordinates to 6 decimal places. At 6 decimal places you have an accuracy of approximately 10cm on the ground. Any more than 6 decimal places just makes for a longer URL and can confuse the reverse geocoder into thinking this is a free form query search.

Ensure that your numbers are not being turned into scientific notation format when converting them to string. This occurs quite often when working with small numbers. For example, it is not uncommon for some languages to convert 0.00005 to 5E-5. Scientific notation is not supported by the service and will be interpreted as a free form query.

Ensure that when converting your coordinates to string that you use an invariant culture. Coordinates that use commas for decimal places will not work correctly.

Like the batch geocoder you can also do batch reverse geocoding using the Bing Spatial Data Services if you need to reverse geocode a large number of coordinates in one go.

Routing

Many of the tips in the geocoding service apply for the routing service, like being sure to encode your address locations. However, don’t encode coordinate based locations.

The default distance units are in Kilometers. Use the distanceUnit parameter to change this to miles if that is your preferred unit of measurement.

You can now have up to 3 possible routes returned by the routing engine for transit and driving directions in certain countries. This may be desirable in some applications but it is best to make this optional to your users. Although the calculation on Bing Maps end is fast, the response from Bing Maps is much bigger when returning 3 routes, rather than one. This could become an issue for users with slow internet connections (i.e. mobile users).

If using Bing Maps in areas where geocoding coverage is limited consider allowing the user to select their start and end point on the map via a click event or by dragging a pushpin. This will allow you to pass in coordinates for your end points rather than an address. The routing engine is capable of calculating routes anywhere there is road data, even if there is no geocoding coverage.

If you want to retrieve the coordinates that make up the route line along the roads use the routePathOutput parameter.

Imagery Service

When requesting a static map image from Bing Maps the imagery service the service will automatically choose the best image format to return the image in for best resolution. Note: this may not be the preferred image type in some cases. For example, the service may return Ordnance Survey maps in PNG format; you may find you prefer these maps returned as JPG of GIF format. You can specify the image type using the format parameter.

The Imagery service can return two different types of metadata. The first type of metadata gives you information about the imagery in Bing Maps for a specific location, zoom level and map type. This is useful if you want to find out the age of the imagery or want to know is a specific type of imagery is available for a certain location. The second type of metadata is for a static image generated from the imagery service. This second metadata may include information such as pixel coordinates of pushpins on your image. This is useful if you want to be able to tie events to the generated image or create an HTML image map out of it.

Reducing Usage Transactions

Are you are using the Bing Maps Rest services in conjunction with one of the Bing Maps map controls? If so, you can significantly reduce the number of transactions your application incurs against your Bing Maps account if you request the Bing Maps key from the map control rather than using your normal Bing Maps key. This is quite often an overlooked feature. When getting the credentials from the map you do not get back your original Bing Maps key. Instead, you get a special session key which you can use as a Bing Maps key to make requests to the Bing Maps services. By doing this all transactions incurred by this session key will be non-billable. Here are some examples of how to properly use a session key.

Bing Maps V7 AJAX API

function ClickGeocode()

 {

                map.getCredentials(MakeBingMapsRESTRequest);

 }

 

 function MakeBingMapsRESTRequest(sessionKey)

 {

                //Generate a request URL for the Bing Maps REST services.

                //Use the session key in the request as the Bing Maps key

 }

Full working sample using JavaScript can be found here.

Bing Maps Silverlight, WPF, WP7, and WinForm API’s

Map.CredentialsProvider.GetCredentials((c) =>

{

                string sessionKey = c.ApplicationId;

               

                //Generate a request URL for the Bing Maps REST services.

                //Use the session key in the request as the Bing Maps key

});

Full working samples using .NET can be found
here.

– Ricky Brundritt, EMEA Bing Maps Technology Solution Professional