REST Easy; Bing Maps Has You Covered

It was just 6 months ago that the Bing Maps Platform team officially launched support for the Silverlight control. This was in addition to the Bing Maps SOAP Service (via Windows Communication Foundation) and the AJAX Control that have been in use for years now. Today, we’re announcing a REST interface into those wonderful maps, aerial images, and geocoding and routing systems for your grubby coding hands to get all dirty. And, the beauty with REST is that you simply need to build URL queries and handle the JSON or XML responses. It’s quite beautiful actually and it’s essentially the way the WWW was architected, so the learning curve will be fairly flat. If you’re too excited to read on and want the SDK now, you can view it online or download it from the Bing Maps Platform site.

Okay, so here’s the scoop on the Bing Maps REST APIs. There are main 4 APIs that allow you to do Geocoding, Render Maps and Imagery, Calculate Routes and Perform Batch Geocoding. Let me break it down for you…

Locations API. The Locations API is for geocoding on the fly. So, in your application when a user enters an address you’ll want to hit the Location API to get a response. The Location API contains 3 main functions:

Location by Address – Pass in an address and we’ll send back a lat/lon pair.

Sample: http://dev.virtualearth.net/REST/v1/Locations/US/WA/98052/Redmond/1 Microsoft Way?o=xml&key=BingMapsKey

Location by Point – Pass in a lat/lon pair and we’ll send back an address (reverse geocoding).

Sample: http://dev.virtualearth.net/REST/V1/Locations/47.64054,-122.12934?o=xml&key=BingMapsKey

Location by Query – Pass in a string (address or landmark) and we’ll send back a lat/lon pair.

Sample: http://dev.virtualearth.net/REST/v1/Locations/1 Microsoft Way Redmond WA 98052?o=xml&key=BingMapsKey

Imagery API. The Imagery API is for getting maps and aerial photos. When you’re ready to show a map of a location you will want to use the Imagery API. Also, the Imagery API grants you access to imagery metadata such as capture date and provider information.

Map – Getting a map image based on an address, landmark or lat/lon pair.

Sample (Road): http://dev.virtualearth.net/REST/V1/Imagery/Map/Road/space needle,seattle?mapLayer=TrafficFlow&key=BingMapsKey

Sample (Aerial with Labels): http://dev.virtualearth.net/REST/v1/Imagery/Map/AerialWithLabels/statue of liberty nyc?mapSize=800,600&key=BingMapsKey

Imagery Metadata – Getting imagery vintage or provider information based on a lat/lon pair.

Sample: http://dev.virtualearth.net/REST/V1/Imagery/Metadata/Aerial/40.714550167322159,-74.007124900817871?zl=15&output=xml&key=BingMapKey

Routes API. The Routes API is for calculating driving directions. The Routes API allows you to get route distance calculations, route geometry and step-by-step directions via driving, walking or traffic based algorithms. You can also pass in up to 25 points on your route to calculate a multiple stop route in a single request.

Route – Calculating a route.

Sample: http://dev.virtualearth.net/REST/V1/Routes/Walking?wp.0=Eiffel%20Tower&wp.1=louvre%20museum&optmz=distance&output=xml&key=BingMapsKey

Spatial Data API. The Spatial Data API is for batch geocoding. Batch geocoding lets you up load a file for processing addresses through our backend systems without having to make multiple requests using the Locations API. If you have thousands of addresses to geocode at one time, you’re better off using the Spatial Data API.

Upload Data – Creates a batch geocoding job and uploads data into the cloud for geocoding.

Sample: http://spatial.virtualearth.net/REST/v1/Dataflows/Geocode?input=xml&description=My dataflow&key=BingMapsKey

Check Job Status – Checks to see whether the job is complete.

Sample: http://spatial.virtualearth.net/REST/v1/Dataflows/e14b1d9bd65c4b9d99d267bbb8102ccf?key=b1c323ea234

Download Data – Once the job is complete, you’ll download the geocoded data.

Sample: https://spatial.virtualearth.net/REST/v1/dataflows/Geocode/5bf10c37df944083b1879fbb0556e67e/output/succeeded&key=MyDataflowJobKey

The REST API also has contextual and cultural properties. Optionally, if you want to shorten the URLs you’re using, you can substitute many of them with acronyms. If you want to show maps in French instead of English, you can set the culture to fr-FR. Also note that all of the sample requests I provided have the “key=BingMapsKey” parameter appended to them. You will need a Bing Maps Key to do any development; but worry not! Keys are free for all to use for developing applications. Get a key in the Bing Maps Portal.

Bing Maps AJAX Control Update – We also enhanced the Bing Maps AJAX Control with some streamlined features and a stripped down mode for light mapping techniques. The new AJAX Control is version 6.3 and has the following changes.

Core functionality version of the map control. The Bing Maps AJAX Control is now available in both full functionality and core functionality versions. If you do not have advanced mapping needs, you can enhance the performance of your map control application by using the core version of the latest map control. Note the version number (v=6.3c) for the core control which is now a slimmed down 35kb!

