/edmunds_ruby

Ruby wrapper for the Edmunds Vehicle API

Primary LanguageRubyMIT LicenseMIT

Ruby wrapper for the Edmunds Vehicle API (V2)

This API wrapper will allow you to make calls to the Edmunds Vehicle API to get detailed information about nearly any make, model, and style (trim). You can also get production images for each vehicle.

See a simple front-end demo using this gem:

http://edmunds.herokuapp.com

Code for frontend can be found here:

https://github.com/johndavid400/vehicular

Setup:

First, include the gem in your Gemfile:

vim Gemfile

gem 'edmunds_ruby', :git => "https://github.com/johndavid400/edmunds_ruby.git", :branch => "v2"

bundle

Now add your API key

Get Edmunds Vehicle API key:

You will need to create an account with Edmunds and get a free developer Vehicle API key from here:

http://developer.edmunds.com

Once you get your API key, either create an initializer file to place it in OR add it to your .bashrc script

option 1 - put api key in an initializer file:

Create a new file in config/initializers called edmunds.rb, like so:

vim config/initializers/edmunds.rb

Add this line, with your api key:

Rails.configuration.edmunds_vehicle_api_key = "your_api_key_here"

Save the file and exit.

option 2 - put api key in your .bashrc script:

Open .bashrc file:

vim ~/.bashrc

Add this line near the top of the file:

export EDMUNDS_VEHICLE="your_api_key_here"

Save and close the file, then source the file to make the changes take effect:

source ~/.bashrc

Now you can use the Vehicle API as you like.

Verify API key:

Open a console and try this:

Edmunds::API.new.api_key

You should see your API key returned... if not, go back to the above steps and verify that you have it in an initializer or your bashrc script as described.

Usage:

To use the gem, open a console and start playing. There are currently 5 classes you can call: Make, Model, ModelYear, Style, and Photo

Some of the methods require inputs, others do not. Let's try an easy one first:

m = Edmunds::Make.new
m.find_all

This should return a list of all vehicle makes in the system.

For the Model class, you will have to provide an id first (which you can get from a Make response)

m = Edmunds::Model.new
m.find_by_id("Lamborghini_Diablo")

Here is a complete list of available methods:

The method descriptions were pulled from the Edmunds API documentation.

http://developer.edmunds.com/docs/read/Home

The method names in this wrapper were kept as close to the original Edmunds API method names as possible, to avoid confusion.

While I plan on wrapping the entire Vehicle API, I currently only have the Make, Model, ModelYear, Style, and Photo methods covered.

Edmunds::Make.new

http://developer.edmunds.com/docs/read/the_vehicle_api/Make_Repository

find_all                                          # Get the list of all makes and their all their models
find_by_id(make_id)                               # Find a make and its models by providing a make ID
find_future_makes                                 # Find all future makes and their models
find_make_by_name(name)                           # Find a make details by its name
find_makes_by_model_year(model_year)              # Find a make by a year
find_makes_by_publication_state(state)            # Find makes by their state (new or used)
find_new_and_used                                 # Find all new and used makes
find_new_and_used_makes_by_model_year(model_year) # Find all new and used makes for a particular year
find_new_makes                                    # Find only new makes
find_used_makes                                   # Find only old makes

Edmunds::V2::Make.new (arguments with * are optional)

get_makes(state*, year*, view*)                      # Get the list of all makes
get_details_by_name(name, state*, year*, view*)      # Get a make and its models by providing its name (ie: 'lexus')
get_count(state*, year*, view*)                      # Get count of all makes 

Edmunds::Model.new

http://developer.edmunds.com/docs/read/the_vehicle_api/Model_Repository

find_by_id(model_id)                                   # Get a vehicle's model details by the model ID
find_by_make_id(make_id)                               # Get a vehicle's model details by the make ID
find_future_models_by_make_id(make_id)                 # Get a list of all future models by the make ID
find_model_by_make_model_name(make, model)             # Get a vehicle model by the make and model names
find_models_by_make(make)                              # Get a list of models by the make name
find_models_by_make_and_publication_state(make, state) # Get a list of models by the make name and the publication state
find_models_by_make_and_year(make, year)               # Get a list of models by the make name and year
find_new_and_used_models_by_make_id(make_id)           # Get a list of new and used models by the make ID
find_new_models_by_make_id(make_id)                    # Get a list of new models by the make ID
find_used_models_by_make_id(make_id)                   # Get a list of used models by the make ID

