In my last post, I mentioned the “starter-kit” applications my colleagues and I have built around the many open APIs available across the web. My contribution to this effort is a sample that leverages both the Bing Maps control and API and the TomTom Traffic Cams API to show the location of and display the images captured by over 13,000 traffic cameras in the US and Canada. In this first of some deeper-dive posts, I’ll provide an overview of how the application is structured, so you can plug-in your own location-centric API to create a completely new app!
To follow along, I suggest downloading the APIMASH projects from GitHub, specifically the one in the APIMASH_TomTom_BingMaps_StarterKit folder. It contains the three Visual Studio projects discussed next. And as also mentioned in my previous post, can get your own API keys from Bing Maps and Mashery to run the sample code.
This class library provides the lower-level plumbing for making HTTP GET requests to an API provider and deserializing the results into a class you've provided. In most cases, you shouldn’t need to touch the code here.
The core class here is ApiBase, which should be the base class for any additional APIs you integrate into this application framework. ApiBase exposes two members:
There are three other classes of note in this library:
This library houses the classes derived from ApiBase that drive the application. In the starter-kit there are two classes provided, one for Bing Maps and the other for TomTom, but the structure of each (and that of any others you might add) is identical and includes the following components:
In this starter-kit, you'll note there are PopulateViewModel static methods defined on the Model class that transfer (and optionally modify) elements from the Model class to the ViewModel class to provide a format conducive to databinding to the user interface. These methods are invoked in the body of each specific API method after receiving the response from the associated API invocation.
In this project you’ll also find a static class of utilities and types for mapping applications as well as the more pivotal IMappable interface. That interface should be implemented by whatever ViewModel class you are planning to build your application around, so that you can easily leverage the built-in synchronization between the class and the Bing Maps control.
If all that sounds a bit convoluted, I’ve include the diagram below to map out the relevant parts of a representative API class, the TomTom API which is used in the sample starter kit.
The Windows Store application includes two pages, a main page (MainPage.xaml) and a search results page (LocationSearchResultsPage.xaml), representative images of which appear below. The main page includes the Bing Maps control as well as a user control (LeftPanel.xaml) in which are shown the cameras retrieved from the TomTom API (or whatever other items you want to display from your API of choice).
In this starter kit, MainPage.xaml contains the Bing Maps control and all of the map-specific functionality for your application. It interacts with the Bing Maps API on your behalf, so you don’t really need the change any code within it. Likewise, the landing page for the Search contract (LocationSearchResulsPage.xaml) provides a generic location search capability for your application so no modifications are required there either.
The UserControl LeftPanel.xaml is where API-specific code is centralized. It’s here where I instantiate an instance of the TomTom API class, invoke the methods to retrieve the traffic cameras, and bind the resulting data to a ListView (and an image control). The collection to which the list view is bound has code (also included) that synchronizes the placement of pins on the map, so as long as the class of items contained in that collection implements IMappable you don’t have to write any code to update the map. Likewise, tapping a map pin will select the appropriate element of the list view (and vice versa).
There are two other user controls in this project, but neither require any modifications.
In the next article, I'll focus more deeply on the implementation of the left panel user control and show how you can mash up a completely different API!