APIMASH: The Edmunds API Starter Kit – The Undocumented API
Edmunds Starter Kit
Loading...
X

APIMASH: The Edmunds API Starter Kit

The APIMASH Edmunds StarterKit is a XAML/C# Windows 8 app based on the default Blank Template that demonstrates calling the Edmunds Vehicle API’s.

For an overview of the APIMASH Starter Kits and their architecture see this article.

The JSON payload for Makes, Models, Model Specs and Pictures is deserialized into a set of C# classes that define the Data Model. That data then is selectively copied into the View Model for binding to WinRT XAML controls. You can use the breadth and detail of the automotive information available through the Edmunds API to create mashups, visualizations and other applications that will provide an added dimension of user experience for the automotive consumer.

Features

  • Invokes the Edmunds REST API for Make, Model, Year, Style ID and Pictures
  • Demonstrates how to deserialize JSON to C# and bind to WinRT XAML Controls
  • Provides a baseline for a Windows 8 Store App

Requirements

Setup

Updating APIMASHLib

APIMASHLib by default is using a third party library for JSON deserialization, JSON.NET. The APIMASHLib project in the Rotten Tomatoes Starter Kit Solution will show that the Newtonsoft.Json reference is broken so you will need to update that reference.

image_thumb[2]

There are 2 ways to update the reference to the Newtonsoft JSON.NET library in the APIMASHLIb project; a) Use NuGet, b) download the Zip from Json.codeplex.com and reference the DLL in the WinRT folder.

Using NuGet

To use NuGet, in Visual Studio navigate the menu Tools > Library Package Manager > Manage NuGet Package for Solution.

image_thumb[12]

Search for Json.NET and install. Request to add it to the APIMASHLib project.

image_thumb[14]

Limitations

  • The app sleeps for 1 second before each API call as to avoid invoking the Edmunds API too often. You will receive notifications by email to your developer email address if you invoke the API more than once or twice a second.
  • Not all invocations return pictures as the programming logic does not apply any intelligence to picture request which is based on Style ID.
  • Only the first style ID retrieved is used. There though a list of style IDs that is retrieved that could be leveraged to pull additional images

Customization

The Edmunds API, one a scale of 1 to 10, where 1 is simple and 10 is complex, is an 11 :). Edmunds provides a rich set of API collections each with several API’s and methods that give you access to Articles, Vehicle Data, Dealer info and Inventory data that can be used together or with other API’s to create compelling apps.

Edmunds provides these 4 API collections:

The Edmunds Starter Kit uses the following API’s in the Vehicle API collection:

  • Make Repository – The Make repository provides information according to the Make of a vehicle
  • Model Year Repository – The Model Year repository is the root entity of the Edmunds data repository. All vehicles data is organized according to Model Year
  • Photo Repository – The Photo Repository provides links that resolve back to photo media on the Edmunds Media Server

Step 1. Get the Starter Kit up and running

Open the APIMASH_Edmunds_StarterKit solution in Visual studio and open the Globals.cs source file. You can add your Developer Key on line 17

public static string EDMUNDS_API_DEVKEY = "&api_key=[YOUR-DEV-KEY-HERE]";

Note that the ‘[ ]’ should be removed as well.

Update the reference to the JSON.NET library in the APIMASHLib project to point to where the DLL is installed on your system.

Press F5.

The app by defaults queries for makes/models in 2013 and fills a ComboBox control with the makes and a ListView with the models. It then queries for the style IDs for the default selection (Audi RS 5) and uses that ID to query for photos. The user can change the Year, Make and Model selections. Note that not all selections will return images.

alt text

Step 2. Code Review Edmunds API Invocations

Edmunds has numerous API’s. This StarterKit calls a select few. The API’s that are used in this app are defined in the Globals.cs file.

The first call is to the findmakesbymodelyear method of the Make Repository API to retrieve a list of makes and models by a particular year. [*See Line 57 in the MainPage.Xaml.cs file*].

private void InvokeYearMakeModel(string year)
{
     Sleep(1000); 
     _apiInvokeYearMakeModel.OnResponse += apiInvokeYearMakeModel_OnResponse;
     var apiCall = Globals.EDMUNDS_API_FINDBYYEAR + year;
     //var apiCall = Globals.EDMUNDS_API_FINDALL;
     _apiInvokeYearMakeModel.Invoke<MakeCollection>(apiCall);
 }

Next It invokes the Model Year Repository API foryearmakemodel method to get the Model Spec data which contains a set of Style Ids. [*See line 88 in the MainPage.Xaml.cs file*]
private void InvokeModelSpecsByMakeModelYear(string make, string model, string year)
{
       Sleep(1000);
       _apiInvokeModelSpecs.OnResponse+=_apiInvokeModelSpecs_OnResponse;
       var apiCall = 
           Globals.EDMUNDS_API_MODELSPECS_MAKE + make + 
           Globals.EDMUNDS_API_MODELSPECS_MODEL + model + 
           Globals.EDMUNDS_API_MODELSPECS_YEAR + year + 
           Globals.EDMUNDS_API_DEVKEY;
       _apiInvokeModelSpecs.Invoke<ModelSpecCollection>(apiCall);
 }

The StyleId is used as input to the third call, the Vehicle Photo Repository findphotosbystyleid method that is used to get a list of vehicle images. [*See line 142 of the MainPage.Xaml.cs file*.]
private void InvokePhotoById(string styleId)
{
     Sleep(1000);
     _apiInvokePhotoByStyleId.OnResponse += _apiInvokePhotoByStyleId_OnResponse;
     var apiCall = Globals.EDMUNDS_API_PHOTOS + styleId;
     _apiInvokePhotoByStyleId.Invoke<PhotoCollection>(apiCall);
}

