Find Similar Cars — Marketcheck API
Sometimes, with all the features and parameters available with Marketcheck search API, It gets confusing for users to decide how to use different parameters to get what they want.
One similar situation is when you want to find similar cars to your current car.
Here in this article we will try and reduce this complexity by explaining various parameters available with API and their proper usage. Lets start by explaining few terminology we will be using.
VIN
VIN means vehicle identification number. A VIN is composed of 17 characters (digits and capital letters) that acts as a unique identifier for each vehicle. A VIN displays the car’s unique features, specifications and manufacturer. The VIN can be used to track recalls, registrations, warranty claims, thefts and insurance coverage. To read more about VIN and significance of each letter in it visit this wikipedia page.
Taxonomy VIN
A VIN has 17 digits out of which last 6 letters are for vehicle serial number and do not signify any specifications. So when you remove those last 6 digits and 9th digit(security check digit) what you are left with is 10 digit taxonomy vin aka Squish VIN, that tells you a lot about specification of the car. For example for this VIN 3FADP4BJ6HM166161 its corresponding taxonomy vin will be 3FADP4BJHM.
Now lets take a look at various API parameters that will allow you to search similar cars based on the VIN.
It is assumed here on that you have a single/ multiple car VINs with you and want to find exactly those car/s or similar cars.
Find Exact VIN
Suppose the VIN you are querying the API with is currently active in the market i.e. car is available for sale. And you want the listings that are listed online for the given VIN. In this case you want listings that have the same exact VIN which you are providing, and not the similar cars. For this purpose you can use vin parameter of the API, that lets you fetch the exact VIN. For example —
https://marketcheck-prod.apigee.net/v2/search/car/active?api_key=<your_api_key>&car_type=used&vin=1FTEW1EG9HKC35917
(Note :- Depending upon when you are reading this article, this particular VIN 1FTEW1EG9HKC35917 may or may not be active in the market. If its not active then replace this VIN with any other that’s currently active)
This API call returns one active listing for this VIN (See num_found: 1) that is deduped by Marketcheck. So it is possible that this VIN is listed online across many sites and if you want all those available listings for this VIN then you can tell API to skip the deduping using nodedup=true parameter, Like —
https://marketcheck-prod.apigee.net/v2/search/car/active?api_key=<your_api_key>&car_type=used&vin=1FTEW1EG9HKC35917&nodedup=true
As you can see, at the time of writing this article, the total number of active listings for this VIN are 12.
Find Similar cars — vins, taxonomy_vins
Okay now you don’t want only that particular car, but other similar cars also. And what you want to find similar cars based on is all the specifications of the car. As stated above, specifications of a car are represented in its taxonomy_vin, which you can derive from its full VIN.
So to find similar cars matching on all the taxonomy specifications of the car, you can use vins or taxonomy_vins parameters of the API, Like —
https://marketcheck-prod.apigee.net/v2/search/car/active?api_key=<your_api_key>&car_type=used&vins=1FTEW1EG9HKC35917
Or using taxonomy_vins parameter like —
https://marketcheck-prod.apigee.net/v2/search/car/active?api_key=<your_api_key>&car_type=used&taxonomy_vins=1FTEW1EGHK
As many of you might be wondering the VIN is same in both urls (taxonomy_vin is just a squished version of given vin), but the responses are different! This creates confusion, and lets remove that confusion by explaining whats happening behind the scenes here.
Lets look at the VIN again — 1FTEW1EG9HKC35917. Here when we remove last 6 digits and 9th one we get this taxonomy vin — 1FTEW1EGHK. Every digit in this taxonomy_vin is representing a car specification. In particular the last digit of taxonomy_vin (and 11th digit of VIN) — K in our vin, is indicating the plant code at which this particular car was manufactured. This information while matching car on its specifications is kinda useless, and we don’t want to consider this digit while searching for similar cars because cars manufactured by single make will have same specifications regardless of actual plant or factory where the car was manufactured.
So when you search with vins parameter this particular 11th digit, the plant code is ignored and hence more number of similar cars match to our given vin, and hence higher num_found. Internally the API transforms given VIN from this 1FTEW1EG9HKC35917 to this taxonomy_vin 1FTEW1EGH? (Replacing last digit K in taxonomy_vin with “?”).
But if you want to consider this last digit of taxonomy_vin also, while searching for similar cars, then you can use taxonomy_vins parameter in API call, as this will match cars that have same exact taxonomy_vin, including the plant code.
(Note : — Notice here in both parameters there is s at the end. Like vins and not vin, taxonomy_vins and not taxonomy_vin).
Find Similar cars — vins & match parameters
Most of the times users want this to find similar cars. In previous examples when you use only vins parameter, even though it omits plant code from taxonomy specifications it still considers all other specifications for matching the car. Most of the times you just want to match the car on year, make, model and/or trim of the given car. And here comes the duo of vins and match (FYI — match only works with vins and not with vin). The value of match can be either year,make,model or year,make,model,trim. Telling the API exactly on which all specifications to match the similar cars. Below is sample API call —
https://marketcheck-prod.apigee.net/v2/search/car/active?api_key=<your_api_key>&car_type=used&vins=1FTEW1EG9HKC35917&match=year,make,modelIts response —
Or with match on year,make,model,trim like —
https://marketcheck-prod.apigee.net/v2/search/car/active?api_key=<your_api_key>&car_type=used&vins=1FTEW1EG9HKC35917&match=year,make,model,trimIts response —
As you can see when you add trim to list of matching specifications the num_found comes down.
As I said earlier this is what most users want when they say “I want to find similar cars for a given vin”. Just use vins with match and you’ll be good to go.
FYI — You can give multiple vins to find the similar cars of different year, make, model. Just add more vins to the value of vins parameter, separated by comma like —
https://marketcheck-prod.apigee.net/v2/search/car/active?api_key=<your_api_key>&car_type=used&vins=1FTEW1EG9HKC35917,3FADP4BJ6HM166161&match=year,make,modelYou can pass in any number of vins here, separated by comma.
Similar cars — Nearby
As you can see we are not done yet! All the above calls gave us the similar cars on national level, which is may or may not be what you want, depending on your requirements. So if you want to find similar cars locally or near by to the given location, you can use geo-spatial query feature of the API.
To get more geo-specific results use latitude, longitude and radius parameters of the API, like —
https://marketcheck-prod.apigee.net/v2/search/car/active?api_key=<your_api_key>&car_type=used&vins=1FTEW1EG9HKC35917,3FADP4BJ6HM166161&match=year,make,model&latitude=34.02&longitude=-118.28&radius=50Just append these params at the end.
Or instead of using latitude and longitude, you can directly provide zip and radius for searching similar cars around zip 90007 like —
https://marketcheck-prod.apigee.net/v2/search/car/active?api_key=<your_api_key>&car_type=used&vins=1FTEW1EG9HKC35917,3FADP4BJ6HM166161&match=year,make,model&zip=90007&radius=50The one more added benefit of searching similar local cars using geo spatial queries is you get the distance of given listing from your current location in dist key at the bottom of each listing.
Of-course you can sort these results any way you want using APIs sort_by and sort_order parameters. Many such parameters and detailed documentation of API can be found at our official docs page — https://apidocs.marketcheck.com/
Conclusion
Marketcheck’s search API is a feature rich solution which has many facets that can be used to fulfil your requirements. Hope this article has been useful to you. If you have any questions or want our input on any API related query you might have, please feel free to contact us at api@marketcheck.com we’d be happy to assist you.
