If you are creating rich, client side applications, using Jquery then these new REST APIs are a great way to do various mapping related tasks without having to load data from your own server side code. In this article we will show you a simple example of geocoding (finding a physical geographical location from its address or name) using Jquery and the Bing Maps REST API.
To get started you need to create a simple HTML page and have the Bing Maps REST API reference site open for the location service (http://msdn.microsoft.com/en-us/library/ff701715.aspx).
The first thing we need to do is add the script reference to the latest version of Jquery, in this case we are loading it from the Google CDN.
Now we need to add a textbox for the user to type their location in, and a button to submit the user request.
Now we need to add somewhere to display the results of our query.
Wiring things up
Now we have the basic page created we need to start using Jquery to wire everything up. Lets start by adding the basic jquery to wire up a click event to the button on page load. For the sake of readability we will miss out most of the HTML in the snippet below.
now comes the clever bit, we need to use Jquery’s getJSON method to request the location information from the Bing Maps REST API for the address the user has entered. The getJSON method is pretty simple and has the following signature:
jQuery.getJSON( url, [ data ], [ callback(data, textStatus) ] )
url - A string containing the URL to which the request is sent.
data - A map or string that is sent to the server with the request.
callback(data, textStatus) - A callback function that is executed if the request succeeds.
So the code to call the Bing Maps REST API to query the location of an non-structured address using the following url
You’ll notice you will need to put your own Bing Maps key into the url which you can get from http://www.bingmapsportal.com/. Here is the code we need to make the call in Jquery.
The important parts to notice are how we construct the call to Jquery’s getJSON method. The first parameter to the call is the url to load json data from, in this case we are building the url string up to include the value the user has entered in the textbox.
As we just mentioned the second parameter is the function you want to be called when the result successfully comes back.For now this code will just show an message box but now to actually read in the data.
Reading the data returned
As you can see you may get more than one “resources” object back if your address could match more than one place in the world. In this example we will just use the first result returned, but in real life you would want to present the user with a list of the possible options to choose from.
So the last bit of code to check if we have a result, and then write out the latitude and longitude of the location is as follows.
This simple example has hopefully shown you just how easy it is to call the Bing Maps REST webservices using Jquery, and just how little code is required for a completely cross browser solution.
To try it out for yourself, download the code using the link below and add your own bing maps key