Step 3 Customization

You can begin your foray into customization by changing the chaing the initial call to from findmakesbymodelyear  to findall. Comment out line 61 and uncommenting line 62 in MainPage.Xaml.cs to invoke the findall method.

private void InvokeYearMakeModel(string year)
{
      Sleep(1000); 
      _apiInvokeYearMakeModel.OnResponse += apiInvokeYearMakeModel_OnResponse;
      //var apiCall = Globals.EDMUNDS_API_FINDBYYEAR + year;
      var apiCall = Globals.EDMUNDS_API_FINDALL;
      _apiInvokeYearMakeModel.Invoke<MakeCollection>(apiCall);
}

To experiment further you can look at the additional capabilities of the Make and Model/Year Repository API’s.

The Make Repository API provides the following methods:

  • findall – Get the list of all makes and their all their models
  • findbyid – Find a make and its models by providing a make ID
  • findfuturemakes – Find all future makes and their models
  • findmakebyname – Find a make details by its name
  • findmakesbymodelyear – Find a make by a year
  • findmakesbypublicationstate – Find makes by their state (new or used)
  • findnewandused – Find all new and used makes
  • findnewandusedmakesbymodelyear – Find all new and used makes for a particular year
  • findnewmakes – Find only new makes
  • findusedmakes – Find only old makes

The Model Year Repository API also provides these methods:

  • findbyid – Get details on a specifc vehicle by its model year ID
  • finddistinctyearwithnew – Get a list of years under which there are new vehicle listings
  • finddistinctyearwithneworused – Get a list of years under which there are new or used vehicle listings
  • finddistinctyearwithused – Get a list of years under which there are used vehicle listings
  • findfuturemodelyearsbymodelid – Get a list of future model years by the model ID
  • findmodelyearsbymakeandyear – Get a list of model years for a specific make and year
  • findmodelyearsbymakemodel – Get a list of model years for a specific make and model
  • findnewandusedmodelyearsbymakeidandyear – Get a list of new and used model years for a specific make ID and year
  • findnewmodelyearsbymodelid – Get a list of new model years by the model ID
  • findusedmodelyearsbymodelid – Get a list of used model years by the model ID
  • findyearsbycategoryandpublicationstate – Get a list of model years for a specific category and publication state
  • formodelid – Get a list of model years by the model ID
  • foryearmakemodel – Get a list of model years for a specific make, model and year

You can also experiment with adding in the Editorial or Dealer API’s to add color commentary and availability information.

Step 4. Mash it up

Car information is EXTREMELY mashable! Experiment by combining Edmunds Car and Dealer data with Bing Maps showing nearby offers and deals. Check out the Tom-Tom Bing Map Starter Kit or the Meetup POI Starter Kit to see how you can combine data from one API to overlay on Bing Maps.

Step 5. Submit your app to the Windows 8 Store

Once you have customized your app you are ready to submit it to the store. You will want to reserve your app name, create a set of unique Tiles and of course test, test and test some more.

For an complete overview of the store submission process check out this article.

You can find a step by step guidance for sore submission here.

Conclusion

Building compelling apps requires compelling data. Open Data API’s are an excellent way to gather and mashup new experiences for end users. The Edmunds API provides a rich set of data on cars of all makes and models. Take advantage of the data and peoples love of cars to create the next great app for Windows.

To learn more attend one of our in-person workshops or one of our Webcast Series on the APIMASH Starter Kits.  Each session will run from Noon – 1pm EDT. Attend one or all four webcasts, you decide. For more details or to register, choose a webcast below.

6/5/2013 | Exploring the Mashery APIs

Register
In this webcast you will learn how to develop Windows 8 apps using Mashery API’s such as Tom-Tom, Edmunds, Rotten Tomatoes and Active.com. Amit Jotwani from Mashery will join us to provide an overview of Mashery the industry leader in API management. We will cover how to access these web service API’s and then deserialize the response into a set of runtime objects that you can bind to Windows 8 UX Controls to create a compelling experience.

6/12/2013 | Exploring the Social Networking APIs

Register
In this webcast you will learn how to develop Windows 8 apps using the Twitter, Meetup and Facebook APIs. Twitter, Meetup and Facebook are the premier social networking sites and their API’s provide access to Tweets, Meetups and Friends. What a great combination!

6/19/2013 | Exploring the Yelp API

Register
In this webcast you will learn how to develop Windows 8 apps using the Yelp API. Yelp is a local business directory service and review site with social networking features. People use Yelp to search for everything from the city’s tastiest burger to the most renowned cardiologist.

6/25/2013 | Exploring the Bing Maps API

Register
In this webcast you will learn how to develop Windows 8 apps using the Bing Maps API. Bing Maps gives you a rich set of tools to help you create amazing map experiences perfect for mash-ups.

Lastly don’t forget to check out the “Keep the Cash Rewards” offer to see how you can get $100 for publishing your app(s) in the Windows Store and/or Windows Phone Store. Publish your app before June 30, 2013 and you can get a $100 virtual Visa card for every qualified app you enter (up to $2000*). Learn more.

-bob

One observation on “APIMASH: The Edmunds API Starter Kit
  1. Pingback: APIMASH Edmunds Starter Kit for Windows Phone 8 | BOB FAMILIAR

Leave Your Observation

Your email address will not be published. Required fields are marked *

Read previous post:
Rotten Tomatoes Starter Kit
APIMASH: The Rotten Tomatoes API Starter Kit

The APIMASH Rotten Tomatoes Starter Kit is a XAML/C# Windows 8 app based on the default Grid Template that demonstrates...

Close