Sample: <script charset=”UTF-8″ type=”text/javascript” src=”http://ecn.dev.virtualearth.net/mapcontrol/mapcontrol.ashx?v=6.3c&mkt=en-us”></script>

New Search and Geocode methods. The new VEMap.Search Method and the VEMap.Geocode Method provide an easier way to return the most accurate search results. The current VE.Find Method has like 11 arguments for making your request more specific. If you know what you want and would rather slim your request down to 3 (query, callback, options).

Sample (Geocode): map.Geocode(‘1 Microsoft Way, Redmond, WA’, findCallback, options);

Sample (Search): map.Search(‘Fish Tacos in San Diego’, findCallback, options);

Drag-able pushpins. With the latest version of the Bing Maps AJAX Control, your pushpins become drag-able by simply setting the VEShape.Draggable Property of the pushpin to true. There are also optional events associated with the dragging motion that you can capture and fire off additional events such as search queries or grabbing pixels to convert to lat/lons.

Sample:

var pushpin = null;

pushpin = new VEShape(VEShapeType.Pushpin, map.GetCenter());

pushpin.Draggable = true;

pushpin.onstartdrag = StartDragHandler;

pushpin.ondrag = DragHandler;

pushpin.onenddrag = EndDragHandler

All good stuff for you Bing Maps Platform developers! I certainly hope to see some cool applications coming from these new APIs. And, if you are a developer, don’t forget to check out the Bing Map Apps API that was also released today. The Bing Map Apps API allows you to submit your Silverlight application to be published on Bing Maps!

Follow me @BingMaps, ^CP

Join the conversation

11 comments
  1. hotels

    @Cecile The faq for this has further instructions on this.

  2. cecile.muller

    That all looks great, especially the REST API, thanks for the article.

    However, am I missing something: "www.bing.com/maps/" seems to handle touch-pan and pinch-zoom fine on the iPhone, yet even the 6.3 mapcontrol doesn't seem to do either of these things ?

    If it is the case, I wish they had integrated their obviously working and well-tested solution in the mapcontrol as well instead of having users try to figure out a hack to make it work. :/

  3. Chris Pendleton

    @stefan – The best I can offer you is a hack. It's not supported and will only handle so many lat/lons, but if you use the GetDirections method and pass in lat/lons the engine will reverse geocode them in the response. You'll have to use a call back to catch them, rip them out of the response and use them how you want. You can pass up to 25 points in the to GetDirections method. Other than that, an AJAX version of the reverse geocode method will only handle one lat/lon at a time.

    CP

  4. stefan.finnsjo

    Hi!

    I'm looking for a way to send multiple positions for reverse geocoding in one ajax request. I know there is a batch api but this cannot be used via ajax.

    Is it possible to do this today or will it be possible in the near future?

    Cheers,

    Stefan

  5. lovepreet

    i had a question on spatial geocoding with Rest service. I am sending input (file with addresses to geocode) as XML with the HTTP request and want the result to be in JSON format.

    In this link

    msdn.microsoft.com/…/ff701737.aspx

    it is explained how we can decide the format of the input and output by specifying certain fields in the HTTP request URL. Also, it tells that inputs allowed are only XML, csb,tab or pipe type while the output can be only xml or JSON and the by default the output is JSON.

    So, I send input in XML but don't get the output in JSON which is what it should be by default accoring to the article in the link. Even when I explicitly mention it be JSON by specifying the output field in the URL of the request, it still comes back as XML.

    Another link

    msdn.microsoft.com/…/ff701732.aspx

    says that output will be in same format as the input which is in contradiction to the option of defining your choice in the input. So, basically do we have an option to decide what the output should be or not?

    If anyone can basically help me get the output in JSON, I will appreciate it.

    Thanks,

    Lovepreet

  6. Chris Pendleton

    @Dean – You can absolutely stop using the token service. You can use App ID (aka Bing Maps Keys). Go to BingMapsPortal.com for keys.

    CP

  7. dean.poulin

    This is great news.  We're using the bing maps webservice on the server side and we'd like to move all this work to the client side.  

    Does utilization of this RESTful interface require client tokens as the web service implementation requires?  

    If I can get rid of having to generate client tokens in background threads I will be an extremely happy camper!

  8. lovepreet

    hi gerald,

    did you ever get any reply on to your question because I am also working on the same thing and having hard time deserializing the json result file. Actually, I don't even get a json file. It's a xml file with the geocoded result. Please let me know if you go any reply or figured out some example that does the whole spatial geocoding process.

  9. gzylicz

    Can't get the Spatial Data API examples to work for batch Geocoding.  Is anyone successfully using this?

  10. johanneselsinghorst

    with the soap geocoder one can simply geocode a "string" and will get a list of addresscandidates back. The spatial data API seems to be different here: one has to split the input into street,locality etc. beforehand which is a tough job and one of the main advantages. Is there some kind of workaround like putting the whole input in the addressline or something?  Thanks, J.

  11. Lowry

    This seems cool for developers.

Comments are closed.