Edmunds::V2::Model.new

  get_models_by_make(make, state*, year*, view*, submodel*, category*)                     # Get models by vehicle make name
  get_details_by_make_and_model(make, model, state*, year*, view*, submodel*, category*)   # Get details by make and model names
  get_count_by_make(make, state*, year*, view*, submodel*, category*)                      # Get model count by make name

Edmunds::ModelYear.new

http://developer.edmunds.com/docs/read/the_vehicle_api/Year_Repository

find_by_id(model_year_id)                                        # Get details on a specifc vehicle by its model year ID
find_distinct_year_with_new                                      # Get a list of years under which there are new vehicle listings
find_distinct_year_with_new_or_used                              # Get a list of years under which there are new or used vehicle listings
find_distinct_year_with_used                                     # Get a list of years under which there are used vehicle listings
find_future_model_years_by_model_id(model_id)                    # Get a list of future model years by the model ID
find_model_years_by_make_and_year(make, year)                    # Get a list of model years for a specific make and year
find_model_years_by_make_model(make, model)                      # Get a list of model years for a specific make and model
find_new_and_used_model_years_by_make_id_and_year(make_id, year) # Get a list of new and used model years for a specific make ID and year
find_new_model_years_by_model_id(model_id)                       # Get a list of new model years by the model ID
find_used_model_years_by_model_id(model_id)                      # Get a list of used model years by the model ID
find_years_by_category_and_publication_state(category, state)    # Get a list of model years for a specific category and publication state
for_model_id(model_id)                                           # Get a list of model years by the model ID
for_year_make_model(year, make, model)                           # Get a list of model years for a specific make, model and year

Edmunds::V2::ModelYear.new

  get_model_years_by_make_model(make, model, state*, view*, submodel*, category*)       # Get model years by make and model name
  get_style_by_make_model_year(make, model, year, state*, view*, submodel*, category*)  # Get style details by make name and model year
  get_count_by_make_model(make, model, state*, view*, submodel*, category*)             # Get count by make and model names

Edmunds::Style.new

http://developer.edmunds.com/docs/read/the_vehicle_api/Style_Repository

find_by_id(style_id)                              # Get a style details by the style ID
find_styles_by_make_model_year(make, model, year) # Get a list of styles by make, model and year
find_styles_by_model_year_id(model_year_id)       # Get a list of styles by model year ID

Edmunds::V2::Style.new

  get_style_by_style_id(style_id, view*)                                                 # Get style by Edmunds style id
  get_style_by_make_model_year(make, model, year, state*, view*, submodel*, category*)   # Get style by make, model, and year
  get_style_by_chrome_id(chrome_id)                                                      # Get style by Chrome ID
  get_style_count(state*)                                                                # Get style count
  get_style_count_by_make(make, state*)                                                  # Get style count by make
  get_style_count_by_make_model(make, model, state*)                                     # Get style count by make and model
  get_style_count_by_make_model_year(make, model, year, state*)                          # Get style count by make, model, and year

Edmunds::Equipment.new

Documentation for these methods was derived from the API console page:

http://developer.edmunds.com/io-docs

find_engines_by_style_id(style_id)         # Get engine details by the style ID (includes Horsepower)
find_transmissions_by_style_id(style_id)   # Get transmission details by the style ID

Edmunds::Photo.new

http://developer.edmunds.com/docs/read/the_vehicle_api/Photos

find_by_style_id(style_id)          # Get an array of photo detail objects for a particular vehicle style
find_sample_by_style_id(style_id)   # Get a sample photo url for a particular vehicle style - tries to get a exterior front view image if available.

Note that the image arrays returned by the find_photos_by_style_id() method return an array of image links that will still need the base url attached to them in order to view the image.

The image base url can be accessed from any of the classes, for instance these all return the same image base url:

Edmunds::API.new.image_base_url
Edmunds::Make.new.image_base_url
Edmunds::Photo.new.image_base_url

or if you set the new instance to a variable:

p = Edmunds::Photo.new
p.image_base_url

Will both return the base url (url prefix) that must be prepended to the links returned by the Photo API method.

With this in mind, I added that last photo method to grab a sample url for an image of any style, then go ahead and add the image base url to the beginning, thus making a valid url that you can click on to see the image... it is not listed as an Edmunds API method, but I found it useful.

More documentation on the way...

Bug reports and Pull requests

Please open an issue on Github if you find a bug, and I will address it.

If you have an improvement to submit, please fork the repo, add your code and send a pull request.