API Usage

Calling the API

You can extend the carquery javascript object by writing your own API calls. Here’s how:

//NOTE: Inside the carquery object, this.base_url will contain the location of the current version of the CarQuery API

$.getJSON(this.base_url+"?callback=?", {cmd:"getMakes", year:"2009"}, function(data) {

   //The 'data' variable contains all response data.
   var makes = data.Makes;
   for (var i = 0; i < makes.length; i++)
   {
       //You can now do what you like with the response data
       alert(makes[i].make_display);
   }
});

$.getJSON is a jQuery method with asynchronously retrieves data from a remote API. When the API response is received, the code inside the provided function is executed.
Please see the jQuery.getJSON() documentation for more information.

In this example the following parameters are passed to the CarQuery api:

cmd: specifies the API function. For information on the available functions see the API Functions section below.

year: specifies the year filter. The API will return all makes which produced a model in this year.

API Functions

Here are examples of how to use the function names.

GetYears

Function: Retrieve range of available years from the CarQuery database.

Usage: http://www.carqueryapi.com/api/0.3/?callback=?&cmd=getYears

Response:

?({
Years: {
   "min_year":"1941",
   "max_year":"2016"
}
});

Notes: The range of available years is determined by the available model data.

GetMakes

Function: Retrieve all makes which produced a model in the specified year

Usage:
http://www.carqueryapi.com/api/0.3/?callback=?&cmd=getMakes&year=2000&sold_in_us=1

Response:

?({
Makes:[
   {
    "make_id":"ac",
    "make_display":"AC",
    "make_is_common":"0",
    "make_country":"UK"
   },
   {
    "make_id":"acura",
    "make_display":"Acura",
    "make_is_common":"1",
    "make_country":"USA"
   },
  {etc...}
]});

Notes: “sold_in_us” parameter is optional. Setting it to “1” will restrict results to models sold in the USA.

GetModels

Function: Retrieve all model names produced by the specified manufacturer in the specified year.

Usage:
http://www.carqueryapi.com/api/0.3/?callback=?&cmd=getModels&make=ford&year=2005&sold_in_us=1&body=SUV

Response:

?({
Models:[
   {
    "model_name":"Escape",
    "model_make_id":"ford"
   },
   {
    "model_name":"Excursion",
    "model_make_id":"ford"
   },
   {etc...}
]});

Notes:
“year” parameter is optional. Omitting it will retrieve all model names ever produced by the manufacturer.
“sold_in_us” parameter is optional. Setting it to “1” will restrict results to models sold in the USA.

“body” parameter is optional. Including it will restrict results to models of the specified body type (SUV, Sedan, etc)

GetTrims

Function: Retrieve trim data for models meeting specified criteria.

Usage:
http://www.carqueryapi.com/api/0.3/?callback=?&cmd=getTrims&[params]

All parameters to getTrims are optional. You may include any of the following:

body=[Coupe, Sedan, SUV, Pickup, Crossover, Minivan, etc.]

doors=[number of doors]

drive=[Front, Rear, AWD, 4WD, etc]

engine_position=[Front, Middle, Rear]

engine_type=[V, in-line, etc]

fuel_type=[Gasoline, Diesel, etc]

full_results=[1 by default. Set to 0 to include only basic year / make /model / trim data (improves load times)]

keyword=[Keyword search. Searches year, make, model, and trim values]

make=[Make ID]

min_cylinders=[Minimum Number of cylinders]

min_lkm_hwy=[Maximum fuel efficiency (highway, l/100km)]

min_power=[Minimum engine power (PS)]

min_top_speed=[Minimum Top Speed (km/h)]

min_torque=[Minimum Torque (nm)]

min_weight=[Minimum Weight (kg)]

min_year=[Earliest Model Year]

max_cylinders=[Maximum Number of cylinders]

max_lkm_hwy=[Minimum fuel efficiency (highway, l/100km)]

max_power=[Minimum engine power (HP)]

max_top_speed=[Maximum Top Speed (km/h)]

max_torque=[Maximum Torque (nm)]

max_weight=[Maximum Weight (kg)]

max_year=[Latest Model Year]

model=[Model Name]

seats=[Number of Seats]

sold_in_us=[1(sold in US), 0(not sold in US)]

year=[Model Year]

Response:

?({
Trims: [
{
   "model_id":"15155"
  ,"model_make_id":"ford"
  ,"model_name":"Taurus"
  ,"model_trim":""
  ,"model_year":"2000"
  ,...(all available model fields are included)
 },
{
   "model_id":"15073"
  ,"model_make_id":"ford"
  ,"model_name":"Taurus"
  ,"model_trim":"3.0"
  ,"model_year":"2000"
  ,...(all available model fields are included)
  },
  {etc...}
]});

Notes: All parameters to getTrims are optional. Results are sorted by year, make, model, and trim. Results are limited to 500 records.

GetModel

Function: Retrieve all available data on the specified model.

Usage: http://www.carqueryapi.com/api/0.3/?callback=?&cmd=getModel&model=11459

Response:

?(
[{
   "model_id":"11459",
   "model_make_id":"dodge",
   "model_name":"Viper SRT10",
   "model_year":"2009",
   "model_body":"Roadster",
   "model_engine_position":"Front",
   "model_engine_cc":"8285",
   "model_engine_cyl":"10",
   "model_engine_type":"V",
   "model_engine_valves_per_cyl":"2",
   "model_engine_power_ps":"506",
   "model_engine_power_rpm":"5600",
   "model_engine_torque_nm":"711",
   "model_engine_torque_rpm":"4200",
   "model_engine_bore_mm":"102.4",
   "model_engine_stroke_mm":"100.6",
   "model_engine_compression":"10.0:1",
   "model_engine_fuel":"Gasoline - unleaded 95",
   "model_top_speed_kph":"314",
   "model_0_to_100_kph":"3.9",
   "model_drive":"Rear",
   "model_transmission_type":"Manual",
   "model_seats":"2",
   "model_doors":"2",
   "model_weight_kg":"1602",
   "model_length_mm":"4470",
   "model_width_mm":"1950",
   "model_height_mm":"1220",
   "model_wheelbase_mm":"2520",
   "model_lkm_hwy":"11",
   "model_lkm_mixed":"21",
   "model_lkm_city":"18",
   "model_fuel_cap_l":"70",
   "model_sold_in_us":"1",
   "model_engine_l":"8.3",
   "model_engine_ci":"506",
   "model_engine_valves":"20",
   "model_engine_power_hp":"499",
   "model_engine_power_kw":"372",
   "model_engine_torque_lbft":"524",
   "model_engine_torque_kgm":"73",
   "model_top_speed_mph":"195",
   "model_weight_lbs":"3532",
   "model_length_in":"176.0",
   "model_width_in":"76.8",
   "model_height_in":"48.0",
   "model_wheelbase_in":"99.2",
   "model_mpg_hwy":"21",
   "model_mpg_city":"13",
   "model_mpg_mixed":"11",
   "model_fuel_cap_g":"18.5",
   "make_display":"Dodge",
   "make_country":"USA",
   "ExtColors":[],  //Note, Color options are only available for select vehicles.
   "IntColors":[]
}]
);