By Ricky Brundritt, EMEA Bing Maps Technology Solution Professional
In addition to Bing Maps great API’s, there are some helpful reporting tools available to anyone who has a Bing Maps account: Developer or Enterprise. These help you get insight as to how people are using your map applications, and to also keep track of your Bing Maps usage so that it does not exceed your allowed transactions. For example, according to the Bing Maps Terms of Use, Limited Commercial use accounts are allowed 500,000 transactions and 125,000 sessions within a 12-month period.
This post will go through and highlight many useful tips to help you make the most out your Bing Maps sessions and transactions. This post is in two sections. The first section is about the reporting tools available in the Bing Maps portal and the second is focused on development tips to get the most out of the API. This blog post will assume that you have implemented Bing Maps Keys in your application. If you are using Bing Maps Tokens, these will be retired on March 30th, 2012. Documentation on how to migrate to Bing Maps Keys is here.
Before I move forward, 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 here.
Bing Maps Portal Reports
The Bing Maps reporting tools can be found in the Bing Maps portal. To find the reports follow these steps:
1. Sign into the Bing Maps portal (https://www.bingmapsportal.com/) using your Windows Live Id for your account.
2. Once signed in click on the “View my Bing Maps API usage” link in the left side panel.
3. You will now see a list of 5 different report options. Choose the one that interests you.
a. Usage Report – A report of all transactions incurred using Bing Maps keys
b. Usage Report by Category – A breakdown of all transactions broken up by the different usage categories (i.e. AjaxSession, RESTRoutes). This is a great way to see how users are using Bing Maps in your application.
c. Usage Report by Bing Maps Keys – Breaks down the transaction by Bing Maps keys. This is useful if you have multiple applications each using a different Bing Maps key.
d. Legacy (MWS + Token) Usage Report – This is an older report type that let people who have implemented Bing Maps tokens or who used to use MapPoint Web Services view their historical transactions.
e. Legacy (MWS + Token) Usage Report by Category - This is a break down of the historical transactions incurred by MapPoint and Bing Maps token users.
If you were to select Usage Report by Category, you would see a page open that looks like this:
All reports have date range filters which can be used to view up to one year’s worth of data. You can also filter the first two reports by Bing Maps key to further break down the data. In addition you can export the reports to several file formats:
- XML file with report data
- CSV (comma delimited)
- Acrobat (PDF) file
- MHTML (web archive)
- Excel
- TIFF file
- Word
Development Tips
Many of the Bing Maps API’s have a method for getting the credentials from the map after you have loaded it using a valid Bing Maps key. One often overlooked feature is that, by 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 occurred by this session key will be non-billable. Many developers overlook this feature and opt to simply use their original Bing Maps key, not knowing that they are actually incurring more billable transactions than they need to. 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 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 can be found here.
Throttled Events for Dynamically Loading Data
Some developers like to update the data on the map as it moves. This is often achieved by using a view change end map event. This can be useful for presenting new data to the user without them needing to do a new search. However there are a few tricks you can implement to reduce the number of requests made by your application. The first trick, if using the Bing Maps V7 API, is to use a throttled event. This will help reduce the number of events that are fired if the user is constantly panning and zooming the map. Here is an example of how to create a throttled event in Bing Maps V7 that ensures that 250ms has passed since the map has stopped moving.
|
Microsoft.Maps.Events.addThrottledHandler(map, 'viewchangeend', eventHandlerFunction, 250); |
By reducing the number of requests made to the Bing Maps services, you greatly reduce the amount of bandwidth required by your application which will in turn increase performance. This will be most notable on web and mobile applications. You can find a good working example of this type of solution here.
Learn More
To learn more about the Bing Maps Account Center and reporting capabilities, attend a webcast on March 15. Register here.