Technology

Using Jquery with the Bing Maps REST API

Anthony Marshall
Anthony Marshall
10 Oct 2010
blog post featured image
<p>In the last few months <a href="http://www.earthware.co.uk/what-we-do/bespoke-mapping-implementations/microsoft-bing-maps.aspx">Bing Maps</a> have released a <a href="http://www.bing.com/toolbox/blogs/maps/archive/2010/06/07/rest-easy-bing-maps-has-you-covered.aspx">new version of the web services</a> (previously available as SOAP). This new version uses the increasingly popular REST format which for the first time allows us to use these services direct from javascript on the clients browser.</p> <p>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.</p> <h3>Getting started</h3> <p>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&#160; (<a href="http://msdn.microsoft.com/en-us/library/ff701715.aspx">http://msdn.microsoft.com/en-us/library/ff701715.aspx</a>).</p> <p>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.</p> <div style="padding-bottom: 0px; margin: 0px; padding-left: 0px; padding-right: 0px; display: inline; float: none; padding-top: 0px" id="scid:9ce6104f-a9aa-4a17-a79f-3a39532ebf7c:e35b48e5-c252-4608-89b6-eaca844eca62" class="wlWriterEditableSmartContent"> <div style="border: #000080 1px solid; color: #000; font-family: 'Courier New', Courier, Monospace; font-size: 10pt"> <div style="background: #ddd; max-height: 300px; overflow: auto"> <ol style="background: #ffffff; margin: 0 0 0 2.5em; padding: 0 0 0 5px;"> <li><span style="color:#0000ff">&lt;!</span><span style="color:#800000">DOCTYPE</span> <span style="color:#ff0000">html</span> <span style="color:#ff0000">PUBLIC</span> <span style="color:#0000ff">&quot;-//W3C//DTD XHTML 1.0 Transitional//EN&quot;</span> <span style="color:#0000ff">&quot;http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd&quot;&gt;</span></li> <li style="background: #f3f3f3"><span style="color:#0000ff">&lt;</span><span style="color:#800000">html</span> <span style="color:#ff0000">xmlns</span><span style="color:#0000ff">=&quot;http://www.w3.org/1999/xhtml&quot;</span> <span style="color:#0000ff">&gt;</span></li> <li><span style="color:#0000ff">&lt;</span><span style="color:#800000">head</span><span style="color:#0000ff">&gt;</span></li> <li style="background: #f3f3f3">    <span style="color:#0000ff">&lt;</span><span style="color:#800000">title</span><span style="color:#0000ff">&gt;</span>Bing Maps REST with Jquery<span style="color:#0000ff">&lt;/</span><span style="color:#800000">title</span><span style="color:#0000ff">&gt;</span></li> <li>    <span style="color:#0000ff">&lt;</span><span style="color:#800000">script</span> <span style="color:#ff0000">type</span><span style="color:#0000ff">=&quot;text/javascript&quot;</span> <span style="color:#ff0000">src</span><span style="color:#0000ff">=&quot;http://ajax.googleapis.com/ajax/libs/jquery/1.4.2/jquery.min.js&quot;&gt;&lt;/</span><span style="color:#800000">script</span><span style="color:#0000ff">&gt;</span></li> <li style="background: #f3f3f3"><span style="color:#0000ff">&lt;/</span><span style="color:#800000">head</span><span style="color:#0000ff">&gt;</span></li> <li><span style="color:#0000ff">&lt;</span><span style="color:#800000">body</span><span style="color:#0000ff">&gt;</span></li> <li style="background: #f3f3f3">&nbsp;</li> <li><span style="color:#0000ff">&lt;/</span><span style="color:#800000">body</span><span style="color:#0000ff">&gt;</span></li> <li style="background: #f3f3f3"><span style="color:#0000ff">&lt;/</span><span style="color:#800000">html</span><span style="color:#0000ff">&gt;</span></li> </ol> </div> </div> </div> <p>&#160;</p> <p>Now we need to add a textbox for the user to type their location in, and a button to submit the user request.</p> <div style="padding-bottom: 0px; margin: 0px; padding-left: 0px; padding-right: 0px; display: inline; float: none; padding-top: 0px" id="scid:9ce6104f-a9aa-4a17-a79f-3a39532ebf7c:529e03d2-c67a-43b7-ad04-831242856f35" class="wlWriterEditableSmartContent"> <div style="border: #000080 1px solid; color: #000; font-family: 'Courier New', Courier, Monospace; font-size: 10pt"> <div style="background: #ddd; max-height: 300px; overflow: auto"> <ol style="background: #ffffff; margin: 0 0 0 2.5em; padding: 0 0 0 5px; white-space: nowrap"> <li><span style="color:#0000ff">&lt;!</span><span style="color:#800000">DOCTYPE</span> <span style="color:#ff0000">html</span> <span style="color:#ff0000">PUBLIC</span> <span style="color:#0000ff">&quot;-//W3C//DTD XHTML 1.0 Transitional//EN&quot;</span> <span style="color:#0000ff">&quot;http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd&quot;&gt;</span></li> <li style="background: #f3f3f3"><span style="color:#0000ff">&lt;</span><span style="color:#800000">html</span> <span style="color:#ff0000">xmlns</span><span style="color:#0000ff">=&quot;http://www.w3.org/1999/xhtml&quot;</span> <span style="color:#0000ff">&gt;</span></li> <li><span style="color:#0000ff">&lt;</span><span style="color:#800000">head</span><span style="color:#0000ff">&gt;</span></li> <li style="background: #f3f3f3">    <span style="color:#0000ff">&lt;</span><span style="color:#800000">title</span><span style="color:#0000ff">&gt;</span>Bing Maps REST with Jquery<span style="color:#0000ff">&lt;/</span><span style="color:#800000">title</span><span style="color:#0000ff">&gt;</span></li> <li>    <span style="color:#0000ff">&lt;</span><span style="color:#800000">script</span> <span style="color:#ff0000">type</span><span style="color:#0000ff">=&quot;text/javascript&quot;</span> <span style="color:#ff0000">src</span><span style="color:#0000ff">=&quot;http://ajax.googleapis.com/ajax/libs/jquery/1.4.2/jquery.min.js&quot;&gt;&lt;/</span><span style="color:#800000">script</span><span style="color:#0000ff">&gt;</span></li> <li style="background: #f3f3f3"><span style="color:#0000ff">&lt;/</span><span style="color:#800000">head</span><span style="color:#0000ff">&gt;</span></li> <li><span style="color:#0000ff">&lt;</span><span style="color:#800000">body</span><span style="color:#0000ff">&gt;</span></li> <li style="background: #f3f3f3">    <span style="color:#0000ff">&lt;</span><span style="color:#800000">label</span> <span style="color:#ff0000">for</span><span style="color:#0000ff">=&quot;myaddress&quot;&gt;</span>Type an address:<span style="color:#0000ff">&lt;/</span><span style="color:#800000">label</span><span style="color:#0000ff">&gt;</span></li> <li>    <span style="color:#0000ff">&lt;</span><span style="color:#800000">input</span> <span style="color:#ff0000">type</span><span style="color:#0000ff">=&quot;text&quot;</span> <span style="color:#ff0000">id</span><span style="color:#0000ff">=&quot;txtAddress&quot;</span> <span style="color:#0000ff">/&gt;</span></li> <li style="background: #f3f3f3">    <span style="color:#0000ff">&lt;</span><span style="color:#800000">input</span> <span style="color:#ff0000">type</span><span style="color:#0000ff">=&quot;button&quot;</span> <span style="color:#ff0000">id</span><span style="color:#0000ff">=&quot;btnSearch&quot;</span> <span style="color:#ff0000">value</span><span style="color:#0000ff">=&quot;Find Location&quot;</span> <span style="color:#0000ff">/&gt;</span></li> <li><span style="color:#0000ff">&lt;/</span><span style="color:#800000">body</span><span style="color:#0000ff">&gt;</span></li> <li style="background: #f3f3f3"><span style="color:#0000ff">&lt;/</span><span style="color:#800000">html</span><span style="color:#0000ff">&gt;</span></li> </ol> </div> </div> </div> <p>&#160;</p> <p>Now we need to add somewhere to display the results of our query.</p> <div style="padding-bottom: 0px; margin: 0px; padding-left: 0px; padding-right: 0px; display: inline; float: none; padding-top: 0px" id="scid:9ce6104f-a9aa-4a17-a79f-3a39532ebf7c:eb2eca72-6675-4265-a302-0c81c12b5d6e" class="wlWriterEditableSmartContent"> <div style="border: #000080 1px solid; color: #000; font-family: 'Courier New', Courier, Monospace; font-size: 10pt"> <div style="background: #ddd; max-height: 300px; overflow: auto"> <ol style="background: #ffffff; margin: 0 0 0 2.5em; padding: 0 0 0 5px; white-space: nowrap"> <li><span style="color:#0000ff">&lt;!</span><span style="color:#800000">DOCTYPE</span> <span style="color:#ff0000">html</span> <span style="color:#ff0000">PUBLIC</span> <span style="color:#0000ff">&quot;-//W3C//DTD XHTML 1.0 Transitional//EN&quot;</span> <span style="color:#0000ff">&quot;http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd&quot;&gt;</span></li> <li style="background: #f3f3f3"><span style="color:#0000ff">&lt;</span><span style="color:#800000">html</span> <span style="color:#ff0000">xmlns</span><span style="color:#0000ff">=&quot;http://www.w3.org/1999/xhtml&quot;</span> <span style="color:#0000ff">&gt;</span></li> <li><span style="color:#0000ff">&lt;</span><span style="color:#800000">head</span><span style="color:#0000ff">&gt;</span></li> <li style="background: #f3f3f3">    <span style="color:#0000ff">&lt;</span><span style="color:#800000">title</span><span style="color:#0000ff">&gt;</span>Bing Maps REST with Jquery<span style="color:#0000ff">&lt;/</span><span style="color:#800000">title</span><span style="color:#0000ff">&gt;</span></li> <li>    <span style="color:#0000ff">&lt;</span><span style="color:#800000">script</span> <span style="color:#ff0000">type</span><span style="color:#0000ff">=&quot;text/javascript&quot;</span> <span style="color:#ff0000">src</span><span style="color:#0000ff">=&quot;http://ajax.googleapis.com/ajax/libs/jquery/1.4.2/jquery.min.js&quot;&gt;&lt;/</span><span style="color:#800000">script</span><span style="color:#0000ff">&gt;</span></li> <li style="background: #f3f3f3"><span style="color:#0000ff">&lt;/</span><span style="color:#800000">head</span><span style="color:#0000ff">&gt;</span></li> <li><span style="color:#0000ff">&lt;</span><span style="color:#800000">body</span><span style="color:#0000ff">&gt;</span></li> <li style="background: #f3f3f3">    <span style="color:#0000ff">&lt;</span><span style="color:#800000">label</span> <span style="color:#ff0000">for</span><span style="color:#0000ff">=&quot;myaddress&quot;&gt;</span>Type an address:<span style="color:#0000ff">&lt;/</span><span style="color:#800000">label</span><span style="color:#0000ff">&gt;</span></li> <li>    <span style="color:#0000ff">&lt;</span><span style="color:#800000">input</span> <span style="color:#ff0000">type</span><span style="color:#0000ff">=&quot;text&quot;</span> <span style="color:#ff0000">id</span><span style="color:#0000ff">=&quot;txtAddress&quot;</span> <span style="color:#0000ff">/&gt;</span></li> <li style="background: #f3f3f3">    <span style="color:#0000ff">&lt;</span><span style="color:#800000">input</span> <span style="color:#ff0000">type</span><span style="color:#0000ff">=&quot;button&quot;</span> <span style="color:#ff0000">id</span><span style="color:#0000ff">=&quot;btnSearch&quot;</span> <span style="color:#ff0000">value</span><span style="color:#0000ff">=&quot;Find Location&quot;</span> <span style="color:#0000ff">/&gt;</span></li> <li>    <span style="color:#0000ff">&lt;</span><span style="color:#800000">p</span> <span style="color:#ff0000">id</span><span style="color:#0000ff">=&quot;results&quot;&gt;&lt;/</span><span style="color:#800000">p</span><span style="color:#0000ff">&gt;</span></li> <li style="background: #f3f3f3"><span style="color:#0000ff">&lt;/</span><span style="color:#800000">body</span><span style="color:#0000ff">&gt;</span></li> <li><span style="color:#0000ff">&lt;/</span><span style="color:#800000">html</span><span style="color:#0000ff">&gt;</span></li> </ol> </div> </div> </div> <h3>&#160;</h3> <h3>Wiring things up</h3> <p>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.</p> <div style="padding-bottom: 0px; margin: 0px; padding-left: 0px; padding-right: 0px; display: inline; float: none; padding-top: 0px" id="scid:9ce6104f-a9aa-4a17-a79f-3a39532ebf7c:eab21ff8-000e-481e-8919-cb475edaabe8" class="wlWriterEditableSmartContent"> <div style="border: #000080 1px solid; color: #000; font-family: 'Courier New', Courier, Monospace; font-size: 10pt"> <div style="background: #ddd; max-height: 300px; overflow: auto"> <ol style="background: #ffffff; margin: 0 0 0 2em; padding: 0 0 0 5px;"> <li><span style="color:#0000ff">&lt;</span><span style="color:#800000">script</span> <span style="color:#ff0000">type</span><span style="color:#0000ff">=&quot;text/javascript&quot;&gt;</span></li> <li style="background: #f3f3f3">    $(document).ready(<span style="color:#0000ff">function</span> () {</li> <li>        $(<span style="color:#800000">&quot;#btnSearch&quot;</span>).click(<span style="color:#0000ff">function</span> () {</li> <li style="background: #f3f3f3">            </li> <li>        });</li> <li style="background: #f3f3f3">    });</li> <li><span style="color:#0000ff">&lt;/</span><span style="color:#800000">script</span><span style="color:#0000ff">&gt;</span></li> </ol> </div> </div> </div> <p>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:</p> <blockquote> <h6><font style="background-color: #cccccc">jQuery.getJSON( url, [ data ], [ callback(data, textStatus) ] )</font></h6> <p><font style="background-color: #cccccc"><strong>url - </strong>A string containing the URL to which the request is sent.</font></p> <p><font style="background-color: #cccccc"><strong>data - </strong>A map or string that is sent to the server with the request.</font></p> <p><font style="background-color: #cccccc"><strong>callback(data, textStatus) - </strong>A callback function that is executed if the request succeeds.</font></p> </blockquote> <p>So the code to call the Bing Maps REST API to query the location of an non-structured address using the following url </p> <pre><a href="http://dev.virtualearth.net/REST/v1/Locations/query?key=BingMapsKey">http://dev.virtualearth.net/REST/v1/Locations/query?key=BingMapsKey</a></pre> <p>You’ll notice you will need to put your own Bing Maps key into the url which you can get from <a href="http://www.bingmapsportal.com/">http://www.bingmapsportal.com/</a>. Here is the code we need to make the call in Jquery.

