Market Days Supply (MDS) is a key metric that indicates how long the current inventory will last based on recent sales trends. It is calculated by dividing the active inventory count by the average daily sales rate over the past 45 days. This helps dealers and manufacturers gauge vehicle demand and optimize stock levels.
The precise formula for MDS is:
MDS = (Active inventory count) / (Past 45 days per day sale rate)
This metric is crucial for inventory management, allowing businesses to optimize their stock levels and make informed decisions about purchasing and pricing strategies.
It also acts as a proxy for vehicle demand and supply dynamics in the automotive market. A lower MDS indicates high demand and quick turnover, while a higher MDS suggests slower sales and potential overstock issues.
This API allows you to retrieve MDS for specific vehicles, dealerships, or geographic areas, enabling targeted market analysis and inventory management. You can filter results by various parameters such as vehicle type, make, model, trim, and more.
GET https://api.marketcheck.com/v2/mds/car
The following example demonstrates how to use the Market Days Supply API to calculate MDS for vehicles based on inventory turnover rates.
import axios from 'axios';
const options = {
method: 'GET',
url: 'https://api.marketcheck.com/v2/mds/car',
params: {
api_key: 'YOUR_API_KEY',
vin: '5FNRL6H73PB057520',
exact: 'true',
debug: 'true'
},
headers: {Accept: 'application/json'}
};
try {
const { data } = await axios.request(options);
console.log(data);
} catch (error) {
console.error(error);
}
This API is built on top of the Inventory Search and Past Inventory APIs, so it supports most of the same parameters, allowing you to filter and refine your MDS calculations across various dimensions.
Your MarketCheck API authentication key. Required for every request, unless OAuth is used.
The base exterior color to filter results by (e.g. White, Black, Blue, Silver, Red). Accepts multiple colors as a comma-separated list.
The base interior color to filter results by (e.g. Black, Brown, Beige, Red). Accepts multiple colors as a comma-separated list.
Filters listings by body subtype (e.g., Crew, Extended, Regular, Extended Crew). Accepts multiple values separated by commas.
Filters listings by body type (e.g., SUV, Pickup, Sedan, Hatchback, Convertible). Accepts multiple values separated by commas.
Filters listings by inventory type. Allowed values - new, used, certified.
If true, returns only vehicles with a single previous owner; if false or omitted, no ownership filter is applied. Default — false.
If true, returns only vehicles with a clean title history; if false or omitted, no title filter is applied. Default — false.
Filters listings by city name (e.g. Los Angeles, San Francisco, Houston).
Filters listings by city fuel-economy mileage. Specify as min-max MPG (e.g., 20-35).
Filters listings by country code. Allowed values - us, ca, all. Default — us.
Filters listings by engine cylinder count (e.g., 4, 6, 8). Accepts multiple values as a comma-separated list.
Filters listings by MarketCheck dealer ID.
Filters dealers by type. Allowed values — franchise, independent.
Filters listings by the name of the dealership group. Accepts multiple values as a comma-separated list.
If true, returns applied year, make, model, and trim filters in the response. Default — false.
Filters listings by Days on Market observed over the last 180 days. Specify as min-max days (e.g., 10-50).
Filters listings by active Days on Market (DOM). Specify as min-max days.
Filters listings by total Days on Market (DOM). Specify as min-max days.
Filters listings by number of doors (e.g., 2, 4). Accepts multiple values as comma-separated list.
Filters listings by active Days on Site (DOS). Specify as min-max days.
Filters listings by drivetrain (FWD, RWD, 4WD). Accepts multiple values separated by commas.
Filters listings by engine designation (e.g., 2.0L I4, 3.5L V6, 2.5L H4). Accepts multiple values as comma-separated list.
Filters listings by engine aspiration (Turbocharged, Naturally Aspirated, etc.). Accepts multiple values separated by commas.
Filters listings by engine block layout (V, I, H). Accepts multiple values separated by commas.
Filters listings by engine displacement size (e.g., 2.0, 2.5, 3.5). Accepts multiple values separated by commas.
Filters listings by engine displacement size. Specify as min-max liters (e.g., 1.5-3.0).
If true, performs exact matching (upto trim level) in MDS API queries. If false, performs partial matching (upto model level). Default — false.
Filters listings by exterior color (e.g. White, Summit White, Gun Metallic). Accepts multiple values as comma-separated list.
Filters listings by finance down-payment amount in USD. Specify a single value or a min-max range.
Filters listings by finance down-payment percentage. Specify a single value or min-max.
Filters listings by finance Estimated Monthly Payment (EMP) in USD. Specify a single value or min-max.
Filters listings by finance loan APR. Specify a single value or min-max.
Filters listings by finance loan term in months. Specify a single value or min-max months.
Filters listings by fuel type (e.g., Unleaded, Diesel, Electric, Premium Unleaded, Electric / Unleaded). Accepts multiple values separated by commas.
Filters listings by highway fuel-economy mileage. Specify as min-max MPG (e.g., 25-40).
If true, returns listings marked as in transit; if false or omitted, no in-transit filter is applied.
If true, includes array of sold VINs in MDS API responses. Default — false.
Filters listings by interior color. Accepts multiple values as comma-separated list.
Latitude component of the search location (decimal degrees). Used for geospatial queries along with longitude and radius parameters.
Filters listings by lease down-payment amount in USD. Specify a single value or min-max.
Filters listings by lease Estimated Monthly Payment (EMP) in USD. Specify a single value or min-max.
Filters listings by lease term length in months. Specify a single value or min-max.
Longitude component of the search location (decimal degrees). Used for geospatial queries along with latitude and radius parameters.
Filters listings by vehicle make (e.g., Toyota, Ford, Mercedes-Benz). Accepts multiple values as comma-separated list.
Filters listings by odometer reading. Specify as min-max miles (e.g., 1000-50000).
Filters listings by specific vehicle model (e.g., Camry). Accepts multiple values separated by commas.
Filters listings by Metropolitan Statistical Area (MSA) code.
Filters listings by Manufacturer's Suggested Retail Price (MSRP). Specify as min-max USD (e.g., 20000-45000).
Filters listings by advertised price in USD. Specify as min-max (e.g., 1000-50000).
Search radius around the specified location in miles. Used with zip or latitude and longitude for geospatial queries.
Filters listings by source marketplace domain (e.g., autotrader.com, cars.com).
Filters listings by US or Canadian state/province code (e.g., CA, NY, ON). Accepts multiple codes separated by commas.
Filters listings by transmission type (Automatic, Manual, etc.). Accepts multiple values separated by commas.
Filters listings by vehicle trim (e.g., EX, Limited). Accepts multiple values separated by commas.
Filters listings by vehicle type (Truck, Car). Accepts multiple values separated by commas.
Filters listings by full 17-character Vehicle Identification Number (VIN).
Filters listings by model year (e.g., 2020). Accepts multiple years separated by commas.
Year-Make-Model-Trim composite string(s). Each combo uses pipe separators and combinations can be comma-separated. For example, 2019|Toyota|Camry|LE,2020|Honda|Civic|EX. Useful for finding multiple groups of similar cars. Alternatively, you can use vins or taxonomy_vins for VIN-based queries.
Filters listings within the specified 5-digit ZIP code.
US, but can be set to CA for Canadian market analysis.vin parameter to filter results by specific Vehicle Identification Number (VIN) to get MDS for similar vehicles.vin is provided, the API will return MDS for similar vehicles based on the VIN's make, model, year, trim, version and build code (requires exact=true for exact match).vins to find similar cars, the MDS API does not support vins as a filter. Instead, it uses the vin parameter to return MDS for similar vehicles based on the VIN's make, model, year, and trim.exact=true to filter vehicles by Year, Make, Model, Trim, Version, and Build Code.vin to return MDS for similar vehicles. Independently, has no effect.debug=true to include decoded Year, Make, Model, and Trim in the response.include_sold=true to include all VINs (up to 10,000) sold in the last 45 days matching the search criteria.ymmt parameter to filter results by Year, Make, Model, and Trim in a single string format separated by pipe (|).ymmt=2020|Toyota|Camry|LE,2021|Honda|Civic|EXinterface MDSResponse {
mds: number; // Market Days Supply = active / (sold / 45)
total_active_cars_for_ymmt: number; // Total active cars for the specified search criteria
total_cars_sold_in_last_45_days: number; // Total cars sold in the last 45 days
sold_vins?: string[]; // List of VINs sold in the last 45 days (if include_sold=true)
debug?: Debug[]; // Returned if debug=true; shows matched YMMT attributes
}
interface Debug {
year: number[];
make: string[];
model: string[];
trim: string[];
}
200 OK - Returns a JSON object containing the MDS and related informationmds is returned as null when MDS cannot be calculated due to zero sales in the past 45 days.| Status Code | Description | Common Causes |
|---|---|---|
| 400 | Bad Request | Invalid parameter values |
| 401 | Unauthorized | Missing/invalid API key |
| 403 | Forbidden | Access denied to resource |
| 422 | Unprocessable Entity | VIN decoding failed or invalid parameters |
| 429 | Too Many Requests | Rate limit exceeded |
| 500 | Internal Server Error | Temporary server issues |
| 502 | Bad Gateway | Issues with upstream services |
| 503 | Service Unavailable | API maintenance or downtime |
Error Response Format
Most error responses follow this structure, except for 502 and 503 errors
{
"code": <HTTP status code>,
"message": "<Error message describing the issue>"
}
Using the MDS API, you can estimate how long the current inventory of similar vehicles will last based on recent sales trends. Use vin parameter to filter results to similar vehicles based on the VIN's make, model, year, and trim.
Use the exact parameter to ensure that the MDS is calculated for vehicles that match the exact specifications of the VIN provided.
Example:
import axios from 'axios';
const options = {
method: 'GET',
url: 'https://api.marketcheck.com/v2/mds/car',
params: {
api_key: 'YOUR_API_KEY',
vin: '4T1DAACK3SU056992',
exact: 'true',
debug: 'true'
},
headers: {Accept: 'application/json'}
};
try {
const { data } = await axios.request(options);
console.log(data);
} catch (error) {
console.error(error);
}
The MDS API can be used to analyze market demand for specific vehicles or vehicle types. By filtering results based on parameters like make, model, year, and many others, you can gain insights into how quickly vehicles are selling in different regions or markets.
include_sold parameter can be used to include sold VINs in the response, allowing you to see which vehicles are in high demand and how quickly they are selling.
The total_cars_sold_in_last_45_days field provides additional context on market demand, helping you understand how many vehicles matching your criteria have been sold recently.
Example:
Here in this example, we are retrieving MDS for new SUVs from Hyundai and Kia at Austin, Texas, including sold VINs to analyze market demand:
import axios from 'axios';
const options = {
method: 'GET',
url: 'https://api.marketcheck.com/v2/mds/car',
params: {
api_key: 'YOUR_API_KEY',
car_type: 'new',
make: 'Hyundai,Kia',
body_type: 'SUV',
city: 'Austin',
state: 'TX',
include_sold: 'true'
},
headers: {Accept: 'application/json'}
};
try {
const { data } = await axios.request(options);
console.log(data);
} catch (error) {
console.error(error);
}
The MDS API can be used to monitor inventory turnover rates for specific dealerships or dealership groups. By filtering results based on dealer_id, source, dealership_group_name, or dealer_type, you can track how quickly vehicles are selling at different dealerships.
This is useful for dealerships looking to optimize their inventory management and sales strategies.
Example:
import axios from 'axios';
const options = {
method: 'GET',
url: 'https://api.marketcheck.com/v2/mds/car',
params: {api_key: 'YOUR_API_KEY', source: 'carmax.com'},
headers: {Accept: 'application/json'}
};
try {
const { data } = await axios.request(options);
console.log(data);
} catch (error) {
console.error(error);
}
The MDS API can be used to analyze the performance of different vehicle segments in the market. By filtering results based on parameters like make, model, body_type, fuel_type etc., you can gain insights into how various segments are performing in terms of sales velocity and inventory levels.
This can help manufacturers and dealers understand which segments are in high demand and which ones may need adjustments in inventory or marketing strategies.
Example:
Here in this example, we are retrieving MDS for electric vehicles (EVs) to analyze their market performance:
import axios from 'axios';
const options = {
method: 'GET',
url: 'https://api.marketcheck.com/v2/mds/car',
params: {api_key: 'YOUR_API_KEY', car_type: 'new', fuel_type: 'electric'},
headers: {Accept: 'application/json'}
};
try {
const { data } = await axios.request(options);
console.log(data);
} catch (error) {
console.error(error);
}
The MDS API can be used to perform local market analysis by filtering results based on geographic parameters —
citystateziplatitude & longitudeThis allows you to understand how vehicles are performing in specific regions, helping dealers and manufacturers tailor their strategies to local market conditions.
Example:
import axios from 'axios';
const options = {
method: 'GET',
url: 'https://api.marketcheck.com/v2/mds/car',
params: {
api_key: 'YOUR_API_KEY',
car_type: 'used',
year: '2022,2023',
make: 'Toyota',
model: 'Camry',
trim: 'LE',
zip: '78701',
radius: '50'
},
headers: {Accept: 'application/json'}
};
try {
const { data } = await axios.request(options);
console.log(data);
} catch (error) {
console.error(error);
}
The MDS API can also be used to analyze the Canadian market by setting the country parameter to CA. This allows you to retrieve MDS data for vehicles in Canada, helping dealers and manufacturers understand market dynamics in that region.
Example:
import axios from 'axios';
const options = {
method: 'GET',
url: 'https://api.marketcheck.com/v2/mds/car',
params: {
api_key: 'YOUR_API_KEY',
car_type: 'new',
make: 'Hyundai,Kia',
model: 'SUV',
country: 'CA'
},
headers: {Accept: 'application/json'}
};
try {
const { data } = await axios.request(options);
console.log(data);
} catch (error) {
console.error(error);
}