Marketcheck API provides access to New, Used and Certified car inventory for all car dealers in USA and Canada.
\nThe API provides a RESTful interface with JSON-formatted responses to access most Marketcheck resources. We are continuously working on expanding our API functionality, so stay tuned!
\nData Source
\nThe data is sourced from over 53,000 Car dealer websites in USA and over 3600 dealer websites in Canada.
\nThere are about 6.2M searchable listings (about 2.2M unique VINs) for Used & Certified cars and about 6.6M (about 3.9M unique VINs) New car listings from all over USA.
\nFor Canada, there are about 200k Used cars listings and 290k New car listings available via the API.
\nThe active inventory set available on target websites is refreshed once every 24 hours. All websites are tracked for changes to the inventory and only those listings that have changes published are crawled afresh.
\nAutobot
\nThe data is mined from dealer websites, something that a dealer would not mind. Our bot is known by the name \"Autobot\" and is a polite web scraper respecting the robots.txt rules set across all dealer websites.
\nPlease note, mining from all target websites is actively monitored and data mining issues are actively fixed. There are always 2-3% websites that will be under maintenance for various reasons and inventory coverage from such sites wont be complete. Our operations and support teams actively monitor such sites and fixes them within 48 hours of the discovery.
\nThe Developer API uses a token based authentication. You have to include the token in the querystring of every request. The token parameter is named as api_key Each Marketcheck API user can generate API keys and can have multiple valid tokens at the same time.
To generate an API token, please Sign up at our developer portal at http://developer.marketcheck.com
\nOnce signed up you can register you app/s and subscribe to the usage packs based on your usage requirements. If you are just starting out, the free Evaluation pack is best suited for you. Evaluation packages do not need prior approvals, but all other packages require approvals and you need to send an email to api@marketcheck.com once you request higher packages via your developer portal account.
\nYou'll need to generate an API key to make an API Request.
\nYou could import the API in the Postman app and execute the sample API calls described below via Postman to get a good feel of the API.
\nPlease follow the following steps to set up Postman for the API
\napi_keyIn case you have any queries on the above process please write to us at support@marketcheck.zendesk.com
\nHeaders
\nAll Marketcheck API calls must include the following headers:
\nOnce you sign up for a package that requires approval please send an email to api@marketcheck.com to get an approval for your API key.
\nIf you need a package with higher limits, please reach out to us at api@marketcheck.com
\nWe have generated API Client SDKs for various languages. These are hosted here - https://github.com/MarketcheckCarsInc
\nIn case you are using languages outside of those listed here you could send us a request to get the Client SDK generated for you.
\nFor API questions and support, please send an email to Marketcheck Support (support@marketcheck.zendesk.com)
\n","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","toc":[{"content":"Authentication","slug":"authentication"},{"content":"Testing via Postman","slug":"testing-via-postman"},{"content":"Requests","slug":"requests"},{"content":"Packages and Rate limits","slug":"packages-and-rate-limits"},{"content":"API Client SDKs","slug":"api-client-sdks"},{"content":"Getting Support","slug":"getting-support"}],"owner":"3967924","collectionId":"e28ed1ea-9701-4e72-be97-8c06d6e31170","publishedId":"RW1hhvSR","public":true,"customColor":null,"publishDate":"2018-05-09T08:59:25.000Z"},"item":[{"name":"Inventory Search API","item":[{"name":"Search","item":[{"name":"By Various Criteria","item":[{"name":"Search by Year, Make","event":[{"listen":"test","script":{"type":"text/javascript","exec":["var jsonData = JSON.parse(responseBody);","var len = jsonData.listings.length;","var listings = jsonData.listings;","","// const test_schema = {","// \"type\": \"object\",","// \"properties\": {","// \"listings\": {","// \"type\": \"array\",","// \"items\": {","// \"type\": \"object\",","// \"properties\": {","// \"build\": {","// \"type\": \"object\",","// \"properties\": {","// \"year\": {\"type\": \"string\"},","// \"make\": {\"type\": \"string\"},","// },","// \"required\": [\"year\", \"make\"]","// }"," ","// }","// }","// }","// },","// \"required\": [\"listings\"]","// };","","// tests[\"Valid schema\"] = tv4.validate(jsonData, test_schema);","","","for(var i = 0; i < len; i++) {"," tests[\"Verify year is: 2014\"] = listings[i].build.year === \"2014\";"," tests[\"Verify make is: Ford\"] = listings[i].build.make === \"Ford\";","}"]}}],"id":"f628dfa6-cb13-4433-83a4-169ff54d244f","request":{"method":"GET","header":[{"key":"Host","value":"marketcheck-prod.apigee.net"}],"body":{"mode":"raw","raw":""},"url":"http://api.marketcheck.com/v1/search?api_key={your_api_key}&year=2014&make=ford&latitude=34.05&longitude=-118.24&radius=100&car_type=used&start=0&rows=50&seller_type=dealer","description":"car_type filterMultiple, comma separated, year values could provided to the year parameter and the API would return for sale listings matching all provided years
Search cars for sale for a given Year, Make, Model combination. To filter on multiple year, make, model combinations check out the ymmt parameter for the Search API
Search cars for sale matching the year, make, model, trim values. The trim parameter value must be a valid Trim value as per the VIN decoder Marketcheck uses. To pull valid trim values for a given VIN, you can use the VIN Decoder API and then pass on the trim to the search API.
In most cases you are already using a VIN Decoder and chances are the trim values you have in your decoder wont match a 100% with our decoder. In such cases its advisable to use the VIN Decoder API or the facets parameter to the Search API described below.
When vin / vins / taxonomy_vins parameter is used to fetch similar cars for sale, the API internally does a VIN Lookup to fetch all car specs attributes for the given vin / vins / taxonomy_vins value/s
car_type attribute is used to filter on conditioncar_type parameter are new, used and certifiedbody_type attribute is used to filter on body typebody_type parameter are suv, sedan, pickup, hatchback, coupe, wagonfacets parameter described belowbody_subtype attribute is used to filter on vehicle typebody_subtype parameter are Crew Cab, Regular Cab, Extended Cab, Super Cab etcfacets parameter described belowseller_type attribute is used to filter on Seller Typeseller_type parameter are dealer, fsbocity,state,zip parameters can be used to search cars for sale near themcountry parameterUS, CA, ALLcountry parameter is not specifiedcarfax_1_owner and carfax_clean_title can be passed as parameters to search query with values either true or falseseller_type attribute to filter private party / FSBO / SIY car listingsymmt parameter is used to specify all possible combinationsyear|make|| or year|make|model or |make|model| combinations. vins or taxonomy_vins parameter to the search api instead the year|make|model|trim combinations.transmissiondrivetrainfuel_typespeedsdoorsengineengine_sizeengine_aspirationengine_blockengine_mesaurefacets parameter described belowexterior_colorinterior_colorAn example that fetches all Used cars for sale near Denver, Colorado within 200 miles
\n","urlObject":{"protocol":"http","path":["search"],"host":["api.marketcheck.com/v1"],"query":[{"key":"api_key","value":"{your_api_key}"},{"key":"latitude","value":"39.73"},{"key":"longitude","value":"-104.99"},{"key":"radius","value":"200"},{"key":"car_type","value":"used"},{"key":"start","value":"0"},{"key":"rows","value":"10"},{"key":"sort_by","value":"dist"},{"key":"sort_order","value":"desc"}],"variable":[]}},"response":[],"_postman_id":"440043b7-9a6a-41a0-8690-899667930a4d"}],"id":"41539f8b-06eb-4592-a394-28aeac32be8d","description":"One of the most widely used features of the API is searching for cars that are for sale nearby. The API accepts the Geo Point and a radius within which for sale car listings need to searched.
\n","_postman_id":"41539f8b-06eb-4592-a394-28aeac32be8d"},{"name":"Plots API","item":[{"name":"Plots by VIN","event":[{"listen":"test","script":{"type":"text/javascript","exec":["var jsonData = JSON.parse(responseBody);","var len = jsonData.listings.length;","var listings = jsonData.listings","","for(var i = 0; i < len; i++) {"," tests[\"Verify distance covered under radius is: 20\"] = listings[i].dist <= 200;","}"]}}],"id":"cf8c177f-f7d1-43a2-935e-3b958cbe77dd","request":{"method":"GET","header":[{"key":"Host","value":"marketcheck-prod.apigee.net"}],"body":{"mode":"raw","raw":""},"url":"http://api.marketcheck.com/v1/search?api_key={your_api_key}&latitude=39.73&longitude=-104.99&radius=200&car_type=used&start=0&rows=10&sort_by=dist&sort_order=desc&plot=true","urlObject":{"protocol":"http","path":["search"],"host":["api.marketcheck.com/v1"],"query":[{"key":"api_key","value":"{your_api_key}"},{"key":"latitude","value":"39.73"},{"key":"longitude","value":"-104.99"},{"key":"radius","value":"200"},{"key":"car_type","value":"used"},{"key":"start","value":"0"},{"key":"rows","value":"10"},{"key":"sort_by","value":"dist"},{"key":"sort_order","value":"desc"},{"key":"plot","value":"true"}],"variable":[]}},"response":[],"_postman_id":"cf8c177f-f7d1-43a2-935e-3b958cbe77dd"}],"id":"787fa0cc-a48b-4098-ae4a-1a99ab1bd3ce","description":"A special purpose Search API that you could use to plot nearby cars on a graph and also show additional data points available in the response on the UI when the users hover over one of the plotted points. It allows user to search with more granular control over filtering, sorting and projections of required fields.
\n","_postman_id":"787fa0cc-a48b-4098-ae4a-1a99ab1bd3ce"},{"name":"Sorting","item":[{"name":"Search - Sort Default - by distance","event":[{"listen":"test","script":{"type":"text/javascript","exec":["var jsonData = JSON.parse(responseBody);","var len = jsonData.listings.length;","var listings = jsonData.listings;","var distAry = [];","","for(var i = 1; i <= len; i++) {"," var dist = listings[i-1].dist;"," distAry.push(dist);"," tests[\"Verify distance is sorted on : desc order\"] = dist <= distAry[i-1];","}"]}}],"id":"d5db261d-1b06-470a-bcc7-71906d66a3da","request":{"method":"GET","header":[{"key":"Host","value":"marketcheck-prod.apigee.net"}],"body":{"mode":"raw","raw":""},"url":"http://api.marketcheck.com/v1/search?api_key={your_api_key}&make=ford&car_type=used&start=1&rows=10&latitude=34.05&longitude=-118.24&radius=10","description":"Default sort order for search results is distance from a given point.
\nIf the location and a sort order is not specified then the sort order is random.
\nTo fetch nearest cars first use the following parameters \nsort_by=dist\nsort_order=asc (Or you could skip this parameter)
To fetch farthest cars first use the following parameters \nsort_by=dist\nsort_order=desc
The calculated distance from the given location is available in the response under response.listing[x].dist key.
\n","urlObject":{"protocol":"http","path":["search"],"host":["api.marketcheck.com/v1"],"query":[{"key":"api_key","value":"{your_api_key}"},{"key":"make","value":"ford"},{"key":"car_type","value":"used"},{"key":"start","value":"1"},{"key":"rows","value":"10"},{"key":"latitude","value":"34.05"},{"key":"longitude","value":"-118.24"},{"key":"radius","value":"10"}],"variable":[]}},"response":[],"_postman_id":"d5db261d-1b06-470a-bcc7-71906d66a3da"},{"name":"Search - Sort Default - distance descending","event":[{"listen":"test","script":{"type":"text/javascript","exec":["var jsonData = JSON.parse(responseBody);","var len = jsonData.listings.length;","var listings = jsonData.listings;","var distAry = [];","","for(var i = 1; i <= len; i++) {"," var dist = listings[i-1].dist;"," distAry.push(dist);"," tests[\"Verify distance is sorted on : desc order\"] = dist <= distAry[i-1];","}"]}}],"id":"4e2f5e95-0471-46a2-94fa-7fd0d2268294","request":{"method":"GET","header":[{"key":"Host","value":"marketcheck-prod.apigee.net"}],"body":{"mode":"raw","raw":""},"url":"http://api.marketcheck.com/v1/search?api_key={your_api_key}&make=ford&car_type=used&start=1&rows=10&latitude=34.05&longitude=-118.24&radius=10&sort_order=desc","description":"Default sort order for search results is distance from a given point. If the location and a sort order is not specified then the sort order is random.
\n","urlObject":{"protocol":"http","path":["search"],"host":["api.marketcheck.com/v1"],"query":[{"key":"api_key","value":"{your_api_key}"},{"key":"make","value":"ford"},{"key":"car_type","value":"used"},{"key":"start","value":"1"},{"key":"rows","value":"10"},{"key":"latitude","value":"34.05"},{"key":"longitude","value":"-118.24"},{"key":"radius","value":"10"},{"key":"sort_order","value":"desc"}],"variable":[]}},"response":[],"_postman_id":"4e2f5e95-0471-46a2-94fa-7fd0d2268294"},{"name":"Sort on Price","event":[{"listen":"test","script":{"type":"text/javascript","exec":["var jsonData = JSON.parse(responseBody);","var len = jsonData.listings.length;","var listings = jsonData.listings;","var distAry = [];","","for(var i = 1; i <= len; i++) {"," var dist = listings[i-1].dist;"," distAry.push(dist);"," tests[\"Verify distance is sorted on : desc order\"] = dist <= distAry[i-1];","}"]}}],"id":"9ee0f2c5-9b02-47b9-9f59-a352bc6cd71b","request":{"method":"GET","header":[{"key":"Host","value":"marketcheck-prod.apigee.net"}],"body":{"mode":"raw","raw":""},"url":"http://api.marketcheck.com/v1/search?api_key={your_api_key}&make=ford&car_type=used&start=1&rows=10&latitude=34.05&longitude=-118.24&radius=10&sort_by=price&sort_order=asc","description":"To sort results on price in the ascending order, use the following two parameters
sort_by=price\nsort_order=asc
To sort in the descending order please specify the sort_order as desc
\nsort_by=price\nsort_order=desc
To sort results on miles in the ascending order, use the following two parameters
sort_by=miles\nsort_order=asc
To sort in the descending order please specify the sort_order as desc
\nsort_by=miles\nsort_order=desc
To sort results on dom (Days on Market) in the ascending order, use the following two parameters
sort_by=dom\nsort_order=asc
To sort in the descending order please specify the sort_order as desc
\nsort_by=dom\nsort_order=desc
To sort results on listing age in the ascending order, use the following two parameters
\nsort_by=age\nsort_order=asc
To sort in the descending order please specify the sort_order as desc
\nsort_by=age\nsort_order=desc
To sort results on year in the ascending order, use the following two parameters
sort_by=year\nsort_order=asc
To sort in the descending order please specify the sort_order as desc
\nsort_by=year\nsort_order=desc
Example here sorts on year in the descending order.
\n","urlObject":{"protocol":"http","path":["search"],"host":["api.marketcheck.com/v1"],"query":[{"key":"api_key","value":"{your_api_key}"},{"key":"make","value":"ford"},{"key":"car_type","value":"used"},{"key":"start","value":"1"},{"key":"rows","value":"10"},{"key":"latitude","value":"34.05"},{"key":"longitude","value":"-118.24"},{"key":"radius","value":"10"},{"key":"sort_by","value":"year"},{"key":"sort_order","value":"desc"}],"variable":[]}},"response":[],"_postman_id":"9c1c789e-633b-4de5-aaa3-a6612fe5a4b4"},{"name":"Sort on Posted at / Listed since","event":[{"listen":"test","script":{"type":"text/javascript","exec":["var jsonData = JSON.parse(responseBody);","var len = jsonData.listings.length;","var listings = jsonData.listings;","var distAry = [];","","for(var i = 1; i <= len; i++) {"," var dist = listings[i-1].dist;"," distAry.push(dist);"," tests[\"Verify distance is sorted on : desc order\"] = dist <= distAry[i-1];","}"]}}],"id":"42551d28-19c9-4671-9c7d-b37418139ac8","request":{"method":"GET","header":[{"key":"Host","value":"marketcheck-prod.apigee.net"}],"body":{"mode":"raw","raw":""},"url":"http://api.marketcheck.com/v1/search?api_key={your_api_key}&make=ford&car_type=used&start=1&rows=10&latitude=34.05&longitude=-118.24&radius=10&sort_by=posted_at&sort_order=desc","description":"To sort results on Posted at / Listed since in the ascending order, use the following two parameters
\nsort_by=posted_at\nsort_order=asc
To sort in the descending order please specify the sort_order as desc
\nsort_by=posted_at\nsort_order=desc
Example here sorts on posted at in the descending order.
\n","urlObject":{"protocol":"http","path":["search"],"host":["api.marketcheck.com/v1"],"query":[{"key":"api_key","value":"{your_api_key}"},{"key":"make","value":"ford"},{"key":"car_type","value":"used"},{"key":"start","value":"1"},{"key":"rows","value":"10"},{"key":"latitude","value":"34.05"},{"key":"longitude","value":"-118.24"},{"key":"radius","value":"10"},{"key":"sort_by","value":"posted_at"},{"key":"sort_order","value":"desc"}],"variable":[]}},"response":[],"_postman_id":"42551d28-19c9-4671-9c7d-b37418139ac8"}],"id":"9e3f03c9-e16c-4598-9161-07e730cc3d20","description":"The Search API allows for sorting results on the following fields -
\nAt the moment, sorting on multiple fields is not supported.
\nIf sort_order is not specified, the results will be sorted in the ascending order.
\nThe examples below will only demonstrate the ascending sort. To sort in the descending order please specify the sort_order as desc
\nsort_order=desc
To fetch listings from the start / first page -
\nstart=0\nrows=10
To fetch listings from the second page -
\nstart=10\nrows=10
Please note start for second page is 10 (as the first record offset starts from 0)
\n","urlObject":{"protocol":"http","path":["search"],"host":["api.marketcheck.com/v1"],"query":[{"key":"api_key","value":"{your_api_key}"},{"key":"year","value":"2014"},{"key":"make","value":"ford"},{"key":"latitude","value":"34.05"},{"key":"longitude","value":"-118.24"},{"key":"radius","value":"10"},{"key":"car_type","value":"used"},{"key":"start","value":"10"},{"key":"rows","value":"10"},{"key":"sort_by","value":"price"}],"variable":[]}},"response":[],"_postman_id":"907f0211-9a2a-4320-a638-11ae7c8868c4"},{"name":"First page / per page 25 listings","event":[{"listen":"test","script":{"type":"text/javascript","exec":["var jsonData = JSON.parse(responseBody);","var len = jsonData.listings.length;","var listings = jsonData.listings","tests[\"Verify number of listings are: 5\"] = listings.length === 5;"]}}],"id":"220ddad2-4a8c-4c15-93ad-83442229a39d","request":{"method":"GET","header":[{"key":"Host","value":"marketcheck-prod.apigee.net"}],"body":{"mode":"raw","raw":""},"url":"http://api.marketcheck.com/v1/search?api_key={your_api_key}&year=2014&make=ford&latitude=34.05&longitude=-118.24&radius=10&car_type=used&start=0&rows=25","description":"To fetch listings from the start / first page -
\nstart=0\nrows=25
To fetch listings from second page -
\nstart=25\nrows=25
start and rows parameters could be used to iterate through the results for a given search criteria
start parameter is the offset from which listings will be returned from the entire match set. start parameter starts with 0
rows parameter is the listings count you need to pull per page / per iteration. page parameter supports a max value of 50. Any value greater than 50 will be ignored and the API will then return only top 10 matching rows.
Perhaps a better way to paginate/iterate would have been page and per_page parameters. We may implement this in the future releases.
-If you would like to match similar cars only on Year, Make, Model attributes for a given VIN (and not on all Specs attributes) then you could use the match parameter to specify the matching option
vin=<your VIN\nmatch=year,make,model
vin=<your VIN>\nmatch=year,make,model,trim
To re-iterate, the match option is provided to filter cars\nby only the car specs attributes specified in the match paramter to account for differences in reference value sets between the VIN decoders at your and Marketchecks end.
match option as described above is also available when multiple VINs are passed in the vins parameterCars matching the specifications for the given list of taxonomy vins
\nA taxonomy vin is a 10 letter string that reprsents a build from the Marketcheck's car specification / VIN Decoder database. Its a short version of the 17 letter VIN and it includes the first 8 and the 10th and 11th letter from a 17 letter VIN.
\n","urlObject":{"protocol":"http","path":["search"],"host":["api.marketcheck.com/v1"],"query":[{"key":"api_key","value":"{your_api_key}"},{"key":"taxonomy_vins","value":"5J6RM4H5CL,1VWBH7A3CC"},{"key":"latitude","value":"34.05"},{"key":"longitude","value":"-118.24"},{"key":"radius","value":"100"},{"key":"car_type","value":"used"},{"key":"start","value":"0"},{"key":"rows","value":"10"}],"variable":[]}},"response":[],"_postman_id":"0af922f8-0e12-4882-9e87-25b30645a1d8"},{"name":"Similar Cars - by VIN(s) / Taxonomy VIN(s)","event":[{"listen":"test","script":{"type":"text/javascript","exec":["var jsonData = JSON.parse(responseBody);","var len = jsonData.listings.length;","var listings = jsonData.listings;","var vins = [\"5J6RM4H59CL070290\", \"19XFB2F5XFE054327\"];","var taxonomyVins = [\"5J6RM4H5CL\", \"1VWBH7A3CC\"];","","for(var i = 0; i < vins.length; i++) {"," var taxonomyVin = vins[i].substring(0,8) + vins[i].substring(9,11);"," taxonomyVins.push(taxonomyVin);","}","","for(var i = 0; i < len; i++) {"," var vinOfResult = listings[i].vin;"," var taxonomyVinsOfResult = vinOfResult.substring(0,8) + vinOfResult.substring(9,11);"," var flag = 0;"," for(var j = 0; j < taxonomyVins.length; j++) {"," if (taxonomyVinsOfResult == taxonomyVins[j]) {"," flag = 1;"," }"," }",""," tests[\"Verify all vins should have taxoomy vin: \" + taxonomyVins] = flag === 1","","}"]}}],"id":"fe20395d-cd9e-4254-9a1b-3410d5d17e5e","request":{"method":"GET","header":[{"key":"Host","value":"marketcheck-prod.apigee.net"}],"body":{"mode":"raw","raw":""},"url":"http://api.marketcheck.com/v1/search?api_key={your_api_key}&vins=5J6RM4H59CL070290,19XFB2F5XFE054327&taxonomy_vins=5J6RM4H5CL,1VWBH7A3CC&car_type=used&start=0&rows=10","description":"Cars matching the specifications for the given list of vins and taxonomy vins together.
\n","urlObject":{"protocol":"http","path":["search"],"host":["api.marketcheck.com/v1"],"query":[{"key":"api_key","value":"{your_api_key}"},{"key":"vins","value":"5J6RM4H59CL070290,19XFB2F5XFE054327"},{"key":"taxonomy_vins","value":"5J6RM4H5CL,1VWBH7A3CC"},{"key":"car_type","value":"used"},{"key":"start","value":"0"},{"key":"rows","value":"10"}],"variable":[]}},"response":[],"_postman_id":"fe20395d-cd9e-4254-9a1b-3410d5d17e5e"},{"name":"Similar Cars - by VIN(s) Near NY","event":[{"listen":"test","script":{"type":"text/javascript","exec":["var jsonData = JSON.parse(responseBody);","var len = jsonData.listings.length;","var listings = jsonData.listings;","var vins = \"4S4BRCFC4A3375256\";","var taxonomyVins = vins.substring(0,8) + vins.substring(9,11);","","for(var i = 0; i < len; i++) {"," var vinOfResult = listings[i].vin;"," var taxonomyVinsOfResult = vinOfResult.substring(0,8) + vinOfResult.substring(9,11);"," tests[\"Verify all vins should have taxoomy vin: 19XFB2F5FE\"] = taxonomyVinsOfResult == taxonomyVins"," tests[\"Verify distance covered under radius is: 1000\"] = listings[i].dist <= 1000;","}"]}}],"id":"93d086ba-0302-4c1b-b710-604227a879de","request":{"method":"GET","header":[{"key":"Host","value":"marketcheck-prod.apigee.net"}],"body":{"mode":"raw","raw":""},"url":"http://api.marketcheck.com/v1/search?api_key={your_api_key}&latitude=40.759212&longitude=-73.984634&radius=100&car_type=used&vins=19XFB2F5XFE212648&start=0&rows=1000&sort_by=dist&sort_order=desc","description":"Cars matching the specifications for the given list of VINs / Taxonomy VINs and around New York City
\n","urlObject":{"protocol":"http","path":["search"],"host":["api.marketcheck.com/v1"],"query":[{"key":"api_key","value":"{your_api_key}"},{"key":"latitude","value":"40.759212"},{"key":"longitude","value":"-73.984634"},{"key":"radius","value":"100"},{"key":"car_type","value":"used"},{"key":"vins","value":"19XFB2F5XFE212648"},{"key":"start","value":"0"},{"key":"rows","value":"1000"},{"key":"sort_by","value":"dist"},{"key":"sort_order","value":"desc"}],"variable":[]}},"response":[],"_postman_id":"93d086ba-0302-4c1b-b710-604227a879de"},{"name":"Exact match - by VIN","event":[{"listen":"test","script":{"type":"text/javascript","exec":["var jsonData = JSON.parse(responseBody);","var len = jsonData.listings.length;","var listings = jsonData.listings;","var vins = \"4S4BRCFC4A3375256\";","var taxonomyVins = vins.substring(0,8) + vins.substring(9,11);","","for(var i = 0; i < len; i++) {"," var vinOfResult = listings[i].vin;"," var taxonomyVinsOfResult = vinOfResult.substring(0,8) + vinOfResult.substring(9,11);"," tests[\"Verify all vins should have taxoomy vin: 19XFB2F5FE\"] = taxonomyVinsOfResult == taxonomyVins"," tests[\"Verify distance covered under radius is: 1000\"] = listings[i].dist <= 1000;","}"]}}],"id":"6a9abf38-02b6-490a-9d02-a58535110900","request":{"method":"GET","header":[{"key":"Host","value":"marketcheck-prod.apigee.net"}],"body":{"mode":"raw","raw":""},"url":"http://api.marketcheck.com/v1/search?api_key={your_api_key}&vin=19XFB2F5XFE212648","description":"vin parameter. source / dealer_id parameters in addition to the vin parameter and the API will return the listing published by the dealer for the VINsource / dealer_id parameters in addition to the vin parameter and the API will return the listing published by the dealer for the VINsource / dealer_id allows you to select a specific listing published online by a specific dealervin=Z* will match all cars with a VIN that starts with the letter ZSimilar cars could be fetched by using a VIN or a Squish VIN.
\nThe API uses all Car specs attributes for the VIN/Squish VIN and uses those to find matching cars around a given location.
\n** The match parameter **\nFor a given VIN, you could also match cars based on Year, Make, Model (and optionally) Trim for the VIN. To filter on these attributes you could use the match parameter and pass it the fields list you prefer to match on.
To filter out cars by Year, Make, Model, Trim is supported via the year, make, model and trim parameters of the Search API. But as the VIN Decoder you are using at your end and the one that Marketcheck uses internally may have potential mismatches (esp on the Trim field) then the expected search results would not come back if you pass these field values by referring to the VIN Decoder you use at your end. To make the Search API refer to Marketcheck's VIN Decoder and then perform an internal look up the match parameter could be used in tandom with vin / vins parameter
** Future changes **
\nseller_type attribute to filter private party / FSBO / SIY car listingsParameter to use price_range
Parameter to use miles_range
Parameter to use dom_range
In the example, the API would fetch all cars on the market for 30 to 60 days.
\nYou can apply this range filter on all 3 dom values we calculate dom_range for dom lifetime,dom_180_range for dom in last 180 days(6 months), dom_active_range for dom active(dom since listing is online this time)
The Search API supports range filtering on following fields
\npricemilesdom [Days on Market]The parameters to use in the API call for each of these respectively are
\nprice_rangemiles_rangedom_rangeThe value of the parameters must be an integer range of the form min-max e.g. 1000-10000 or 30-60
The Search API supports comprehensive Search/Filter criteria across many fields as listed below -
\nAn example to fetch facets for a search criteria by Year, Make, Model, Trim fields
\n","urlObject":{"protocol":"http","path":["search"],"host":["api.marketcheck.com/v1"],"query":[{"key":"api_key","value":"{your_api_key}"},{"key":"latitude","value":"34.05"},{"key":"longitude","value":"-118.24"},{"key":"radius","value":"10"},{"key":"car_type","value":"used"},{"key":"start","value":"0"},{"key":"rows","value":"0"},{"key":"facets","value":"year,make,model,trim"}],"variable":[]}},"response":[],"_postman_id":"9261e5f7-89ad-4290-8a40-ff51f687d603"},{"name":"Facets with limit, offset","event":[{"listen":"test","script":{"type":"text/javascript","exec":["var jsonData = JSON.parse(responseBody);","var len = jsonData.listings.length;","var listings = jsonData.listings","var years = jsonData.facets.year;","var make = jsonData.facets.make;","","tests[\"Verify facets has: year\"] = responseBody.has(\"year\")","tests[\"Verify facets has: make\"] = responseBody.has(\"make\")","tests[\"Verify facets has year offset: 60\"] = years.length <= 60","tests[\"Verify facets has make offset: 60\"] = years.length <= 60"]}}],"id":"8ace9a32-8d68-4f80-9e80-65fe35eb2cde","request":{"method":"GET","header":[{"key":"Host","value":"marketcheck-prod.apigee.net"}],"body":{"mode":"raw","raw":""},"url":"http://api.marketcheck.com/v1/search?api_key={your_api_key}&latitude=34.05&longitude=-118.24&radius=100&car_type=used&start=0&rows=0&facets=make|0|60,year|0|30","description":"To fetch more than top 20 terms you could pass in a offset (start) and a limit (count of terms to return)
\nThe factes parameter format changes to the following when offset and limit is to be used \n facets=field1|offset|limit,field2|offset|limit
e.g. To fetch top 60 makes and to 30 year values you could use the following parameter value\n facets=make|0|60,year|0|30
city filter parameterseller_name by passing in a limit of 10The Search API supports facets / counts by unqiue terms for the following fields
\nThings to note
\nmean is the averags days on market a Ford cars remains on the market in USlatitude, longitude and radius to define your region for the searchstats=dom option to get stats on Days on Market for the search criteriaThe Search API could calculate various statistics for the following fields
\nStats Response
\nFor more info on the response fields please refer to - https://lucene.apache.org/solr/guide/6_6/the-stats-component.html
\nPlease note all values are returned realtime based on the data that is contonuously updating at the back in the database.
\nJust like Facets, Stats could be included in the regular Search API calls too.
\n","_postman_id":"4dbb7e3b-71a8-4663-9a86-a1263b0156ff"}],"id":"ce5e872b-7cde-448f-a0b1-4bb23ac7f4e7","description":"Marketcheck's API has a comprehensive Search API that allows cars to be filtered on many car attributes. The Search API provides the following major features
\nGet all details from the Marketcheck database for a particular for sale listing.
\n","urlObject":{"protocol":"http","path":["listing","ab2281d2-05fc-4d61-aa32-3fab037501c3"],"host":["api.marketcheck.com/v1"],"query":[{"key":"api_key","value":"{your_api_key}"}],"variable":[]}},"response":[],"_postman_id":"1c2dea8c-0c78-4e84-a287-c76c32d8a10e"},{"name":"Get Listing Extra Attributes","event":[{"listen":"test","script":{"type":"text/javascript","exec":["var jsonData = JSON.parse(responseBody);","var listingId = \"03b65568-be2e-442e-9125-47beda77ce7e\";","tests[\"Verify listing id is: \" + listingId] = jsonData.id === listingId","tests[\"Verify: features\"] = responseBody.has(\"features\")","tests[\"Verify: options\"] = responseBody.has(\"options\")",""]}}],"id":"7df18ae1-b37c-46d1-aa7e-1447c34d5d22","request":{"method":"GET","header":[{"key":"Host","value":"marketcheck-prod.apigee.net"}],"body":{"mode":"raw","raw":""},"url":"http://api.marketcheck.com/v1/listing/03b65568-be2e-442e-9125-47beda77ce7e/extra?api_key={your_api_key}","description":"Marketcheck keeps history of all online listings and gives you the ability to query the historical listings for a VIN.
\nThe data goes back to Jan 2013, with over 1.2 billion listings stored in the database.
\n","urlObject":{"protocol":"http","path":["listing","03b65568-be2e-442e-9125-47beda77ce7e","extra"],"host":["api.marketcheck.com/v1"],"query":[{"key":"api_key","value":"{your_api_key}"}],"variable":[]}},"response":[],"_postman_id":"7df18ae1-b37c-46d1-aa7e-1447c34d5d22"},{"name":"Get Listing Media Attributes","event":[{"listen":"test","script":{"type":"text/javascript","exec":["var listingId = \"03b65568-be2e-442e-9125-47beda77ce7e\";","tests[\"Verify listing id is: \" + listingId] = jsonData.id === listingId","tests[\"Verify: photo_links\"] = responseBody.has(\"photo_links\")"]}}],"id":"584447b3-5f58-4a0e-a5dd-b0e9c6fd4b35","request":{"method":"GET","header":[{"key":"Host","value":"marketcheck-prod.apigee.net"}],"body":{"mode":"raw","raw":""},"url":"http://api.marketcheck.com/v1/listing/03b65568-be2e-442e-9125-47beda77ce7e/media?api_key={your_api_key}","urlObject":{"protocol":"http","path":["listing","03b65568-be2e-442e-9125-47beda77ce7e","media"],"host":["api.marketcheck.com/v1"],"query":[{"key":"api_key","value":"{your_api_key}"}],"variable":[]}},"response":[],"_postman_id":"584447b3-5f58-4a0e-a5dd-b0e9c6fd4b35"}],"id":"75e633af-5dc4-4aac-acc8-3e2aefb584ad","description":"Once a Search is performed the next logical step would be to obtain more details about the listing like the car photos, installed options list, features, seller comments etc. These could be obtained using the Listing API by passing in a unique Marketcheck Listing ID to the API that you obtain from the Search API responses.
\nThis API could be used to build Vehicle Details Pages (VDPs) on your website / mobile app.
\nThere are 3 variants of the VDP API -
\n/listing/listing_id/listing/listing_id/extra/listing/listing_id/mediaYou can pass in list of fields to select for history for any VIN
\n","urlObject":{"protocol":"http","path":["history","5TDZK3DC6DS350288"],"host":["api.marketcheck.com/v1"],"query":[{"key":"api_key","value":"{your_api_key}"},{"key":"fields","value":"seller_type,dealer_id,seller_name,seller_phone,seller_email,vdp_url,source,last_seen_at,price,miles,city,state,zip,scraped_at"}],"variable":[]}},"response":[],"_postman_id":"1a44cad9-6ce0-4dae-955e-6f54212f9bcc"}],"id":"60b95600-0e22-4c12-bea5-1c658a485238","description":"Pull online listing history for a VIN from Marketcheck's historical database that hosts data extracted from over 900M VDP pages since Jan 2013 till date and growing at a rate of about 30-40M unique listings a month from all over the web.
\n","_postman_id":"60b95600-0e22-4c12-bea5-1c658a485238"},{"name":"Market API","item":[{"name":"Market Days Supply (MDS)","item":[{"name":"MDS with exact and debug","event":[{"listen":"test","script":{"type":"text/javascript","exec":["var jsonData = JSON.parse(responseBody);","tests[\"year is present\"] = responseBody.has(\"year\");","tests[\"make is present\"] = responseBody.has(\"make\");","tests[\"model is present\"] = responseBody.has(\"model\");","tests[\"trim is present\"] = responseBody.has(\"trim\");","tests[\"verify mds is not null\"] = responseBody.mds !== null;","tests[\"verify mds is not zero\"] = responseBody.mds !== 0;","tests[\"verify total_active_cars_for_ymmt is not null\"] = responseBody.total_active_cars_for_ymmt !== null;","tests[\"verify total_active_cars_for_ymmt is not zero\"] = responseBody.total_active_cars_for_ymmt !== 0;","tests[\"verify total_cars_sold_in_last_45_days is not null\"] = responseBody.total_cars_sold_in_last_45_days !== null;","tests[\"verify total_cars_sold_in_last_45_days is not zero\"] = responseBody.total_cars_sold_in_last_45_days !== 0;","","var per_day_sold_rate = (jsonData.total_cars_sold_in_last_45_days / 45);","var mds = Math.round(jsonData.total_active_cars_for_ymmt / per_day_sold_rate)","tests[\"verify mds\"] = jsonData.mds === mds",""]}}],"id":"907b23c5-e624-472e-8381-50a4b8f8e895","request":{"method":"GET","header":[{"key":"host","value":"marketcheck-prod.apigee.net"},{"key":"","value":""}],"body":{"mode":"raw","raw":""},"url":"http://api.marketcheck.com/v1/mds?api_key={your_api_key}&vin=2T2BK1BA1DC181616&latitude=37.998&longitude=-84.522&radius=1000&exact=true&debug=1","description":"To filter active cars based on Year, Make, Model and Trim and also consider the same cars sold count from last 45 days you'd need to pass in the parameter exact=true
Without the exact parameter mentioned in the API, it will match similar cars only on Year, Make, Model values for a given VIN.
The debug parameter is used to print the component values that go in the MDS calculation formula. It prints the Active cars count and the past 45 days sold count values the API uses to arrive at the final MDS value.
Without the exact=true parameter the API will match similar cars, active and last 45 days sold, based only on Year, Make and Model values for a given VIN.
Using paramter include_sold=true this returns all vins sold in last 45 days. The maximum limit on sold vins is 10K.
The API calculates and returns Market Days Supply of similar cars identified by the input VIN. Also returns all vins that were sold in last 45 days.
\nThe formula implemented to calculate Market Days Supply is as follows,
\nMDS = (Active inventory count) / (Past 45 days sale count)
\nThe similar cars for a given could be matched by two criteria -
\nGet Monthwise averages for cars that match the exact specifications of the input VIN.
\nThe response includes monthwise averages for price, miles, days on market values and the average number of units that were listed for sale in the month.
\nYou could use this data to plot trendlines across these fields.
\n","urlObject":{"protocol":"http","path":["trends"],"host":["api.marketcheck.com/v1"],"query":[{"key":"api_key","value":"{your_api_key}"},{"key":"vin","value":"1FMCU9GXXEUA10071"},{"key":"car_type","value":"used"}],"variable":[]}},"response":[],"_postman_id":"0c433625-d7d3-4ef4-ab1b-31714e479a40"}],"id":"addc164f-d8f0-4b96-a3eb-a39672a9f3bd","description":"Explore the live market with various analytical APIs we have put up so far.
\nFind dealers in USA & Canada around a given geo point.
\n","_postman_id":"1e413c35-78d8-4c40-b442-98e0159d9816"},{"name":"VIN Decoder API","item":[{"name":"VIN Decoder ","id":"ba81146f-b024-431e-a47d-3b86532af8b6","request":{"method":"GET","header":[{"key":"Host","value":"marketcheck-prod.apigee.net"}],"body":{"mode":"raw","raw":""},"url":"http://api.marketcheck.com/v1/vin/1FAHP3F28CL148530/specs?api_key={your_api_key}","urlObject":{"protocol":"http","path":["vin","1FAHP3F28CL148530","specs"],"host":["api.marketcheck.com/v1"],"query":[{"key":"api_key","value":"{your_api_key}"}],"variable":[]}},"response":[],"_postman_id":"ba81146f-b024-431e-a47d-3b86532af8b6"}],"id":"dd485ee0-4fe9-408b-9226-f6ccd7bd4fdb","description":"Decode any VIN and get the specifications for it. The VIN decoder data is sources from VinAudit.com and is refreshed daily and new cars make it in to the decoder as they come in market.
\n","_postman_id":"dd485ee0-4fe9-408b-9226-f6ccd7bd4fdb"}]}