<br /></p>

<div style="padding-bottom: 0px; margin: 0px; padding-left: 0px; padding-right: 0px; display: inline; float: none; padding-top: 0px" id="scid:9ce6104f-a9aa-4a17-a79f-3a39532ebf7c:fbd4f37b-c199-4f89-9e24-f225f448e15d" class="wlWriterEditableSmartContent"> <div style="border: #000080 1px solid; color: #000; font-family: 'Courier New', Courier, Monospace; font-size: 10pt"> <div style="background: #ddd; max-height: 300px; overflow: auto"> <ol style="background: #ffffff; margin: 0 0 0 2.5em; padding: 0 0 0 5px; white-space: nowrap"> <li>$(document).ready(<span style="color:#0000ff">function</span> () {</li> <li style="background: #f3f3f3">    $(<span style="color:#800000">&quot;#btnSearch&quot;</span>).click(<span style="color:#0000ff">function</span> () {</li> <li>        <span style="color:#006400">//check user has entered something first</span></li> <li style="background: #f3f3f3">        <span style="color:#0000ff">if</span> ($(<span style="color:#800000">&quot;#txtAddress&quot;</span>).val().length &gt; 0) {</li> <li>            <span style="color:#006400">//send location query to bing maps REST api</span></li> <li style="background: #f3f3f3">            $.getJSON(<span style="color:#800000">&#39;http://dev.virtualearth.net/REST/v1/Locations?query=&#39;</span> + $(<span style="color:#800000">&quot;#txtAddress&quot;</span>).val() + <span style="color:#800000">&#39;&amp;key=YOURBINGMAPSKEY&amp;jsonp=?&#39;</span>, <span style="color:#0000ff">function</span>(result) {</li> <li>                alert(<span style="color:#800000">&quot;got a result&quot;</span>);</li> <li style="background: #f3f3f3">            });</li> <li>        }</li> <li style="background: #f3f3f3">        <span style="color:#0000ff">else</span> {</li> <li>            $(<span style="color:#800000">&quot;#results&quot;</span>).html(<span style="color:#800000">&quot;please enter an address&quot;</span>);</li> <li style="background: #f3f3f3">        }</li> <li>    });</li> <li style="background: #f3f3f3">});</li> </ol> </div> </div> </div> <p>&#160;</p> <p>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. </p> <p><strong>The critical part of this url is the addition of the “&amp;jsonp=?” to the end of the url, this allow jquery to create a proxy allowing your code to make a cross domain call to a different url than the one the page is running on.</strong> Without this javascript would not be able to make the call to the Bing Maps REST API. The “?” is where jquery does its magic and behind the scenes wires up your success callback code (the second parameter) and the callback that is sent to the Bing Maps REST API. </p> <p>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.</p> <h3>Reading the data returned</h3> <p>The data returned by the location service is quite complex and its easier to explore using a tool like firebug (the firefox plugin) or IE or chromes built in javascript debuggers. Here is a screen shot of what the data looks like returned from this call.</p> <p><a href="http://earthware-website.azurewebsites.net/Content/images/wp-images/2010/10/bingmapsreturned.gif"><img style="background-image: none; border-right-width: 0px; padding-left: 0px; padding-right: 0px; display: inline; border-top-width: 0px; border-bottom-width: 0px; border-left-width: 0px; padding-top: 0px" title="bingmapsreturned" border="0" alt="bingmapsreturned" src="http://earthware-website.azurewebsites.net/Content/images/wp-images/2010/10/bingmapsreturned_thumb.gif" width="458" height="482" /></a></p> <p>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. </p> <p>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.</p> <p> <div style="padding-bottom: 0px; margin: 0px; padding-left: 0px; padding-right: 0px; display: inline; float: none; padding-top: 0px" id="scid:9ce6104f-a9aa-4a17-a79f-3a39532ebf7c:79aa6995-c678-485b-8458-10b34074375a" class="wlWriterEditableSmartContent"> <div style="border: #000080 1px solid; color: #000; font-family: 'Courier New', Courier, Monospace; font-size: 10pt"> <div style="background: #ddd; max-height: 500px; overflow: auto"> <ol style="background: #ffffff; margin: 0 0 0 2.5em; padding: 0 0 0 5px; white-space: nowrap"> <li>$(document).ready(<span style="color:#0000ff">function</span> () {</li> <li style="background: #f3f3f3">    $(<span style="color:#800000">&quot;#btnSearch&quot;</span>).click(<span style="color:#0000ff">function</span> () {</li> <li>        <span style="color:#006400">//check user has entered something first</span></li> <li style="background: #f3f3f3">        <span style="color:#0000ff">if</span> ($(<span style="color:#800000">&quot;#txtAddress&quot;</span>).val().length &gt; 0) {</li> <li>            <span style="color:#006400">//send location query to bing maps REST api</span></li> <li style="background: #f3f3f3">            $.getJSON(<span style="color:#800000">&#39;http://dev.virtualearth.net/REST/v1/Locations?query=&#39;</span> + $(<span style="color:#800000">&quot;#txtAddress&quot;</span>).val() + <span style="color:#800000">&#39;&amp;key=YOURBINGMAPSKEY&amp;jsonp=?&#39;</span>, <span style="color:#0000ff">function</span> (result) {</li> <li>                <span style="color:#0000ff">if</span> (result.resourceSets[0].estimatedTotal &gt; 0) {</li> <li style="background: #f3f3f3">                    <span style="color:#0000ff">var</span> loc = result.resourceSets[0].resources[0].point.coordinates;</li> <li>                    $(<span style="color:#800000">&quot;#results&quot;</span>).html(<span style="color:#800000">&#39;latitude:&#39;</span> + loc[0] + <span style="color:#800000">&#39;, longitude:&#39;</span> + loc[1]);</li> <li style="background: #f3f3f3">                }</li> <li>                <span style="color:#0000ff">else</span> {</li> <li style="background: #f3f3f3">                    $(<span style="color:#800000">&quot;#results&quot;</span>).html(<span style="color:#800000">&quot;sorry that address cannot be found&quot;</span>);</li> <li>                }</li> <li style="background: #f3f3f3">            });</li> <li>        }</li> <li style="background: #f3f3f3">        <span style="color:#0000ff">else</span> {</li> <li>            $(<span style="color:#800000">&quot;#results&quot;</span>).html(<span style="color:#800000">&quot;please enter an address&quot;</span>);</li> <li style="background: #f3f3f3">        }</li> <li>    });</li> <li style="background: #f3f3f3">});</li> </ol> </div> </div> </div> </p> <h3>Summary</h3> <p>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. </p> <p>To try it out for yourself, download the code <strong><font color="#ff0000">using the link below and add your own </font></strong><a href="http://www.bingmapsportal.com/"><strong><font color="#ff0000">bing maps key</font></strong></a></p> <p>.<a href="http://earthware-website.azurewebsites.net/Content/images/wp-images/2010/10/JqueryRESTDemo.zip"><img alt="butdownloadcode[1]" src="http://earthware-website.azurewebsites.net/Content/images/wp-images/2010/03/butdownloadcode1.gif" /></a></p>
Close chatbot
Open chatbot
Open chatbot