Market Comparison Scatter plot with Marketcheck API

You can build various market comparison reports/widgets/graphs based on data provided by Marketcheck API. Like - time on market of the car, and Market comparison of car based on its price and miles compared with similar cars.

From here on you’ll see lots of API calls that you can make, all of which contain an api_key parameter. This is a required parameter in Marketcheck API (used for authentication purposes) which you can obtain by signing up at Marketcheck’s developer portal at

API Calls

Okay now lets turn our attention to actual API calls that you will need to make to get the data needed for such scatter plots and graphs.
Suppose you have a car whose VIN (Vehicle Identification Number), price, and miles are known to you, then to find similar cars based on that VIN you can make API call like this -<your_api_key>&car_type=used&vins=1FTEW1EG8HFA58169&match=year,make,model,trim&plot=true&stats=price,miles

Now let’s dissect this API call (we’ll discuss various parameters used and their meaning) —

  1. car_type — This param is used to indicate car condition, i.e. whether it is a new or used car. Accordingly the value of this parameter can be used or new.
  2. vins — To search similar cars you can use vins param here, the value of this param can be the 17 digit VIN of a car. (Note :- Be sure to use vins and not vin here!). To search similar cars for multiple VINs (cars), you can provide multiple values to this param separated by comma like — vins=1FTEW1EG8HFA58169,1N6AD0EV2JN714176
  3. match — What do you want similar cars to match on? The value of this parameter can be year, make, model, trim OR year, make, model. This parameter works in combination with vins param to get you similar cars based on given vin matching on year, make, model and/or trim
  4. plot — By default Marketcheck API returns only 10 listings per API call with lots of fields, all of which are not be needed for our scatter plot. So to get more number of listings in one go with only the fields that matter (like price, miles, DOM and VIN), use this plot param whose value can be either true or false. With plot you can get upto 1000 listings in one go with limited number of fields. We can use all these listings and their price and miles for plotting all the similar cars on the graph
  5. stats — Marketcheck API also provides stats on matched set of listings to your search criteria. Like with our example, say API returns listings for1500 for sale cars that are similar to our car, then by just appending stats param at the end you can request stats on various numeric fields like price, miles, DOM etc. As you can see with this API call you can request stats on multiple fields in one go just by specifying them as value to stats param, separated by comma like stats=price,miles,dom

And there you have it! With this single API fetch you have similar cars and all the necessary data points required for creating scatter plot shown above in the image. Below is the sample response —

Sample API response — 1

Sample API response — 2

This is the type of response you will see with above API call,

  1. num_found :- Tells you the number of similar cars found
  2. listings :- Array that actually contains all the listings.
  3. stats :- Object with all the fields as key on which stats were requested, In our case price and miles.

So, from this API response you can use price and miles of each listing to plot similar car on scatter plot, with miles on x-axis and price on y-axis. Depending on the library that you use for generating scatter plot, you can iterate over listings array, that will contain all the similar cars. From value of stats key in JSON response you can use mean of price and miles to plot national average of the similar cars (Shown in special colour — green in our example).
As mentioned above it is assumed you have prior knowledge of price, miles and VIN of your car, So now you can use those price and miles to plot your car as well on the scatter plot (Again shown in special colour — red in our example)

Similar cars near me?

Obviously this only found similar cars on national level ( i.e. for entire US). You can go one step further and get similar cars that are near you using geo-spatial query with API and plot only those and display their averages as an extra data point on the scatter plot. To make geo specific query to API, you can just append corresponding latitude, longitude, and radius to the API call like-<your_api_key>&car_type=used&vins=1FTEW1EG8HFA58169&match=year,make,model&plot=true&stats=price,miles&latitude=34.02&longitude=-118.28&radius=100

With this API you will get similar cars that are nearby given latitude, longitude and within specified radius and plot those.