Build a basic Edmunds TMV like widget with Marketcheck Cars API
Hello there,
We are getting a lot of requests from API developers on how Marketcheck Cars API could help them build a True Market Value like widget, more so since the time Edmunds retired their public API last year.
Marketcheck offers various APIs you could use to build a TMV like widget like Edmunds has.
In this recipe, we have put together details on various API calls you could use to pull market price yourself for your web / mobile app.
Steps involved in building a TMV / Market price calculator
- Build the drill down to narrow comparables from the market. This could be a single form or a wizard like interface you could build to help your users narrow down their selection criteria
- Pull market stats for the final filter criteria the users apply
- Use the market averages as returned by Marketcheck’s Inventory Search API for users selections and base off your Market Value / Price
Lets look at each step closer.
Narrow down comparables
You’d probably ask the users to select certain criteria like Car Condition (New/Used/Certified), Year, Make, Model, Trim, Color and certain options and features in order to zoom in on the comparables/listings set based on which the final market price will be calculated
Fetch all active Makes
- To pull a list of all available active makes from API
Important thing to note in this API call is the facets param. We have specified `make` as the field to get facets for. Other pipe (“|”) separated values are offset (0) and limit (100)for facets on that field, these help in paginating through the facet terms.
This API call will give you the list of makes available with us and their count as you can see in the screenshot.
Fetch all active Models for a Make
- Suppose you choose the make `Ford` and would like to get a list of all available models for ford you can query the API as follows -
Notice we have added make param with value as `Ford` in api query and changed facets field to model this time. The offset is 0 and limit is 20, this will make the API call return top 20 models for Ford from the active set of cars for sale for Ford.
This API call will give us all the models and their counts for make Ford.
Fetch all Years for a Make, Model combination
- Next if you choose ford f-150 as model, then you can query the API for all available years for that make model combo -
As you can see, now we have added model param to api query with value f-150 and changed facet field to year. This will return all available years for that make model combo.
- Once you have year, then you can choose car condition with car_type parameter, whose value can either be used or new. If unspecified API will return results for both used and new cars. Sample API query -
Of course you can change the order of the API calls to fit your needs. For instance you may start with car condition as first level filter and then drill down to the final comparable set by using Make, Model, Trim, Color fields.
Next, we describe more facet fields below that you could use.
Facet and Filter.. keep going…
Following similar pattern you can facet on multiple fields, few examples below -
To get all available trims use a query as
To get all available body_subtypes use a query as
To get all available fuel types use a query as
To get all available exterior & interior colours of these cars query as
You can see in the series of API calls above, the filter criteria is changing, mostly based on the facet response from the previous query and based on the users selection.
Following are the fields, on which you can query API for facets -
- year
- make
- model
- trim
- trim_r
- body_type
- body_subtype
- vehicle_type
- car_type
- drivetrain
- transmission
- cylinders
- fuel_type
- exterior_color
- interior_color
- city
- state
- doors
- engine
- engine_size
- engine_aspiration
- engine_block
- carfax_1_owner
- carfax_clean_title
and using these same fields you can enhance the filter criteria too as you narrow down the result sets.
Fetch Market Stats / Market Value
There are multiple ways with which you can pull market stats with the Search API or Market APIs. We’ll describe both approaches below.
Using Search API’s stats component
You can get stats/averages on price, miles and DOM(Days on Market) field using the Search API.
To get stats for various fields for a search/filter criteria, include the stats query string parameter in your Search API query, as follows
This will give you various stats on fields price, miles and dom (Days on Market). The stats response object looks like this -
From the response you can see there are lots of relevant terms you could use to come up with a market price estimate of your own.
We use Apache Solr at the back of the Search API and these responses are a wrapper on top of Solr’s stats component responses and are described here in more detail https://lucene.apache.org/solr/guide/7_4/the-stats-component.html
Using Cars Market APIs
Another alternative to using Search API (or you could choose to use this one too in addition to using Search API) is Cars Market Stats APIs
Cars Market Stats API does not allow all the various filters like the Search API does, but its faster than Search API as its pre-calculated and cached every 24 hours.
You could use filter by Year, Make, Model, Trim and can fetch stats for matching cars at City / State / Nation wide
A standard API query to pull Market Stats for a YMMT (Year, Make, Model, Trim) combination for a city, say Houston, TX would look like
with a response as follows
You could use this limited, but much faster API too in case you need market stats only on YMMT level. There are lots of variations to the Stats API you could use and those are documented here https://apidocs.marketcheck.com/#03d83317-c54e-41d8-a2d0-fb8eec39533b
Conclusions
So this is still a basic market value calculator you can build here as there are some enhancements still pending like -
- Filters on Installed options / features not supported yet by the Search API
- The stats are based on list price and not actual sales price
- The comparables and stats are only based on active inventory on the day. We are soon adding capabilities to pull comparables from last 3 months and base the stats based on those
Even with these limitations, some of our clients still find this useful and have integrated with the API to build the Market Value widgets in their web/mobile app. Hopefully you can use it too!
Handy Links:
- Marketcheck API Developer Portal : www.marketcheck.com
- API Documentation: apidocs.marketcheck.com
