Bing Maps API Best Practices

These best practices provide guidelines for using the Bing Maps APIs.

Terminology

The following terms are used in this document to represent API groups. API’s may also be called out individually.

Bing Maps services

Includes:

1. Bing Maps REST Services: Provides geocoding, routing, elevations, imagery and traffic incident information using REST URL requests.

2. Bing Maps Spatial Data Services: Provides batch geocoding, spatial data source (database with spatial entities) management and data source query services using REST URL requests.

Bing Maps controls

Includes:

1. Bing Maps V8 Web Control: Use for web applications.

2. Windows 10 UWP Map control: Use for Windows 10 UWP apps that use C#, C++ or Visual Basic.

3. Bing Maps WPF Control (legacy): Use for Windows Presentation Foundation (WPF) applications.

4. Bing Maps Mobile SDK: Use for iOS and Android applications

5. Bing Map Unity SDK: Use Bing Maps Unity-Based, mixed reality experiences.

Guidelines for Bing Maps services

Please adhere to the following guidelines when coding for Bing Maps services.

Use the Find by Query API

The Bing Maps REST Services Locations API provides options for geocoding addresses. The recommended method is to pass in addresses as single-line queries using the Find by Query API. This will this will help ensure that the parts of the address are correctly categorized and will probably give you the most accurate results.

For more information on Bing REST Services, please see Bing Maps REST Service Tips & Tricks below.

Rate Limiting

In the Bing Maps terms of use trial and basic keys are limited in the number of transactions they can generate within a period of time. Public facing Windows Store, Windows Phone, and WPF apps have a limit of 50,000 transactions in a 24 hour period. Internal Windows apps, public facing web sites and non-Windows mobile apps have a limit of 125,000 transactions a year. Rate limiting occurs when the frequency of requests made against the Bing Maps REST and/or SOAP services by an account exceeds these free terms of use. Rate limiting can also occur when the services are under a lot of load. This is done to ensure that the usage from trial and basic keys do no interrupt the services for those using an Enterprise keys. Enterprise keys are not rate limited and the only way to get around rate limiting is to upgrade to an Enterprise key. For more information see our Bing Maps Licensing Options page.

When a request is rate limited, the response will return no results. This may be confusing at first as it looks like Bing Maps was unable to find results. To indicate that the request was rate limited a flag is added to the header of the response (X-MS-BM-WS-INFO) which is set to the value of 1 as documented the Status Codes and Error Handling page. To make for a better user experience, applications that use trial or basic keys should look for this flag in the header and handle requests which are rate limited. Something as simple as logging the fact that a request was rate limited in your application log could help when debugging reported issues.

Bing Maps REST Service Tips and Tricks

We recommend the Bing Maps REST services rather than SOAP services. They are newer, 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 section 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

For those of you that have been having 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 on the Using the REST Services with .NET page.

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 Culture Codes.

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.

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.

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, or 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/region is returned as the postal code was not found.

If you are using the REST services from server side code, you may find that the results 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 Geocode Dataflow API 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 request.

Routing

Many of the tips in the geocoding service apply for the routing service, such as 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 three possible routes returned by the routing engine for transit and driving directions in certain countries/regions. 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 larger when returning 3 routes rather than one. This could become an issue for users with slow internet connections (i.e. mobile users).

When 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 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.

Reducing Usage Transactions

If you are using the Bing Maps Rest services in conjunction with one of the Bing Maps map controls, 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 of 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 V8 Web Control

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  
 }  

A full working sample for the above using JavaScript can be found on MSDN in the Geocoding a Location page.

Bing Maps WPF control

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 on MSDN in the Using the REST Services with .NET page.

Guidelines for Bing Maps controls

Please adhere to the following guidelines when coding for Bing Maps controls.

Minimize map control sessions to reduce billable transactions

