openapi: 3.0.0 info: title: MarketCheck Cars API description: >- Access the New, Used and Certified cars inventories for all Car Dealers in US. The data is sourced from online listings by over 44,000 Car dealers in US. At any time, there are about 6.2M searchable listings (about 1.9M unique VINs) for Used & Certified cars and about 6.6M (about 3.9M unique VINs) New Car listings from all over US. MarketCheck aggregates billions of data points from over 44,000 US and 3,500 Canadian dealerships, offering daily-updated inventory search, price prediction, market days supply, OEM incentives, auction listings, and third-party integrations for recalls, title checks, and plate-to-VIN lookups. version: 1.0.3 contact: name: MarketCheck url: https://www.marketcheck.com/ termsOfService: https://www.marketcheck.com/terms/ externalDocs: description: MarketCheck API Documentation url: https://docs.marketcheck.com/docs/api/cars servers: - url: https://mc-api.marketcheck.com/v1 description: MarketCheck Production API tags: - name: Listings description: Search and retrieve active car listings - name: Inventory description: Dealer inventory operations - name: Dealer description: Dealer search and information - name: History description: Vehicle listing history - name: VIN Decoder description: VIN decoding and vehicle specifications - name: Market description: Market analytics, trends, and pricing insights - name: Facets description: Search facets for filtering - name: Graphs description: Plot data for visualizations paths: /search: get: tags: - Listings summary: Gets active car listings for the given search criteria operationId: search description: >- This endpoint is the meat of the API and serves many purposes. This API produces a list of currently active cars from the market for the given search criteria. The API results are limited to allow pagination upto 1000 rows. The search API facilitates the following use cases - 1. Search Cars around a given geo-point within a given radius 2. Search cars for a specific year / make / model or combination of these 3. Search cars matching multiple year, make, model combinations in the same search request 4. Filter results by most car specification attributes 5. Search for similar cars by VIN or Taxonomy VIN 6. Filter cars within a given price / miles / days on market (dom) range 7. Specify a sort order for the results on price / miles / dom / listed date 8. Search cars for a given City / State combination 9. Get Facets to build the search drill downs 10. Get Market averages for price/miles/dom/msrp for your search parameters: - name: api_key in: query description: The API Authentication Key. Mandatory with all API calls. schema: type: string - name: latitude in: query description: Latitude component of location schema: type: number format: float - name: longitude in: query description: Longitude component of location schema: type: number format: float - name: radius in: query description: Radius around the search location schema: type: integer - name: car_type in: query description: "Car type. Allowed values are: new / used / certified" schema: type: string enum: [new, used, certified] - name: seller_type in: query description: Seller type to filter cars on. You can pass in multiple seller type values comma separated. schema: type: string - name: year in: query description: Car year - 1980 onwards. You can pass in multiple year values comma separated. schema: type: string - name: make in: query description: "Car Make - should be a standard OEM Make name. You can pass in multiple make values separated by comma. e.g. ford,audi" schema: type: string - name: model in: query description: "Car model to search. You can pass in multiple model values comma separated for e.g f-150,Mustang." schema: type: string - name: trim in: query description: Car trim to search. You can pass in multiple trim values comma separated. schema: type: string - name: dealer_id in: query description: Dealer id to filter the cars. schema: type: string - name: vin in: query description: Car vin to search schema: type: string - name: source in: query description: Source to search cars. You can pass in multiple source values comma separated. schema: type: string - name: body_type in: query description: Body type to filter the cars on. You can pass in multiple body types comma separated. schema: type: string - name: body_subtype in: query description: Body subtype to filter the cars on. You can pass in multiple body subtype values comma separated. schema: type: string - name: vehicle_type in: query description: Vehicle type to filter the cars on. You can pass in multiple vehicle type values comma separated. schema: type: string - name: vins in: query description: Comma separated list of 17 digit vins to search the matching cars for. Only 10 VINs allowed per request. schema: type: string - name: taxonomy_vins in: query description: Comma separated list of 10 letter taxonomy VINs (first 8 + 10th + 11th chars of 17-digit VIN). schema: type: string - name: ymmt in: query description: "Comma separated list of Year|Make|Model|Trim combinations. e.g. 2010|Audi|A5,2014|Nissan|Sentra|S 6MT" schema: type: string - name: match in: query description: Comma separated list of fields for exact matching (year,make,model,trim). schema: type: string - name: cylinders in: query description: Cylinders to filter the cars on. You can pass in multiple cylinder values comma separated. schema: type: string - name: transmission in: query description: "Transmission to filter the cars on. [a = Automatic, m = Manual]." schema: type: string - name: speeds in: query description: Speeds to filter the cars on. You can pass in multiple speeds values comma separated. schema: type: string - name: doors in: query description: Doors to filter the cars on. You can pass in multiple doors values comma separated. schema: type: string - name: drivetrain in: query description: Drivetrain to filter the cars on. You can pass in multiple drivetrain values comma separated. schema: type: string - name: exterior_color in: query description: Exterior color to match. You can pass in multiple exterior color values comma separated. schema: type: string - name: interior_color in: query description: Interior color to match. You can pass in multiple interior color values comma separated. schema: type: string - name: engine in: query description: Filter listings on engine schema: type: string - name: engine_type in: query description: Engine Type to match. You can pass in multiple engine type values comma separated. schema: type: string - name: engine_aspiration in: query description: Engine Aspiration to match. You can pass in multiple Engine aspiration values comma separated. schema: type: string - name: engine_block in: query description: Engine Block to match. You can pass in multiple Engine Block values comma separated. schema: type: string - name: miles_range in: query description: "Miles range to filter cars with miles in the given range. Range to be given in the format: min-max e.g. 1000-5000" schema: type: string - name: price_range in: query description: "Price range to filter cars with the price in the range given. Range to be given in the format: min-max e.g. 1000-5000" schema: type: string - name: dom_range in: query description: "Days on Market range to filter cars with the DOM within the given range. Range to be given in the format: min-max e.g. 10-50" schema: type: string - name: sort_by in: query description: "Sort by field - allowed fields are distance|price|miles|dom|age|posted_at|year. Default sort field is distance from the given point." schema: type: string enum: [distance, price, miles, dom, age, posted_at, year] - name: sort_order in: query description: Sort order - asc or desc. Default sort order is distance from a point. schema: type: string enum: [asc, desc] - name: rows in: query description: Number of results to return. Default is 10. Max is 50. schema: type: integer default: 10 maximum: 50 - name: start in: query description: Page number to fetch the results for the given criteria. Default is 1. Pagination is allowed only till first 1000 results. schema: type: integer default: 1 - name: facets in: query description: "The comma separated list of fields for which facets are requested. Supported fields are - year, make, model, trim, vehicle_type, car_type, body_type, body_subtype, drivetrain, cylinders, transmission, exterior_color, interior_color, doors, engine_type, engine_aspiration, engine_block." schema: type: string - name: stats in: query description: "The list of fields for which stats need to be generated. Allowed fields are - price, miles, msrp, dom." schema: type: string - name: country in: query description: Filter on Country, by default US. Search available on US (United States) and CA (Canada). schema: type: string enum: [US, CA] default: US - name: plot in: query description: If plot has value true results in around 25k coordinates with limited fields to plot respective graph. schema: type: string - name: nodedup in: query description: If nodedup is set to true then will give results using is_searchable. schema: type: string - name: state in: query description: Filter listings on State. schema: type: string - name: city in: query description: Filter listings on city. schema: type: string - name: dealer_name in: query description: Filter listings on dealer_name. schema: type: string - name: trim_o in: query description: Filter listings on web scraped trim. schema: type: string - name: trim_r in: query description: Filter trim on custom possible matches. schema: type: string - name: dom_active_range in: query description: "Active Days on Market range to filter cars. Range to be given in the format: min-max e.g. 10-50" schema: type: string - name: dom_180_range in: query description: "Last 180 Days on Market range to filter cars. Range to be given in the format: min-max e.g. 10-50" schema: type: string - name: options in: query description: Tokenizer search on options. For multiple options use | as separator. schema: type: string - name: features in: query description: Tokenizer search on features. For multiple options use | as separator. schema: type: string responses: '200': description: Successful response with search results content: application/json: schema: $ref: '#/components/schemas/SearchResponse' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Unauthorized - Invalid API key content: application/json: schema: $ref: '#/components/schemas/Error' /listing/{id}: get: tags: - Listings summary: Listing by id operationId: getListing description: Get a particular listing by its id parameters: - name: id in: path required: true description: Listing id to get all the listing attributes schema: type: string - name: api_key in: query description: The API Authentication Key. Mandatory with all API calls. schema: type: string responses: '200': description: Successful response with listing details content: application/json: schema: $ref: '#/components/schemas/Listing' '404': description: Listing not found content: application/json: schema: $ref: '#/components/schemas/Error' /listing/{id}/extra: get: tags: - Listings summary: Long text Listings attributes for Listing with the given id operationId: getListingExtra description: Get listing options, features, seller comments parameters: - name: id in: path required: true description: Listing id to get all the long text listing attributes schema: type: string - name: api_key in: query description: The API Authentication Key. Mandatory with all API calls. schema: type: string responses: '200': description: Successful response with extra listing attributes content: application/json: schema: $ref: '#/components/schemas/ListingExtraAttributes' '404': description: Listing not found content: application/json: schema: $ref: '#/components/schemas/Error' /listing/{id}/media: get: tags: - Listings summary: Listing media by id operationId: getListingMedia description: Get listing media (photo, photos) by id parameters: - name: id in: path required: true description: Listing id to get all the listing attributes schema: type: string - name: api_key in: query description: The API Authentication Key. Mandatory with all API calls. schema: type: string responses: '200': description: Successful response with listing media content: application/json: schema: $ref: '#/components/schemas/ListingMedia' '404': description: Listing not found content: application/json: schema: $ref: '#/components/schemas/Error' /listing/{id}/vdp: get: tags: - Listings summary: Get listing HTML operationId: getListingVDP description: Cached HTML of the Vehicle Details Page (VDP) for the listing. The HTML is cached only for 7 days for all listings. parameters: - name: id in: path required: true description: Listing id to get the vehicle details page (VDP) HTML schema: type: string - name: api_key in: query description: The API Authentication Key. Mandatory with all API calls. schema: type: string - name: html in: query description: Get only HTML for given listings VDP page schema: type: string responses: '200': description: Successful response with VDP HTML content: application/json: schema: $ref: '#/components/schemas/ListingVDP' '404': description: Listing not found content: application/json: schema: $ref: '#/components/schemas/Error' /vin_report_summary: get: tags: - Listings summary: Get Summary Report operationId: getSummaryReport description: Generate Summary report for a given VIN parameters: - name: vin in: query required: true description: VIN as a reference to the type of car for which Summary data is to be returned schema: type: string - name: api_key in: query description: The API Authentication Key. Mandatory with all API calls. schema: type: string responses: '200': description: Successful response with summary report content: application/json: schema: type: array items: $ref: '#/components/schemas/VinReport' /dealer/{dealer_id}: get: tags: - Dealer summary: Dealer by id operationId: getDealer description: Get a particular dealer's information by its id parameters: - name: dealer_id in: path required: true description: Dealer id to get all the dealer info attributes schema: type: string - name: api_key in: query description: The API Authentication Key. Mandatory with all API calls. schema: type: string responses: '200': description: Successful response with dealer information content: application/json: schema: $ref: '#/components/schemas/Dealer' '404': description: Dealer not found content: application/json: schema: $ref: '#/components/schemas/Error' /dealer/{dealer_id}/active/inventory: get: tags: - Inventory - Dealer summary: Dealer inventory operationId: getDealerActiveInventory description: Get a dealer's currently active inventory parameters: - name: dealer_id in: path required: true description: Id representing the dealer to fetch the active inventory for schema: type: string - name: api_key in: query description: The API Authentication Key. Mandatory with all API calls. schema: type: string - name: rows in: query description: Number of results to return. Default is 10. Max is 50. schema: type: integer default: 10 maximum: 50 - name: start in: query description: Page number to fetch the results for the given criteria. Default is 1. schema: type: integer default: 1 responses: '200': description: Successful response with dealer active inventory content: application/json: schema: $ref: '#/components/schemas/BaseListing' /dealer/{dealer_id}/historical/inventory: get: tags: - Inventory - Dealer summary: Dealer's historical inventory operationId: getDealerHistoricalInventory description: "[v1 : Not Implemented Yet] - Get a dealer's historical inventory" parameters: - name: dealer_id in: path required: true description: Id representing the dealer to fetch the historical inventory for schema: type: string responses: '200': description: Successful response with dealer historical inventory content: application/json: schema: $ref: '#/components/schemas/BaseListing' /dealer/{dealer_id}/landing: get: tags: - Dealer summary: Experimental - Get cached version of dealer landing page by dealer id operationId: getDealerLandingPage description: Experimental - Get cached version of dealer landing page by dealer id parameters: - name: dealer_id in: path required: true description: Dealer id to get the landing page html for schema: type: string - name: api_key in: query description: The API Authentication Key. Mandatory with all API calls. schema: type: string responses: '200': description: Successful response with dealer landing page content: application/json: schema: $ref: '#/components/schemas/DealerLandingPage' /dealer/{dealer_id}/ratings: get: tags: - Dealer summary: Dealer's Rating operationId: getDealerRatings description: "[MOCK] Get a dealer's Rating" parameters: - name: dealer_id in: path required: true description: Id representing the dealer to fetch the ratings for schema: type: string responses: '200': description: Successful response with dealer rating content: application/json: schema: $ref: '#/components/schemas/DealerRating' /dealer/{dealer_id}/reviews: get: tags: - Dealer summary: Dealer's Review operationId: getDealerReviews description: "[MOCK] Get a dealer's Review" parameters: - name: dealer_id in: path required: true description: Id representing the dealer to fetch the reviews for schema: type: string responses: '200': description: Successful response with dealer reviews content: application/json: schema: $ref: '#/components/schemas/DealerReview' /dealers: get: tags: - Dealer summary: Find car dealers around operationId: dealerSearch description: The dealers API returns a list of dealers around a given point and radius. Max radius of only 50 miles is supported. parameters: - name: latitude in: query required: true description: Latitude component of location schema: type: number format: float - name: longitude in: query required: true description: Longitude component of location schema: type: number format: float - name: radius in: query required: true description: Radius around the search location (max 50 miles) schema: type: integer maximum: 50 - name: api_key in: query description: The API Authentication Key. Mandatory with all API calls. schema: type: string - name: rows in: query description: Number of results to return. Default is 10. Max is 50. schema: type: integer default: 10 maximum: 50 - name: start in: query description: Offset for the search results. Default is 1. schema: type: integer default: 1 responses: '200': description: Successful response with dealers list content: application/json: schema: $ref: '#/components/schemas/DealersResponse' /history/{vin}: get: tags: - History summary: Get a car's online listing history operationId: history description: The history API returns online listing history for a car identified by its VIN. History listings are sorted in the descending order of the listing date / last seen date. parameters: - name: vin in: path required: true description: The VIN to identify the car to fetch the listing history. Must be a valid 17 char VIN. schema: type: string minLength: 17 maxLength: 17 - name: api_key in: query description: The API Authentication Key. Mandatory with all API calls. schema: type: string - name: fields in: query description: List of fields to fetch, in case the default fields list in the response is to be trimmed down. schema: type: string - name: rows in: query description: Number of results to return. Default is 10. Max is 50. schema: type: integer default: 10 maximum: 50 - name: page in: query description: Page number to fetch the results for the given criteria. Default is 1. schema: type: number responses: '200': description: Successful response with vehicle listing history content: application/json: schema: type: array items: $ref: '#/components/schemas/HistoricalListing' /vin/{vin}/specs: get: tags: - VIN Decoder summary: VIN Decoder operationId: decode description: Get the basic information on specifications for a car identified by a valid VIN parameters: - name: vin in: path required: true description: VIN to decode schema: type: string minLength: 17 maxLength: 17 - name: api_key in: query description: The API Authentication Key. Mandatory with all API calls. schema: type: string responses: '200': description: Successful response with VIN decoded build information content: application/json: schema: $ref: '#/components/schemas/Build' /economy: get: tags: - VIN Decoder summary: Get Economy based on environmental factors operationId: getEconomy description: "[MOCK] Calculate Economy i.e. Environmental Friendliness" parameters: - name: vin in: query required: true description: VIN as a reference to the type of car for which Environmental Economy data is to be returned schema: type: string - name: api_key in: query description: The API Authentication Key. Mandatory with all API calls. schema: type: string responses: '200': description: Successful response with economy data content: application/json: schema: $ref: '#/components/schemas/Economy' /fuel_efficiency: get: tags: - VIN Decoder summary: Get fuel efficiency operationId: getEfficiency description: "[MOCK] Calculate fuel efficiency from taxonomy db mileage values" parameters: - name: vin in: query required: true description: VIN as a reference to the type of car for which fuel data is to be returned schema: type: string - name: api_key in: query description: The API Authentication Key. Mandatory with all API calls. schema: type: string responses: '200': description: Successful response with fuel efficiency data content: application/json: schema: $ref: '#/components/schemas/FuelEfficiency' /safety: get: tags: - VIN Decoder summary: Get Safety Rating operationId: getSafetyRating description: "[MOCK] Get Safety ratings from third party sources" parameters: - name: vin in: query required: true description: VIN to fetch the safety ratings schema: type: string - name: api_key in: query description: The API Authentication Key. Mandatory with all API calls. schema: type: string responses: '200': description: Successful response with safety rating content: application/json: schema: $ref: '#/components/schemas/SafetyRating' /averages: get: tags: - Market summary: Get Averages for YMM operationId: getAverages description: >- [Merged with the /search API - Please check the 'stats' parameter to the Search API] Get market averages for price / miles / msrp / dom (days on market) fields for active cars matching the given reference VIN's basic specification or Year, Make, Model, Trim (Optional) criteria. parameters: - name: vin in: query required: true description: VIN as a reference to the type of car for which averages data is to be returned schema: type: string - name: api_key in: query description: The API Authentication Key. Mandatory with all API calls. schema: type: string - name: year in: query description: Year of the car schema: type: string - name: make in: query description: Make of the car schema: type: string - name: model in: query description: Model of the Car schema: type: string - name: trim in: query description: Trim of the Car schema: type: string - name: fields in: query description: "Comma separated list of fields to generate stats for. Allowed fields: price, miles, msrp, dom (days on market)" schema: type: string responses: '200': description: Successful response with market averages content: application/json: schema: $ref: '#/components/schemas/Averages' /comparison: get: tags: - Market summary: Compare market operationId: getComparison description: "[MOCK] Get historical market trends for cars matching the given VIN's basic specification or Year, Make, Model, Trim (Optional) criteria" parameters: - name: vin in: query required: true description: VIN as a reference to the type of car for which comparison data is to be returned schema: type: string - name: api_key in: query description: The API Authentication Key. Mandatory with all API calls. schema: type: string responses: '200': description: Successful response with market comparison data content: application/json: schema: $ref: '#/components/schemas/ComparisonPoint' /competition: get: tags: - Market summary: Competitors operationId: getCompetition description: "[MOCK] Competitor cars in market for current vin" parameters: - name: vin in: query required: true description: VIN as a reference to the type of car for which competitors data is to be returned schema: type: string - name: api_key in: query description: The API Authentication Key. Mandatory with all API calls. schema: type: string responses: '200': description: Successful response with competitor data content: application/json: schema: $ref: '#/components/schemas/CompetitorsPoint' /depreciation: get: tags: - Market summary: Depreciation operationId: getDepreciation description: "[MOCK] Model resale value based on depreciation" parameters: - name: vin in: query required: true description: VIN as a reference to the type of car for which Depreciation stats is to be returned schema: type: string - name: api_key in: query description: The API Authentication Key. Mandatory with all API calls. schema: type: string responses: '200': description: Successful response with depreciation data content: application/json: schema: $ref: '#/components/schemas/DepreciationPoint' /mds: get: tags: - Market summary: Market Days Supply operationId: getMDS description: Get Market Days Supply (MDS) for a car identified by a valid VIN parameters: - name: vin in: query required: true description: VIN to decode schema: type: string - name: api_key in: query description: The API Authentication Key. Mandatory with all API calls. schema: type: string - name: exact in: query description: Exact parameter schema: type: string - name: latitude in: query description: Latitude component of location schema: type: number format: float - name: longitude in: query description: Longitude component of location schema: type: number format: float - name: radius in: query description: Radius around the search location schema: type: integer - name: debug in: query description: Debug parameter schema: type: string - name: include_sold in: query description: To fetch sold vins schema: type: string responses: '200': description: Successful response with market days supply data content: application/json: schema: $ref: '#/components/schemas/Mds' /popularity: get: tags: - Market summary: Popularity operationId: getPopularity description: "[MOCK] Get the Popularity for the given simple filter criteria (by given Year, Make, Model, Trim criteria)" parameters: - name: year in: query required: true description: Year of the car schema: type: string - name: make in: query required: true description: Make of the car schema: type: string - name: model in: query required: true description: Model of the Car schema: type: string - name: trim in: query required: true description: Trim of the Car schema: type: string - name: body_type in: query required: true description: Body type to filter the cars on schema: type: string - name: api_key in: query description: The API Authentication Key. Mandatory with all API calls. schema: type: string - name: stats in: query description: "The list of fields for which stats need to be generated. Allowed fields are - price, miles, msrp, dom." schema: type: string responses: '200': description: Successful response with popularity data content: application/json: schema: type: array items: $ref: '#/components/schemas/PopularityItem' /trends: get: tags: - Market summary: Get Trends for criteria operationId: getTrends description: Get historical market trends for cars matching the given VIN's basic specification or Year, Make, Model, Trim (Optional) criteria parameters: - name: vin in: query required: true description: VIN as a reference to the type of car for which trend data is to be returned schema: type: string - name: car_type in: query required: true description: "Car type. Allowed values are: new / used / certified" schema: type: string enum: [new, used, certified] - name: api_key in: query description: The API Authentication Key. Mandatory with all API calls. schema: type: string - name: year in: query description: Year of the car schema: type: string - name: make in: query description: Make of the car schema: type: string - name: model in: query description: Model of the Car schema: type: string - name: trim in: query description: Trim of the Car schema: type: string responses: '200': description: Successful response with trend data content: application/json: schema: type: array items: $ref: '#/components/schemas/TrendPoint' /facets: get: tags: - Facets summary: Facets operationId: getFacets description: >- [Merged with the /search API - Please check the 'facets' parameter to the Search API above] Get the facets for the given simple filter criteria (by given VIN's basic specification, Or by Year, Make, Model, Trim criteria) and facet fields. parameters: - name: fields in: query required: true description: "Comma separated list of fields to generate facets for. Supported fields are - year, make, model, trim, exterior_color, interior_color, drivetrain, vehicle_type, car_type, body_style, body_subtype, doors." schema: type: string - name: api_key in: query description: The API Authentication Key. Mandatory with all API calls. schema: type: string - name: vin in: query description: VIN as a reference to the type of car for which facets data is to be returned schema: type: string - name: year in: query description: Year of the car schema: type: string - name: make in: query description: Make of the car schema: type: string - name: model in: query description: Model of the Car schema: type: string - name: trim in: query description: Trim of the Car schema: type: string responses: '200': description: Successful response with facets content: application/json: schema: type: array items: $ref: '#/components/schemas/FacetItem' /plots: get: tags: - Graphs summary: Price, Miles plots data for given criteria operationId: getPriceMilesPlotData description: "[DEPRECATED - Please check this in /search API using plot=true] Get price, miles plot data for active cars matching the given VIN's basic specification or Year, Make, Model, Trim (Optional) criteria" deprecated: true parameters: - name: car_type in: query required: true description: Car type to get the scatter plot data for schema: type: string enum: [new, used, certified] - name: api_key in: query description: The API Authentication Key. Mandatory with all API calls. schema: type: string - name: vin in: query description: VIN as a reference to the type of car for which plot data is to be returned schema: type: string - name: year in: query description: Year of the car schema: type: string - name: make in: query description: Make of the car schema: type: string - name: model in: query description: Model of the Car schema: type: string - name: trim in: query description: Trim of the Car schema: type: string - name: rows in: query description: Number of results to return. Default is 1000. Max is 10000. schema: type: integer default: 1000 maximum: 10000 responses: '200': description: Successful response with plot data content: application/json: schema: type: array items: $ref: '#/components/schemas/PlotPoint' components: schemas: Error: type: object properties: message: type: string description: Error message code: type: integer description: Error code BaseListing: type: object description: Base listing object containing minimal car listing information properties: id: type: string description: Unique listing identifier vin: type: string description: Vehicle Identification Number heading: type: string description: Listing heading / title price: type: number description: Listed price in USD miles: type: integer description: Odometer reading in miles msrp: type: number description: Manufacturer Suggested Retail Price data_source: type: string description: Source of the listing data source_url: type: string description: URL to the original listing source seller_type: type: string description: "Type of seller: dealer, private, auction" enum: [dealer, private, auction] car_type: type: string description: Type of car listing enum: [new, used, certified] scraped_at: type: integer description: Unix timestamp when the listing was scraped last_seen_at: type: integer description: Unix timestamp when the listing was last seen first_seen_at: type: integer description: Unix timestamp when the listing was first seen dom: type: integer description: Days on market dom_180: type: integer description: Days on market in the last 180 days dom_active: type: integer description: Active days on market dealer_id: type: string description: Dealer identifier ref_price: type: number description: Reference/comparison price ref_miles: type: number description: Reference/comparison miles ref_year: type: integer description: Reference year build: $ref: '#/components/schemas/Build' dealer: $ref: '#/components/schemas/Dealer' Listing: allOf: - $ref: '#/components/schemas/BaseListing' type: object description: Full listing object with all attributes properties: vdp_url: type: string description: URL to the Vehicle Details Page stock_no: type: string description: Dealer stock number inventory_type: type: string description: Inventory classification ListingExtraAttributes: type: object description: Extra long-text attributes for a listing properties: id: type: string seller_comments: type: string description: Seller comments from the listing options: type: array items: type: string description: List of vehicle options features: type: array items: type: string description: List of vehicle features ListingMedia: type: object description: Media assets associated with a listing properties: id: type: string photo_links: type: array items: type: string description: List of photo URLs photo_count: type: integer description: Total number of photos ListingVDP: type: object description: Vehicle Details Page HTML content properties: id: type: string html: type: string description: Cached HTML content of the Vehicle Details Page HistoricalListing: type: object description: Historical listing record for a vehicle properties: id: type: string vin: type: string price: type: number description: Listed price at time of listing miles: type: integer description: Odometer reading at time of listing scraped_at: type: integer description: Unix timestamp when listing was scraped last_seen_at: type: integer description: Unix timestamp when listing was last seen first_seen_at: type: integer description: Unix timestamp when listing was first seen dealer_id: type: string source: type: string seller_type: type: string enum: [dealer, private, auction] SearchResponse: type: object description: Response object from search API properties: num_found: type: integer description: Total number of listings found listings: type: array items: $ref: '#/components/schemas/Listing' stats: type: object description: Statistics for the search results additionalProperties: true facets: type: object description: Facets for the search results additionalProperties: true VinReport: type: object description: Summary report for a VIN properties: vin: type: string year: type: integer make: type: string model: type: string trim: type: string avg_price: type: number avg_miles: type: number num_active_listings: type: integer Dealer: type: object description: Dealer information properties: id: type: string description: Unique dealer identifier name: type: string description: Dealer name website: type: string description: Dealer website URL dealer_type: type: string description: Type of dealership zip: type: string description: Dealer zip code city: type: string description: Dealer city state: type: string description: Dealer state latitude: type: number description: Dealer latitude longitude: type: number description: Dealer longitude phone: type: string description: Dealer phone number franchises: type: array items: type: string description: List of car franchises/makes the dealer carries DealersResponse: type: object description: Response from dealers search properties: num_found: type: integer description: Total number of dealers found dealers: type: array items: $ref: '#/components/schemas/Dealer' DealerLandingPage: type: object description: Dealer landing page content properties: dealer_id: type: string html: type: string description: Cached HTML content of the dealer landing page DealerRating: type: object description: Dealer rating information properties: dealer_id: type: string overall_rating: type: number description: Overall dealer rating components: $ref: '#/components/schemas/RatingComponents' DealerReview: type: object description: Dealer review information properties: dealer_id: type: string reviews: type: array items: $ref: '#/components/schemas/ReviewComponents' RatingComponents: type: object description: Rating components breakdown properties: customer_service: type: number facilities: type: number overall_experience: type: number recommend_dealer: type: number ReviewComponents: type: object description: Individual review data properties: rating: type: number title: type: string body: type: string author: type: string date: type: string Build: type: object description: Vehicle build/specification information decoded from VIN properties: year: type: integer description: Model year make: type: string description: Vehicle make model: type: string description: Vehicle model trim: type: string description: Vehicle trim level body_type: type: string description: Body type (sedan, SUV, truck, etc.) vehicle_type: type: string description: Vehicle type classification transmission: type: string description: Transmission type drivetrain: type: string description: Drivetrain type (FWD, AWD, RWD, 4WD) fuel_type: type: string description: Fuel type engine: type: string description: Engine description engine_size: type: string description: Engine displacement cylinders: type: integer description: Number of cylinders doors: type: integer description: Number of doors made_in: type: string description: Country of manufacture highway_fuel_economy: type: integer description: Highway fuel economy in MPG city_fuel_economy: type: integer description: City fuel economy in MPG Economy: type: object description: Environmental economy data for a vehicle properties: vin: type: string co2_five_year_cost: type: number description: CO2 cost over 5 years energy_impact_score: type: number description: Energy impact score ghg_score: type: number description: Greenhouse gas score smog_score: type: number description: Smog emission score FuelEfficiency: type: object description: Fuel efficiency data for a vehicle properties: vin: type: string highway: type: number description: Highway fuel efficiency in MPG city: type: number description: City fuel efficiency in MPG combined: type: number description: Combined fuel efficiency in MPG annual_fuel_cost: type: number description: Estimated annual fuel cost in USD SafetyRating: type: object description: Safety rating data from third party sources properties: vin: type: string overall_rating: type: number description: Overall safety rating frontal_crash_rating: type: string description: Frontal crash test rating side_crash_rating: type: string description: Side crash test rating rollover_rating: type: string description: Rollover test rating Averages: type: object description: Market averages for a vehicle type properties: price: type: number description: Average price miles: type: number description: Average mileage msrp: type: number description: Average MSRP dom: type: number description: Average days on market ComparisonPoint: type: object description: Market comparison data point properties: vin: type: string price: type: number miles: type: number dom: type: number data_points: type: array items: type: object additionalProperties: true CompetitorsPoint: type: object description: Competitor vehicle data properties: vin: type: string same_cars: $ref: '#/components/schemas/CompetitorsSameCars' similar_cars: $ref: '#/components/schemas/CompetitorsSimilarCars' CompetitorsSameCars: type: object description: Same vehicle competitors properties: avg_price: type: number avg_miles: type: number num_listings: type: integer cars: type: array items: $ref: '#/components/schemas/CompetitorsCarDetails' CompetitorsSimilarCars: type: object description: Similar vehicle competitors properties: avg_price: type: number avg_miles: type: number num_listings: type: integer cars: type: array items: $ref: '#/components/schemas/CompetitorsCarDetails' CompetitorsCarDetails: type: object description: Competitor car details properties: id: type: string vin: type: string price: type: number miles: type: integer make: type: string model: type: string trim: type: string year: type: integer DepreciationPoint: type: object description: Depreciation data for a vehicle properties: vin: type: string current_value: type: number depreciation_stats: type: array items: $ref: '#/components/schemas/DepreciationStats' DepreciationStats: type: object description: Annual depreciation statistics properties: year: type: integer description: Calendar year avg_price: type: number description: Average price for that year depreciation_pct: type: number description: Depreciation percentage from original Mds: type: object description: Market Days Supply data properties: vin: type: string mds: type: number description: Market Days Supply value supply: type: integer description: Number of supply units sales_per_day: type: number description: Average sales per day PopularityItem: type: object description: Popularity data item properties: year: type: integer make: type: string model: type: string trim: type: string popularity_index: type: number description: Popularity index score num_listings: type: integer TrendPoint: type: object description: Historical trend data point properties: date: type: string description: Date of the trend data point (YYYY-MM-DD) avg_price: type: number description: Average price on that date avg_miles: type: number description: Average miles on that date avg_dom: type: number description: Average days on market on that date num_listings: type: integer description: Number of listings on that date FacetItem: type: object description: A facet item with field name, value, and count properties: item: type: string description: Facet value count: type: integer description: Number of listings matching this facet value PlotPoint: type: object description: Price/miles scatter plot data point properties: id: type: string price: type: number description: Listing price miles: type: integer description: Odometer reading dom: type: integer description: Days on market latitude: type: number longitude: type: number