When you use the Bing Maps V8 control to add maps to your application, you are charged one billable transaction per session. A session is created when you load the map control on a web page and ends when you leave that web page. If you load the map control in a separate web page, you start a new session and are charged another billable transaction. If it’s possible to not change pages and still perform the map operations you need on the same web page, you will save on transactions. For example, if you want to show a map of locations and show directions to a particular location upon request, you will have the fewest transactions if you show the map of locations and the map with directions on the same web page. If you want to make use of any of the Bing Maps services, you can also save transactions by using a session key instead of a Bing Maps Key. For more information, see Use session keys to use Bing Maps services from within Bing Maps controls.

Making use of Sessions

This section will go through and highlight many useful tips to help you make the most of your Bing Maps sessions and transactions. This can have a huge impact on the number of billable transactions that get generated by your application and as a result make a big difference in terms of licensing. To start off, there are a couple of definitions you should know.

• Bing Maps Session: A Bing Maps session occurs when one of the map controls is loaded. Any transactions occurred against the Bing Maps services, while within a session is non-billable. Note this requires the application to properly use Bing Maps Keys.

• Bing Maps Transaction: A Bing Maps transaction occurs any time a service request is made. For example, some of the more common services used that incur transactions are: Bing Maps Geocoding, Routing, and Imagery service, Bing Spatial Data Service Query.

• Bing Maps Key: A Bing Maps Key is a unique string that is used to authenticate a user’s Bing Maps application or service request. This is the primary method used for tracking usage of the Bing Maps API’s.

Complete documentation explaining all the different ways sessions and transactions are incurred can be found at Understanding Bing Maps Transactions.

Implementing Session Keys

Implementing session keys is pretty straight forward. You simply use a session key instead of a Bing Maps Key. When using the REST services, simply use your session key with the key parameter of your requests.

The following are examples of how you can generate session keys in the different Bing Maps controls.

Bing Maps V8 Web Control

var sessionKey;  
  
map.getCredentials(function (c) {  
    sessionKey = c;  
});  

Bing Maps WPF Controls

string sessionKey;  
  
map.CredentialsProvider.GetCredentials((c) =>  
{  
    sessionKey = c.ApplicationId;  
});  

Visual Basic

Dim sessionKey As String  
  
map.CredentialsProvider.GetCredentials(Function(c)   
sessionKey = c.ApplicationId  
End Function)  

Guidelines for both Bing Maps services and Bing Maps controls

Please adhere to the following guidelines when coding for both Bing Services and Bing Maps controls.

Use session keys to use Bing Maps services with Bing Maps controls

Bing Maps service requests made in the context of a Bing Maps control session with a session key (instead of a Bing Maps Key) create only non-billable transactions. This is true even if the transaction is noted as billable in the transactions table. For example, if you use the Bing Maps V8 Web control to show a map in a web page, and query for a list of points of interest (POIs) near a point using the Bing Maps Spatial Data Services by using a session key, a non-billable transaction is recorded. If you had made the request with a Bing Maps Key, this request would be billable and would count towards the billable transaction limits.

To obtain a session key, you must establish a Bing Maps session. A Bing Maps session is created when you use one of the Bing Maps controls to show a map in your application. If you are using the Bing Maps V8 Web Control, the session ends when you move away from a web page that displays the control. Note that the application displays a map on two separate web pages, each of those web pages is a separate session. For applications that use the Bing Maps for Windows Store apps control (C++, C#, or Visual Basic) or the WPF control, a session is created when you start the application and ends when you close the application. The session key is used in place of the Bing Maps key in the request. For information about how to create a session key, see Using the REST Services with .NET and Geocoding a Location.

• Non-billable request
  http://BingMapsServiceRequest?key=sessionKey

• Billable request
  http://BingMapsServiceRequest?key={BingMapsKey}

Encode address values before geocoding

Make parameter string parameter values UTF-8 encoded strings so that blanks and other special characters are encoded. For example, blank spaces are encoded as %20 and ampersands (&) are encoded as %26. Languages that contain more than Latin characters, such as Japanese native character sets, must be encoded. Among options for encoding strings are the JavaScript encodeURI function and the .NET System.URI class.