com.marketcheck/api
Official9 toolsMarketCheck automotive data: search US/UK listings, predict prices, decode VINs, market history.
Search US/UK vehicle listings, predict prices, decode VINs, and analyze automotive market history.
Captured live from the server via tools/list.
search_active_cars
Search for cars in the United States and Canada market with comprehensive filters. This endpoint allows searching market vehicles that are up for sale in US and Canadian market right now. This endpoint serves only dealer listings. DO NOT USE CARFAX FIELDS: Carfax data on this server is incomplete and unreliable. Do NOT pass `carfax_1_owner` or `carfax_clean_title` as filters, do NOT request them in facets/stats, and do NOT infer ownership history, title status, or any other meaning from any `carfax_*` value that might appear in a listing. Treat all Carfax fields as if they did not exist. MANDATORY TWO-STEP WORKFLOW for filtering by categorical fields. Field values in this API are NOT canonical English (e.g. fuel_type="Hybrid" is wrong; the actual value is "HEV" or "Electric / Unleaded"). Skipping step 1 leads to silent zero-result responses. STEP 1 — discover valid values: call this tool with ONLY the `facets` parameter (and an optional location filter), rows=1, no other filters set. STEP 2 — filter for real: re-call with the exact strings returned in step 1. For instance, to filter cars by powertrain in New York: STEP 1 call: search_active_cars(facets="powertrain_type", rows=1, state="NY") -> returns {"powertrain_type": [{"item": "HEV", "count": 18058}, {"item": "PHEV", "count": 6004}, ...]} STEP 2 call: search_active_cars(powertrain_type="HEV,PHEV", state="NY") Fields that REQUIRE step 1 before being used as filters: powertrain_type, fuel_type, trim, body_type, drivetrain, transmission, make, model, exterior_color, interior_color. WRONG: search_active_cars(fuel_type="Hybrid") # silent zero-result CORRECT: search_active_cars(facets="fuel_type", rows=1) # discover valid values first then: search_active_cars(fuel_type="Electric / Unleaded") DEALER FILTERING: When any of dealer_id, source, mc_website_id, mc_dealer_id, mc_location_id, mc_rooftop_id, mc_dealership_group_id, mc_dealership_group_name, mc_sub_dealership_group_id, mc_sub_dealership_group_name, or mc_category are provided, this tool automatically routes to the Dealer Inventory Syndication API (GET /dealerships/inventory) instead of the standard inventory search API for optimized dealer-specific inventory retrieval. Use search_past_90_days for expired/sold dealer inventory analysis. STALENESS METRICS — dos_active vs dom_active (read before answering "how long has this car been for sale" questions): - dos_active (Days on Site): days this listing has been active at the CURRENT dealer. Answers "how long has THIS DEALER been trying to sell this car." DEFAULT: use dos_active for stale-inventory and "how long has it been listed" questions (e.g. finding dealers with stale inventory in an area). - dom_active (Days on Market): cumulative days the VEHICLE has been actively listed for sale across ALL dealers — it survives dealer-to-dealer transfers. Use ONLY when the question is about the vehicle's total market exposure, e.g. evaluating a car at auction or in a dealer trade: a car showing dos_active=15 at the current store may show dom_active=60 because it has been passed around dealers for two months. This rule applies to choosing filter params (dos_active_range vs dom_active_range), sort_by values, and which field to read and report from listing results. When unsure which the user means, default to dos_active.
Parameters (126)
- active_inventory_date_rangeany
Date range to filter listings active within range (YYYYMMDD-YYYYMMDD)
- base_ext_colorany
Base exterior color to match (comma-separated values)
- base_exterior_colorany
Base exterior color to match (comma-separated values)
- base_int_colorany
Base interior color to match (comma-separated values)
- base_interior_colorany
Base interior color to match (comma-separated values)
- exterior_colorany
Exterior color to match (comma-separated values)
- interior_colorany
Interior color to match (comma-separated values)
- body_subtypeany
Body subtype to filter listings on (comma-separated values)
- body_typeany
Filter listing on their body type
- car_typeany
Car type (new/used/certified)
- cylindersany
Number of engine cylinders (e.g., 4, 6, 8)
- doorsany
Number of doors (e.g., 2, 4)
- drivetrainany
Filter listing on their drivetrain
- engineany
Filter listing on their engine
- engine_aspirationany
Engine Aspiration to match (comma-separated values)
- engine_blockany
Engine Block to match (comma-separated values)
- engine_sizeany
Engine Size to match (comma-separated values)
- engine_size_rangeany
Engine size range in format "min-max" (e.g., "1.0-2")
- fuel_typeany
Filter listing on their fuel type. WARNING: This field has many non-normalized values. RECOMMENDED: Use powertrain_type instead for reliable filtering, OR first call this tool with facets="fuel_type|0|1000" to discover exact available values.
- makeany
Filter listings on their make
- modelany
Filter listings on their model
- powertrain_typeany
Filter on powertrain_type. Available values: "Combustion" (gas/diesel), "HEV" (Hybrid Electric), "MHEV" (Mild Hybrid), "BEV" (Battery Electric), "PHEV" (Plug-in Hybrid), "FCEV" (Fuel Cell Electric), "EREV" (Extended Range Electric). RECOMMENDED: Use this field instead of fuel_type for consistent and reliable filtering of vehicle power sources.
- seating_capacityany
Number of seats (e.g., 5, 7, 8)
- transmissionany
Filter listing on their transmission
- trimany
Filter listing on their trim
- vehicle_typeany
Filter listing on their vehicle type
- versionany
Filter listings on their version
- yearany
Vehicle manufacturing year (e.g., 2020, 2021)
- year_rangeany
Year range in format "min-max" (e.g., "2019-2021")
- carfax_1_ownerany
Indicates whether car has had only one owner or not
- carfax_clean_titleany
Indicates whether car has clean ownership records
- cityany
Filter listing on City in which they are listed
- countryany
Filter listing on Country in which they are listed
- latitudeany
Latitude component of location
- longitudeany
Longitude component of location
- msa_codeany
Filter listing on msa code in which they are listed
- radiusany
Radius around the search location (Unit - Miles)
- stateany
Filter listing on State in which they are listed
- zipany
Filter listing on ZIP around which they are listed
- city_mpg_rangeany
City mileage range in format "min-max" (e.g., "1000-5000")
- highway_mpg_rangeany
Highway mileage range in format "min-max" (e.g., "1000-5000")
- dom_180_rangeany
Last 180 Days on Market range in format "min-max" (e.g., "10-50")
- dom_active_rangeany
Cumulative days the VEHICLE has been actively listed across ALL dealers (survives dealer transfers) in format "min-max" (e.g., "10-50"). Use for total-market-exposure analysis (auction/trade evaluation); otherwise prefer dos_active_range. See STALENESS METRICS above.
- dom_rangeany
Days on Market range in format "min-max" (e.g., "10-50")
- dos_active_rangeany
Days the listing has been active at the CURRENT dealer, in format "min-max" (e.g., "10-50"). Dealer-level staleness — DEFAULT metric for "how long has it been for sale" questions. See STALENESS METRICS above.
- first_seen_at_mc_daysany
First seen at MC days range in format "max-min" (e.g., "25-12" for 12 to 25 days ago).
- first_seen_at_mc_rangeany
First seen at MC date range in format YYYYMMDD-YYYYMMDD(prev_date-later_date)
- first_seen_at_source_daysany
First seen at source days range in format "max-min" (e.g., "25-12" for 12 to 25 days ago).
- first_seen_at_source_rangeany
First seen at source date range in format YYYYMMDD-YYYYMMDD(prev_date-later_date)
- first_seen_daysany
First seen days range in format "max-min" (e.g., "30-10" for 10 to 30 days ago).
- first_seen_rangeany
First seen date range in format YYYYMMDD-YYYYMMDD(prev_date-later_date)
- last_seen_daysany
Last seen days range in format "max-min" (e.g., "3-1" for 1 to 3 days ago).
- last_seen_rangeany
Last seen date range in format YYYYMMDD-YYYYMMDD(prev_date-later_date)
- dedupany
If true, gives results with is_searchable irrespective of dealer_id/mc_website_id/source
- exclude_certifiedany
Boolean param to exclude certified cars from search results
- exclude_dealer_idsany
List of dealer ids to exclude from result
- exclude_high_value_featuresany
Filter to remove listings with specified excluded HVFs. Use facets="high_value_features|0|1000" first to discover available feature names.
- exclude_makeany
List of makes to exclude from result
- exclude_mc_website_idsany
List of dealer ids to exclude from result
- exclude_options_packagesany
Filter to remove listings with specified excluded OPs. Use facets="options_packages|0|1000" first to discover available package names.
- exclude_sourcesany
List of sources to exclude from result
- finance_down_paymentany
Search listings with exact/range down payment in finance offers
- finance_down_payment_perany
Search listings with exact/range down payment percentage
- finance_empany
Search listings with exact/range Estimated Monthly Payment(EMI)
- finance_loan_aprany
Search listings with exact/range loans Annual Percentage Rate
- finance_loan_termany
Search listings with exact/range finance loan term
- include_financeany
Boolean param to search for listings that include finance options
- include_leaseany
Boolean param to search for listings that include leasing options
- lease_down_paymentany
Search listings with exact/range down payment in lease offers
- lease_empany
Search listings with exact/range lease Estimated Monthly Payment(EMI)
- lease_termany
Search listings with exact/range lease term
- high_value_featuresany
Filter listings on their high_value_features (intersection of provided HVFs). IMPORTANT: Before using this filter, first call this tool with facets="high_value_features|0|1000" to get the complete list of available high_value_features and their counts. This ensures you use exact feature names as they appear in the data.
- options_packagesany
Filter listings on their options_packages (intersection of provided OPs). IMPORTANT: Before using this filter, first call this tool with facets="options_packages|0|1000" to get the complete list of available options packages and their counts. This ensures you use exact package names as they appear in the data.
- vinany
Filter listing on their VIN
- vinsany
Comma separated list of 17 digit vins (max 10 VINs per request)
- taxonomy_vinsany
Comma separated list of 10 letters excerpt from 17 letter VIN
- mmany
Make-Model concatenated string from auto-complete API
- ymmany
Year-Make-Model concatenated string from auto-complete API
- ymmtany
Comma separated list of Year|Make|Model|Trim combinations
- matchany
Comma separated list of Year,Make,Model,Trim fields for exact match with vins
- in_transitany
Boolean to filter in transit vehicles
- include_non_vin_listingsany
Include non vin listings (default false)
- include_preferred_dealer_flagany
Flag to add preferred dealers flag based on client filter score
- include_relevant_linksany
Include relevant links (default true)
- inventory_count_rangeany
Inventory count range for total listings in dealers inventory
- min_photo_linksany
Filter listings by number of photo links within given range
- min_photo_links_cachedany
Filter listings by number of cached photo links within range
- nodedupany
If true, API gives results without is_searchable (multiple listings for single vin)
- ownedany
When true, returns listings actually owned by dealer (used with dealer_id/mc_website_id/source)
- photo_linksany
Boolean to include only listings that have photo_links
- photo_links_cachedany
Boolean to include only listings that have photo_links_cached
- plotany
If true, results in around 25k coordinates with limited fields for plotting
- preferred_dealersany
Flag to add preferred dealers flag based on client filter score
- preferred_dealers_onlyany
Flag to show only preferred dealers listings
- price_changeany
Query to filter listings based on positive and negative price change
- price_change_rangeany
Price change range in format "min-max" (e.g., "10-500")
- price_rangeany
Price range in format "min-max" (e.g., "1000-5000")
- msrp_rangeany
MSRP range in format "min-max" (e.g., "1000-5000")
- miles_rangeany
Miles range in format "min-max" (e.g., "1000-5000")
- dealer_idany
Dealer ID filter to search inventory from specific dealer
- dealer_typeany
Type of dealer (e.g., franchise, independent)
- sourceany
Source filter to search inventory from specific source
- stock_noany
Filter listing on their stock number on lot
- vdp_urlany
Filter based on vehicle detail page URL
- mc_website_idany
MarketCheck website ID filter
- mc_dealer_idany
MarketCheck dealer ID filter
- mc_location_idany
MarketCheck location ID filter
- mc_rooftop_idany
MarketCheck rooftop ID filter
- mc_dealership_group_idany
MarketCheck dealership group ID filter
- mc_dealership_group_nameany
MarketCheck dealership group name filter
- mc_sub_dealership_group_idany
MarketCheck sub-dealership group ID filter
- mc_sub_dealership_group_nameany
MarketCheck sub-dealership group name filter
- mc_categoryany
MarketCheck seller category. Values: "Dealer", "Retailer", "Dealership Group", "Aggregator", "Marketing", "Financing"
- facet_sortany
Controls sort order of facet terms: - count (default): Sort by frequency (highest first) - index: Sort alphabetically
- facetsany
Field facets return unique terms and their counts for categorical data, useful for building search filters and understanding inventory distribution. Syntax: facets=field_name|offset|limit|min_count - offset (default: 0): Start position for terms - limit (default: 20, max: 1000): Number of terms to return - min_count (optional): Minimum count for a term to be included Example: facets=make|0|60|2 returns top 60 makes with at least 2 listings each
- range_facetsany
Comma separated list of numeric fields for range facets
- statsany
List of fields for which stats need to be generated
- sort_byany
Sort by field (dist|price|miles|msrp|dom|dom_180|dom_active|dos_active|highway_mpg|city_mpg|last_seen|first_seen|lease_term|lease_emp|lease_down_payment|finance_loan_term|finance_loan_apr|finance_emp|finance_down_payment|price_change_percent). For staleness sorting, default to dos_active (current dealer) over dom_active (all dealers) — see STALENESS METRICS above.
- sort_orderany
Sort order (asc|desc)
- rowsany
Number of results to return. For standard searches: default 5, max 50. For dealer/syndication searches (when dealer_id, mc_dealer_id, mc_location_id, or similar dealer identifiers are provided): defaults to 1500 (full inventory), max 1500.
- startany
Page number/offset to fetch results (default 0, max depends on package)
- seller_typeany
Filter by seller type. Only 3 strict values allowed: "dealer" (default), "fsbo" (private seller), "auction"
- fetch_all_photosboolean
When False (default), limits photo links to single photo per listing to reduce token usage. When True, returns all photo links.
- include_dealer_objectboolean
When True, includes dealer object in response. Dealer object structure: - id (number): Unique dealer identifier - website (string): Dealer website URL - name (string): Dealer business name - dealer_type (string, optional): Dealer classification (franchise, independent) - street, city, state, country (string, optional): Address components - latitude, longitude (string, optional): Geographic coordinates - zip (string, optional): Postal/ZIP code - phone (string, optional): Contact phone number - seller_email (string, optional): Contact email address - dealership_group_name (string, optional): Parent dealership group - msa_code (string, optional): Metropolitan Statistical Area code
- include_mc_dealership_objectboolean
When True, includes mc_dealership object in response. McDealership object structure: - mc_website_id (number, optional): MarketCheck website identifier - mc_dealer_id (number, optional): MarketCheck dealer identifier - mc_location_id (number, optional): MarketCheck location identifier - mc_rooftop_id (number, optional): MarketCheck rooftop identifier - mc_dealership_group_id (number, optional): MarketCheck dealership group identifier - mc_dealership_group_name (string, optional): MarketCheck dealership group name - mc_sub_dealership_group_id (number, optional): MarketCheck sub-dealership group identifier - mc_sub_dealership_group_name (string, optional): MarketCheck sub-dealership group name - mc_category (string, optional): MarketCheck seller category. Values: "Dealer", "Retailer", "Dealership Group", "Aggregator", "Marketing", "Financing" - website (string, optional): Dealer website URL - name (string, optional): Dealer business name - dealer_type (string, optional): Dealer classification (franchise, independent) - street, city, state, country (string, optional): Address components - latitude, longitude (string, optional): Geographic coordinates - zip (string, optional): Postal/ZIP code - msa_code (string, optional): Metropolitan Statistical Area code - phone (string, optional): Contact phone number
- include_build_objectboolean
When True, includes build object in response. Build object structure: - year (number): Model year - make (string): Vehicle manufacturer - model (string, optional): Vehicle model - trim (string, optional): Trim level - version (string, optional): Specific version/variant - body_type (string, optional): Body style (sedan, SUV, truck, etc.) - vehicle_type (string, optional): Vehicle category - transmission (string, optional): Transmission type - drivetrain (string, optional): Drivetrain configuration - fuel_type (string, optional): Fuel type (gasoline, electric, hybrid, etc.) - engine (string, optional): Engine description - engine_size (number, optional): Engine displacement - engine_block (string, optional): Engine block configuration - doors (number, optional): Number of doors - cylinders (number, optional): Number of cylinders - made_in (string, optional): Manufacturing country - overall_height, overall_length, overall_width (string, optional): Vehicle dimensions - std_seating (string, optional): Standard seating capacity - highway_mpg (number, optional): Highway fuel economy - city_mpg (number, optional): City fuel economy - powertrain_type (string, optional): Powertrain classification
search_past_90_days
Search for recent car inventory (EXPIRED/SOLD listings from last 90 days) with comprehensive filters following Marketcheck API structure. IMPORTANT: This endpoint serves ONLY expired/sold listings from the last 90 days for US and CA (Canada) markets, NOT active listings. For currently active listings, use the search_active_cars tool instead. DO NOT USE CARFAX FIELDS: Carfax data on this server is incomplete and unreliable. Do NOT pass `carfax_1_owner` or `carfax_clean_title` as filters, do NOT request them in facets/stats, and do NOT infer ownership history, title status, or any other meaning from any `carfax_*` value that might appear in a listing. Treat all Carfax fields as if they did not exist. IMPORTANT: Before filtering by specific field values (make, model, trim, body_type, fuel_type, etc.), use the 'facets' parameter to discover available values in the API. Field values may be represented differently than expected. For example: - Use facets="make,model,trim,body_type" to see all available options - This prevents filtering errors due to incorrect field value assumptions - Facets show actual data distribution and available filter options VIN vs Listing ID Disclaimer: - A single VIN can have multiple listings, each with a unique listing ID - Listing ID changes when there are changes in price or miles of the listing - When expired=false is set, it shows listings for VINs that are currently active in the market (not sold yet), but the specific listing is expired. The latest/current listing for that VIN is present in the active search API - This endpoint shows historical listing data (expired listing IDs) for market analysis, not current inventory This endpoint is designed for analytical use cases including: - Historical market analysis of sold vehicles - Sold vehicle pricing trends and patterns - Days on market analysis for expired listings - Dealer inventory turnover and sales analysis - Market intelligence from recently sold inventory Key use cases: - Analyze recent sales trends and pricing - Get sold/expired listings for market intelligence - Calculate average market prices from recent inventory - Track dealer inventory turnover patterns Due to performance reasons, this endpoint is more restrictive than active search: - Does not accept facets, stats and range_facets in a single call - Requires one of: city, state, zip, (latitude+longitude+radius), source, or dealer_id - For geo queries, radius cannot be greater than 100 miles - Charged at higher rates than active search endpoint STALENESS METRICS — dos_active vs dom_active (read before answering "how long was this car for sale" questions): - dos_active (Days on Site): days the listing was active at the CURRENT dealer. Answers "how long did THIS DEALER try to sell this car." DEFAULT: use dos_active for stale-inventory and "how long was it listed" questions. - dom_active (Days on Market): cumulative days the VEHICLE was actively listed across ALL dealers — it survives dealer-to-dealer transfers. Use ONLY when the question is about the vehicle's total market exposure, e.g. evaluating a car at auction or in a dealer trade: a car showing dos_active=15 at the current store may show dom_active=60 because it was passed around dealers for two months. This rule applies to choosing filter params (dos_active_range vs dom_active_range), sort_by values, and which field to read and report from listing results. When unsure which the user means, default to dos_active.
Parameters (115)
- active_inventory_date_rangeany
Date range to filter listings active within range (YYYYMMDD-YYYYMMDD)
- base_ext_colorany
- base_exterior_colorany
Base exterior color to match (comma-separated values)
- base_int_colorany
- base_interior_colorany
Base interior color to match (comma-separated values)
- exterior_colorany
Exterior color to match (comma-separated values)
- interior_colorany
Interior color to match (comma-separated values)
- body_subtypeany
- body_typeany
Filter listing on their body type
- car_typeany
Car type (new/used/certified)
- cylindersany
Number of engine cylinders (e.g., 4, 6, 8)
- doorsany
Number of doors (e.g., 2, 4)
- drivetrainany
- engineany
- engine_aspirationany
- engine_blockany
- engine_sizeany
- engine_size_rangeany
- fuel_typeany
Filter listing on their fuel type. WARNING: This field has many non-normalized values. First call this tool with facets="fuel_type|0|1000" to discover exact available values before filtering.
- makeany
Filter listings on their make
- modelany
Filter listings on their model
- seating_capacityany
Number of seats (e.g., 5, 7, 8)
- transmissionany
- trimany
Filter listing on their trim
- vehicle_typeany
- versionany
- yearany
Vehicle manufacturing year (e.g., 2020, 2021)
- year_rangeany
Year range in format "min-max" (e.g., "2019-2021")
- carfax_1_ownerany
- carfax_clean_titleany
- cityany
Filter listing on City in which they are listed
- countryany
- latitudeany
Latitude component of location
- longitudeany
Longitude component of location
- msa_codeany
- radiusany
Radius around the search location (Unit - Miles, max 100)
- stateany
Filter listing on State in which they are listed
- zipany
Filter listing on ZIP around which they are listed
- city_mpg_rangeany
- highway_mpg_rangeany
- dom_180_rangeany
- dom_active_rangeany
Cumulative days the VEHICLE was actively listed across ALL dealers (survives dealer transfers) in format "min-max" (e.g., "10-50"). Use for total-market-exposure analysis (auction/trade evaluation); otherwise prefer dos_active_range. See STALENESS METRICS above.
- dom_rangeany
Days on Market range in format "min-max" (e.g., "10-50")
- dos_active_rangeany
Days the listing was active at the CURRENT dealer, in format "min-max" (e.g., "10-50"). Dealer-level staleness — DEFAULT metric for "how long was it for sale" questions. See STALENESS METRICS above.
- first_seen_at_mc_daysany
First seen at MC days range in format "max-min" (e.g., "25-12" for 12 to 25 days ago).
- first_seen_at_mc_rangeany
First seen at MC date range in format YYYYMMDD-YYYYMMDD
- first_seen_at_source_daysany
First seen at source days range in format "max-min" (e.g., "25-12" for 12 to 25 days ago).
- first_seen_at_source_rangeany
First seen at source date range in format YYYYMMDD-YYYYMMDD
- first_seen_daysany
First seen days range in format "max-min" (e.g., "30-10" for 10 to 30 days ago).
- first_seen_rangeany
First seen date range in format YYYYMMDD-YYYYMMDD
- last_seen_daysany
Last seen days range in format "max-min" (e.g., "3-1" for 1 to 3 days ago).
- last_seen_rangeany
Last seen date range in format YYYYMMDD-YYYYMMDD
- dedupany
- exclude_certifiedany
- exclude_dealer_idsany
- exclude_makeany
- exclude_mc_website_idsany
- exclude_sourcesany
- expiredany
Boolean to fetch only expired listings or active ones (True/False)
- finance_down_paymentany
- finance_down_payment_perany
- finance_empany
- finance_loan_aprany
- finance_loan_termany
- include_financeany
- include_leaseany
- lease_down_paymentany
- lease_empany
- lease_termany
- vinany
- vinsany
- taxonomy_vinsany
- matchany
- ymmtany
- dealer_idany
Dealer id to filter the listings
- dealer_nameany
- dealer_typeany
- dealership_group_nameany
- in_transitany
Boolean to filter in transit vehicles (True/False)
- include_non_vin_listingsany
Boolean to include non vin listings (True/False, default False)
- include_relevant_linksany
- mc_categoryany
MarketCheck seller category. Values: "Dealer", "Retailer", "Dealership Group", "Aggregator", "Marketing", "Financing"
- mc_dealer_idany
- mc_dealership_group_idany
- mc_dealership_group_nameany
- mc_location_idany
- mc_rooftop_idany
- mc_sub_dealership_group_idany
- mc_sub_dealership_group_nameany
- mc_website_idany
- nodedupany
- ownedany
Boolean, when True returns listings actually owned by dealer (used with dealer_id/source)
- photo_linksany
- photo_links_cachedany
- plotany
- soldany
Boolean to fetch only sold/expired listings (True/False)
- sourceany
Filter listing on their source
- stock_noany
- vdp_urlany
- price_change_rangeany
- price_rangeany
Price range in format "min-max" (e.g., "1000-5000")
- msrp_rangeany
MSRP range in format "min-max" (e.g., "1000-5000")
- miles_rangeany
Miles range in format "min-max" (e.g., "1000-5000")
- facet_sortany
- facetsany
Field facets return unique terms and their counts for categorical data, useful for building search filters and understanding inventory distribution. Syntax: facets=field_name|offset|limit|min_count (single field only) - offset (default: 0): Start position for terms - limit (default: 20, max: 1000): Number of terms to return - min_count (optional): Minimum count for a term to be included Example: facets=make|0|60|2 returns top 60 makes with at least 2 listings each
- range_facetsany
Numeric field for range facets (single field only)
- statsany
Field for which stats need to be generated (single field only)
- sort_byany
Sort by field (dist|price|miles|msrp|dom|dom_active|dos_active|last_seen|first_seen, etc.). For staleness sorting, default to dos_active (current dealer) over dom_active (all dealers) — see STALENESS METRICS above.
- sort_orderany
Sort order (asc|desc)
- rowsany
Number of results to return (default 5, max 50)
- startany
Page number/offset to fetch results (default 0)
- fetch_all_photosboolean
When False (default), limits photo links to single photo per listing to reduce token usage. When True, returns all photo links.
- include_dealer_objectboolean
When True, includes dealer object in response. Dealer object structure: - id (number): Unique dealer identifier - website (string): Dealer website URL - name (string): Dealer business name - dealer_type (string, optional): Dealer classification (franchise, independent) - street, city, state, country (string, optional): Address components - latitude, longitude (string, optional): Geographic coordinates - zip (string, optional): Postal/ZIP code - phone (string, optional): Contact phone number - seller_email (string, optional): Contact email address - dealership_group_name (string, optional): Parent dealership group - msa_code (string, optional): Metropolitan Statistical Area code
- include_mc_dealership_objectboolean
When True, includes mc_dealership object in response. McDealership object structure: - mc_website_id (number, optional): MarketCheck website identifier - mc_dealer_id (number, optional): MarketCheck dealer identifier - mc_location_id (number, optional): MarketCheck location identifier - mc_rooftop_id (number, optional): MarketCheck rooftop identifier - mc_dealership_group_id (number, optional): MarketCheck dealership group identifier - mc_dealership_group_name (string, optional): MarketCheck dealership group name - mc_sub_dealership_group_id (number, optional): MarketCheck sub-dealership group identifier - mc_sub_dealership_group_name (string, optional): MarketCheck sub-dealership group name - mc_category (string, optional): MarketCheck seller category. Values: "Dealer", "Retailer", "Dealership Group", "Aggregator", "Marketing", "Financing" - website (string, optional): Dealer website URL - name (string, optional): Dealer business name - dealer_type (string, optional): Dealer classification (franchise, independent) - street, city, state, country (string, optional): Address components - latitude, longitude (string, optional): Geographic coordinates - zip (string, optional): Postal/ZIP code - msa_code (string, optional): Metropolitan Statistical Area code - phone (string, optional): Contact phone number
- include_build_objectboolean
When True, includes build object in response. Build object structure: - year (number): Model year - make (string): Vehicle manufacturer - model (string, optional): Vehicle model - trim (string, optional): Trim level - version (string, optional): Specific version/variant - body_type (string, optional): Body style (sedan, SUV, truck, etc.) - vehicle_type (string, optional): Vehicle category - transmission (string, optional): Transmission type - drivetrain (string, optional): Drivetrain configuration - fuel_type (string, optional): Fuel type (gasoline, electric, hybrid, etc.) - engine (string, optional): Engine description - engine_size (number, optional): Engine displacement - engine_block (string, optional): Engine block configuration - doors (number, optional): Number of doors - cylinders (number, optional): Number of cylinders - made_in (string, optional): Manufacturing country - overall_height, overall_length, overall_width (string, optional): Vehicle dimensions - std_seating (string, optional): Standard seating capacity - highway_mpg (number, optional): Highway fuel economy - city_mpg (number, optional): City fuel economy
predict_price_with_comparables
Predict car price along with comparable vehicles in the market. This provides predicted price, MSRP along with active set comparables to help understand market positioning and competitive pricing.
Parameters (7)
- vinstringrequired
Vehicle Identification Number (17 characters, required)
- milesinteger
Miles the vehicle has driven in total (default: 50,000)
- dealer_typestring
Filter based on dealer type (independent or franchise, default: 'franchise')
- zipany
Location ZIP code (default: '50501' - Des Moines, IA)
- cityany
City of the car (optional if zip provided)
- stateany
State of the car (optional if zip provided)
- is_certifiedboolean
Boolean to indicate if car is certified or not (default: False)
get_car_history
Get a car's online listing history by VIN. 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 (4)
- vinstringrequired
Vehicle Identification Number (17 characters, required)
- fieldsany
List of fields to fetch, comma-separated (optional)
- pageany
Page number to fetch results (default is 1, optional)
- sort_orderany
Sort order - asc or desc (default is asc, optional)
decode_vin_neovin
Get vehicle specifications from NeoVIN decoder by VIN. Get the basic information on specifications for a car identified by a valid VIN from NeoVIN decoder. This provides detailed vehicle specifications including trim, engine, transmission, features, options, MSRP information, and more comprehensive data than standard VIN decoders.
Parameters (2)
- vinstringrequired
Vehicle Identification Number (17 characters, required)
- include_genericany
Boolean to include generic data in response (optional, default: False)
get_server_info
Get information about the server. Returns: Server capabilities as a dict (serialized by the transport layer)
No parameters.
search_uk_active_cars
Search for active cars in the UK market. This tool searches for currently active car listings in the UK using the Marketcheck API. It supports comprehensive filtering by location, vehicle specifications, price, and more. Includes all parameters supported by the /search/car/uk/active endpoint. DO NOT USE CARFAX FIELDS: Carfax data on this server is incomplete and unreliable. Do NOT pass `carfax_1_owner` or `carfax_clean_title` (via kwargs or otherwise) as filters, do NOT request them in facets/stats, and do NOT infer ownership history, title status, or any other meaning from any `carfax_*` value that might appear in a listing. Treat all Carfax fields as if they did not exist. IMPORTANT: Before filtering by specific field values (make, model, trim, body_type, fuel_type, etc.), use the 'facets' parameter to discover available values in the API. Field values may be represented differently than expected. For example: - Use facets="make,model,trim,body_type" to see all available options - This prevents filtering errors due to incorrect field value assumptions - Facets show actual data distribution and available filter options STALENESS METRICS — dos_active vs dom_active (read before answering "how long has this car been for sale" questions): - dos_active (Days on Site): days this listing has been active at the CURRENT dealer. Answers "how long has THIS DEALER been trying to sell this car." DEFAULT: use dos_active for stale-inventory and "how long has it been listed" questions. - dom_active (Days on Market): cumulative days the VEHICLE has been actively listed for sale across ALL dealers — it survives dealer-to-dealer transfers. Use ONLY when the question is about the vehicle's total market exposure, e.g. evaluating a car at auction or in a dealer trade: a car showing dos_active=15 at the current store may show dom_active=60 because it has been passed around dealers for two months. This rule applies to choosing filter params (dos_active_range vs dom_active_range), sort_by values, and which field to read and report from listing results. When unsure which the user means, default to dos_active.
Parameters (124)
- latitudeany
Latitude component of location (range: -90 to 90).
- longitudeany
Longitude component of location (range: -180 to 180).
- radiusany
Radius around the search location in miles (max: 7000).
- postal_codeany
To filter listing on postal code around which they are listed.
- zipany
To filter listing on ZIP around which they are listed.
- cityany
To filter listing on City in which they are listed.
- countyany
To filter listing on county in which they are listed.
- stateany
To filter listing on State in which they are listed.
- car_typeany
Car type. Allowed values are - new / used.
- yearany
To filter listing on their year (comma-separated values).
- year_rangeany
Year range to filter listings (format: min-max e.g. 2019-2021).
- makeany
To filter listings on their make (comma-separated values).
- modelany
To filter listings on their model (comma-separated values).
- variantany
To filter listing on their variant (comma-separated values).
- trimany
To filter listing on their trim (comma-separated values).
- body_typeany
To filter listing on their body type (comma-separated values).
- ymmtany
Comma separated list of Year, Make, Model, Trim combinations.
- transmissionany
To filter listing on their transmission (comma-separated values).
- doorsany
Doors to filter the cars on (comma-separated integer values).
- drivetrainany
To filter listing on their drivetrain (comma-separated values).
- engineany
To filter listing on their engine (comma-separated values).
- fuel_typeany
To filter listing on their fuel type (comma-separated values).
- cylindersany
To filter listing on their cylinders (comma-separated values).
- exterior_colorany
Exterior color to match (comma-separated values from facets API).
- interior_colorany
Interior color to match (comma-separated values from facets API).
- base_exterior_colorany
Base exterior color to match (comma-separated values).
- base_interior_colorany
Base interior color to match (comma-separated values).
- base_ext_colorany
Base exterior color to match (alias for base_exterior_color).
- base_int_colorany
Base interior color to match (alias for base_interior_color).
- miles_rangeany
Miles range to filter listings (format: min-max e.g. 1000-5000).
- price_rangeany
Price range to filter listings (format: min-max e.g. 1000-5000).
- msrp_rangeany
MSRP range to filter listings (format: min-max e.g. 1000-5000).
- price_changeany
Price change filter for listings.
- price_change_rangeany
Price change range to filter listings.
- sort_byany
Sort by field. Default sort field is distance from the given point. For staleness sorting, default to dos_active (current dealer) over dom_active (all dealers) — see STALENESS METRICS above.
- sort_orderany
Sort order - asc or desc. Default sort order is asc.
- rowsany
Number of results to return. Default is 10. Max is 50.
- startany
Page number to fetch results. Default is 0. Max pagination: 10000.
- facetsany
Field facets return unique terms and their counts for categorical data, useful for building search filters and understanding inventory distribution. Syntax: facets=field_name|offset|limit|min_count - offset (default: 0): Start position for terms - limit (default: 20, max: 1000): Number of terms to return - min_count (optional): Minimum count for a term to be included Example: facets=make|0|60|2 returns top 60 makes with at least 2 listings each
- range_facetsany
Comma separated list of numeric fields for range facets.
- facet_sortany
Controls sort order of facet terms: - count (default): Sort by frequency (highest first) - index: Sort alphabetically
- statsany
List of fields for which stats need to be generated.
- countryany
To filter listing on Country (uk, england, scotland, northern ireland, wales).
- plotany
If true, results in around 25k coordinates with limited fields to plot.
- nodedupany
If true, API will give results without is_searchable.
- dedupany
If true, will give results with is_searchable irrespective of dealer.
- co2_emissionsany
CO2 emissions filter (comma-separated values).
- insurance_groupany
Insurance group filter for UK vehicles.
- vehicle_registration_markany
Vehicle Registration Mark filter.
- vehicle_registration_date_rangeany
Vehicle registration date range (YYYYMMDD-YYYYMMDD).
- num_ownersany
Number of owners filter.
- fca_statusany
To filter on fca status.
- seating_capacityany
To filter on vehicle seating capacity.
- vrmany
Vehicle Registration Mark (VRM) filter.
- write_off_categoryany
Write off category filter.
- exclude_write_off_categoryany
To exclude write off category.
- ulez_compliantany
Filter for ULEZ compliant vehicles.
- sourceany
To filter listing on their source (comma-separated URLs).
- dealer_idany
Dealer id to filter the listings.
- exclude_sourcesany
A list of sources to exclude from result.
- exclude_dealer_idsany
A list of dealer ids to exclude from result.
- exclude_mc_website_idsany
A list of MC website ids to exclude from result.
- dealer_typeany
Filter based on dealer type (franchise or independent).
- mc_website_idany
Website id to filter the listings.
- mc_dealer_idany
To filter listings on their mc_dealer_id.
- mc_location_idany
To filter listings on their mc_location_id.
- mc_rooftop_idany
To filter listings on their mc_rooftop_id.
- mc_dealership_group_idany
To filter listings on their mc_dealership_group_id.
- mc_dealership_group_nameany
To filter listings on their mc_dealership_group_name.
- mc_sub_dealership_group_idany
To filter listings on their mc_sub_dealership_group_id.
- mc_sub_dealership_group_nameany
To filter listings on their mc_sub_dealership_group_name.
- mc_categoryany
Filter based on mc_category (Dealer, Dealership Group, etc.).
- stock_noany
To filter listing on their stock number on lot.
- inventory_count_rangeany
Inventory count range to filter listings (min-max format).
- include_non_vin_listingsany
To include non vin listings. Default is false.
- dom_rangeany
Days on Market range to filter cars (format: min-max e.g. 10-50).
- dom_active_rangeany
Cumulative days the VEHICLE has been actively listed across ALL dealers (survives dealer transfers), format min-max. Use for total-market-exposure analysis; otherwise prefer dos_active_range. See STALENESS METRICS above.
- dom_180_rangeany
Last 180 Days on Market range to filter cars.
- dos_active_rangeany
Days the listing has been active at the CURRENT dealer, format min-max. Dealer-level staleness — DEFAULT metric for "how long has it been for sale" questions. See STALENESS METRICS above.
- last_seen_rangeany
Last seen date range (YYYYMMDD-YYYYMMDD format).
- first_seen_rangeany
First seen date range (YYYYMMDD-YYYYMMDD format).
- first_seen_at_source_rangeany
First seen at source date range.
- first_seen_at_mc_rangeany
First seen at MC date range.
- last_seen_daysany
Last seen days range in format "max-min" (e.g., "3-1" for 1 to 3 days ago).
- first_seen_daysany
First seen days range in format "max-min" (e.g., "30-10" for 10 to 30 days ago).
- first_seen_at_source_daysany
First seen at source days range in format "max-min" (e.g., "15-5").
- first_seen_at_mc_daysany
First seen at MC days range in format "max-min" (e.g., "15-5").
- active_inventory_date_rangeany
Active inventory date range filter.
- photo_linksany
Boolean to include only listings that have photo_links.
- photo_links_cachedany
Boolean to include only listings with cached photo_links.
- min_photo_linksany
Minimum number of photo links required.
- min_photo_links_cachedany
Minimum number of cached photo links required.
- vdp_urlany
Vehicle details page URL filter.
- engine_sizeany
Engine Size to match (comma-separated values from facets API).
- engine_size_rangeany
Engine size range filter.
- highway_mpg_rangeany
Highway mileage range (min-max format e.g. 1000-5000).
- city_mpg_rangeany
City mileage range (min-max format e.g. 1000-5000).
- combined_mpg_rangeany
Combined mileage range for UK (min-max format).
- performance_co2_rangeany
Performance CO2 range filter.
- ev_battery_typeany
Electric vehicle battery type filter.
- ev_battery_capacity_rangeany
EV battery capacity range filter.
- ev_vehicle_rangeany
Electric vehicle range filter.
- car_location_seller_nameany
Car location seller name filter.
- car_location_streetany
Car location street filter.
- car_location_cityany
Car location city filter.
- car_location_countyany
Car location county filter.
- car_location_zipany
Car location ZIP filter.
- car_location_latitudeany
Car location latitude coordinate.
- car_location_longitudeany
Car location longitude coordinate.
- exclude_makeany
Make values to exclude from results.
- preferred_dealersany
Preferred dealers filter.
- include_preferred_dealer_flagany
Include preferred dealer flag.
- preferred_dealers_onlyany
Filter to show only preferred dealers.
- model_variantany
Model variant filter.
- is_vat_includedany
Boolean filter for VAT inclusion.
- uvc_idany
UVC (Universal Vehicle Code) ID filter.
- ownedany
When used with dealer_id, returns listings owned by dealer.
- matchany
Comma separated list of fields for exact match.
- vehicle_typeany
To filter listing on their vehicle type.
- wheelbase_categoryany
To filter listing on their wheelbase category.
- fetch_all_photosboolean
When False (default), limits photo links to single photo per listing to reduce token usage. When True, returns all photo links.
- include_dealer_objectboolean
When True, includes dealer object in response. Dealer object structure: - id (number): Unique dealer identifier - website (string): Dealer website URL - name (string): Dealer business name - dealer_type (string, optional): Dealer classification (franchise, independent) - street, city, county, country (string, optional): Address components - latitude, longitude (string, optional): Geographic coordinates - postal_code (string, optional): UK postal code - phone (string, optional): Contact phone number - seller_email (string, optional): Contact email address - fca_status (string, optional): FCA authorization status - preferred_dealer (boolean, optional): Flag indicating if this is a preferred dealer
- include_mc_dealership_objectboolean
When True, includes mc_dealership object in response. McDealership object structure: - mc_website_id (number, optional): MarketCheck website identifier - mc_dealer_id (number, optional): MarketCheck dealer identifier - mc_location_id (number, optional): MarketCheck location identifier - mc_rooftop_id (number, optional): MarketCheck rooftop identifier - mc_dealership_group_id (number, optional): MarketCheck dealership group identifier - mc_dealership_group_name (string, optional): MarketCheck dealership group name - mc_sub_dealership_group_id (number, optional): MarketCheck sub-dealership group identifier - mc_sub_dealership_group_name (string, optional): MarketCheck sub-dealership group name - mc_category (string, optional): MarketCheck seller category. UK market only supports: dealer - website (string, optional): Dealer website URL - name (string, optional): Dealer business name - dealer_type (string, optional): Dealer classification (franchise, independent) - street, city, county, country (string, optional): Address components - latitude, longitude (string, optional): Geographic coordinates - postal_code (string, optional): UK postal code - phone (string, optional): Contact phone number - fca_status (string, optional): FCA authorization status
- include_build_objectboolean
When True, includes build object in response. Build object structure: - year (number): Model year - make (string): Vehicle manufacturer - model (string, optional): Vehicle model - model_variant (string, optional): Vehicle model variant - trim (string, optional): Trim level - variant (string, optional): Specific variant identifier - body_type (string, optional): Body style (saloon, hatchback, estate, etc.) - vehicle_type (string, optional): Vehicle category - transmission (string, optional): Transmission type - drivetrain (string, optional): Drivetrain configuration - fuel_type (string, optional): Fuel type (petrol, diesel, electric, hybrid, etc.) - engine (string, optional): Engine description - engine_size (number, optional): Engine displacement - doors (number, optional): Number of doors - cylinders (number, optional): Number of cylinders - made_in (string, optional): Manufacturing country - overall_height, overall_length, overall_width (string, optional): Vehicle dimensions - wheelbase_category (string, optional): Wheelbase classification - std_seating (string, optional): Standard seating capacity - highway_mpg (number, optional): Highway fuel economy - city_mpg (number, optional): City fuel economy - combined_mpg (number, optional): Combined fuel economy - seating_capacity (number, optional): Passenger seating capacity - performance_torque_ftlb (number, optional): Torque in foot-pounds - performance_maxspeed_mph (number, optional): Maximum speed in miles per hour - performance_torque_rpm (number, optional): Torque at RPM - performance_power_bhp (number, optional): Power in brake horsepower - performance_power_rpm (number, optional): Power at RPM - performance_torque_nm (number, optional): Torque in Newton-meters - performance_power_kw (number, optional): Power in kilowatts - performance_co2 (number, optional): CO2 emissions rating - euro_status (number, optional): Euro emissions standard status
search_uk_recent_cars
Search for recent/expired cars in the UK market (last 90 days). This tool searches recent inventory data for EXPIRED/SOLD listings only. It does NOT include active listings - use search_uk_active_cars for current inventory. DO NOT USE CARFAX FIELDS: Carfax data on this server is incomplete and unreliable. Do NOT pass `carfax_1_owner` or `carfax_clean_title` (via kwargs or otherwise) as filters, do NOT request them in facets/stats, and do NOT infer ownership history, title status, or any other meaning from any `carfax_*` value that might appear in a listing. Treat all Carfax fields as if they did not exist. IMPORTANT: Before filtering by specific field values (make, model, trim, body_type, fuel_type, etc.), use the 'facets' parameter to discover available values in the API. Field values may be represented differently than expected. For example: - Use facets="make,model,trim,body_type" to see all available options - This prevents filtering errors due to incorrect field value assumptions - Facets show actual data distribution and available filter options STALENESS METRICS — dos_active vs dom_active (read before answering "how long was this car for sale" questions): - dos_active (Days on Site): days the listing was active at the CURRENT dealer. Answers "how long did THIS DEALER try to sell this car." DEFAULT: use dos_active for stale-inventory and "how long was it listed" questions. - dom_active (Days on Market): cumulative days the VEHICLE was actively listed across ALL dealers — it survives dealer-to-dealer transfers. Use ONLY when the question is about the vehicle's total market exposure, e.g. evaluating a car at auction or in a dealer trade: a car showing dos_active=15 at the current store may show dom_active=60 because it was passed around dealers for two months. This rule applies to choosing filter params (dos_active_range vs dom_active_range), sort_by values, and which field to read and report from listing results. When unsure which the user means, default to dos_active.
Parameters (121)
- latitudeany
Latitude component of location (range: -90 to 90).
- longitudeany
Longitude component of location (range: -180 to 180).
- radiusany
Radius around the search location in miles (max: 100 for recent search).
- zipany
To filter listing on ZIP around which they are listed.
- postal_codeany
To filter listing on postal code around which they are listed.
- cityany
To filter listing on City in which they are listed.
- countyany
To filter listing on county in which they are listed.
- stateany
To filter listing on State in which they are listed.
- car_include_leaseany
Boolean param to search for listings that include leasing options.
- car_include_financeany
Boolean param to search for listings that include finance options.
- lease_termany
Search listings with exact lease term, or range (min-max e.g. 30-60).
- lease_down_paymentany
Search listings with exact down payment in lease offers or range.
- lease_empany
Search listings with lease Estimated Monthly Payment (EMI) or range.
- finance_loan_termany
Search listings with exact finance loan term or range.
- finance_loan_aprany
Search listings with finance Annual Percentage Rate or range.
- finance_empany
Search listings with finance Estimated Monthly Payment (EMI) or range.
- finance_down_paymentany
Search listings with exact down payment in finance offers or range.
- finance_down_payment_perany
Search listings with exact down payment percentage or range.
- car_typeany
Car type. Allowed values are - new / used / certified.
- year_rangeany
Year range to filter listings (format: min-max e.g. 2019-2021).
- yearany
To filter listing on their year (comma-separated values).
- makeany
To filter listings on their make (comma-separated values).
- modelany
To filter listings on their model (comma-separated values).
- trimany
To filter listing on their trim (comma-separated values).
- variantany
To filter listing on their variant (comma-separated values).
- body_typeany
To filter listing on their body type (comma-separated values).
- body_subtypeany
Body subtype to filter listings (comma-separated values from facets API).
- vehicle_typeany
To filter listing on their vehicle type (comma-separated values).
- wheelbase_categoryany
To filter listing on their wheelbase category.
- ymmtany
Comma separated list of Year, Make, Model, Trim combinations.
- matchany
Comma separated list of fields for exact match (e.g., year,make,model,trim).
- cylindersany
To filter listing on their cylinders (comma-separated values).
- transmissionany
To filter listing on their transmission (comma-separated values).
- doorsany
Doors to filter the cars on (comma-separated integer values).
- drivetrainany
To filter listing on their drivetrain (comma-separated values).
- engineany
To filter listing on their engine (comma-separated values).
- engine_sizeany
Engine Size to match (comma-separated values from facets API).
- engine_size_rangeany
Engine size range filter (min-max format).
- engine_aspirationany
Engine Aspiration to match (comma-separated values from facets).
- engine_blockany
Engine Block to match (comma-separated values from facets).
- fuel_typeany
To filter listing on their fuel type (comma-separated values).
- exterior_colorany
Exterior color to match (comma-separated values from facets API).
- interior_colorany
Interior color to match (comma-separated values from facets API).
- base_exterior_colorany
Base exterior color to match (comma-separated values).
- base_interior_colorany
Base interior color to match (comma-separated values).
- base_ext_colorany
Base exterior color to match (alias for base_exterior_color).
- base_int_colorany
Base interior color to match (alias for base_interior_color).
- miles_rangeany
Miles range to filter listings (format: min-max e.g. 1000-5000).
- price_rangeany
Price range to filter listings (format: min-max e.g. 1000-5000).
- msrp_rangeany
MSRP range to filter listings (format: min-max e.g. 1000-5000).
- price_change_rangeany
Price change range to filter listings.
- highway_mpg_rangeany
Highway mileage range for UK (min-max format e.g. 1000-5000).
- city_mpg_rangeany
City mileage range for UK (min-max format e.g. 1000-5000).
- combined_mpg_rangeany
Combined mileage range for UK (min-max format).
- ulez_compliantany
Filter for ULEZ compliant vehicles.
- dom_rangeany
Days on Market range to filter cars (format: min-max e.g. 10-50).
- dom_active_rangeany
Cumulative days the VEHICLE was actively listed across ALL dealers (survives dealer transfers), format min-max. Use for total-market-exposure analysis; otherwise prefer dos_active_range. See STALENESS METRICS above.
- dom_180_rangeany
Last 180 Days on Market range to filter cars.
- dos_active_rangeany
Days the listing was active at the CURRENT dealer, format min-max. Dealer-level staleness — DEFAULT metric for "how long was it for sale" questions. See STALENESS METRICS above.
- last_seen_rangeany
Last seen date range (YYYYMMDD-YYYYMMDD format).
- first_seen_rangeany
First seen date range (YYYYMMDD-YYYYMMDD format).
- first_seen_at_source_rangeany
First seen at source date range.
- first_seen_at_mc_rangeany
First seen at MC date range.
- last_seen_daysany
Last seen days range in format "max-min" (e.g., "3-1" for 1 to 3 days ago).
- first_seen_daysany
First seen days range in format "max-min" (e.g., "30-10" for 10 to 30 days ago).
- first_seen_at_source_daysany
First seen at source days range in format "max-min" (e.g., "15-5").
- first_seen_at_mc_daysany
First seen at MC days range in format "max-min" (e.g., "15-5").
- active_inventory_date_rangeany
Active inventory date range filter.
- dealer_idany
Dealer id to filter the listings.
- dealer_nameany
Filter listings on dealer_name.
- dealer_typeany
Filter based on dealer type (franchise or independent).
- dealership_group_nameany
Name of the dealership group to search for.
- sourceany
To filter listing on their source (comma-separated URLs).
- exclude_dealer_idsany
A list of dealer ids to exclude from result.
- exclude_mc_website_idsany
A list of MC website ids to exclude from result.
- exclude_sourcesany
A list of sources to exclude from result.
- mc_website_idany
Website id to filter the listings.
- mc_dealer_idany
To filter listings on their mc_dealer_id.
- mc_location_idany
To filter listings on their mc_location_id.
- mc_rooftop_idany
To filter listings on their mc_rooftop_id.
- mc_dealership_group_idany
To filter listings on their mc_dealership_group_id.
- mc_dealership_group_nameany
To filter listings on their mc_dealership_group_name.
- mc_sub_dealership_group_idany
To filter listings on their mc_sub_dealership_group_id.
- mc_sub_dealership_group_nameany
To filter listings on their mc_sub_dealership_group_name.
- mc_categoryany
Filter based on mc_category (Dealer, Dealership Group, etc.).
- insurance_groupany
Insurance group filter for UK vehicles.
- vrmany
Vehicle Registration Mark (VRM) filter.
- num_ownersany
Number of owners filter.
- write_off_categoryany
Write off category filter.
- exclude_write_off_categoryany
To exclude write off category.
- fca_statusany
To filter on fca status.
- seating_capacityany
To filter on vehicle seating capacity.
- sort_byany
Sort by field. Default sort field is distance from the given point. For staleness sorting, default to dos_active (current dealer) over dom_active (all dealers) — see STALENESS METRICS above.
- sort_orderany
Sort order - asc or desc. Default sort order is asc.
- rowsany
Number of results to return. Default is 10. Max is 50.
- startany
Page number to fetch results. Default is 0. Max pagination: 10000.
- include_non_vin_listingsany
To include non vin listings. Default is false.
- facetsany
Field facets return unique terms and their counts for categorical data, useful for building search filters and understanding inventory distribution. Syntax: facets=field_name|offset|limit|min_count - offset (default: 0): Start position for terms - limit (default: 20, max: 1000): Number of terms to return - min_count (optional): Minimum count for a term to be included Example: facets=make|0|60|2 returns top 60 makes with at least 2 listings each
- range_facetsany
Comma separated list of numeric fields for range facets.
- facet_sortany
Controls sort order of facet terms: - count (default): Sort by frequency (highest first) - index: Sort alphabetically
- statsany
List of fields for which stats need to be generated.
- countryany
To filter listing on Country (uk, england, scotland, northern ireland, wales).
- plotany
If true, results in around 25k coordinates with limited fields to plot.
- nodedupany
If true, API will give results without is_searchable.
- dedupany
If true, will give results with is_searchable irrespective of dealer.
- ownedany
When used with dealer_id, returns listings owned by dealer.
- exclude_certifiedany
Boolean param to exclude certified cars from search results.
- photo_linksany
Boolean to include only listings that have photo_links.
- photo_links_cachedany
Boolean to include only listings with cached photo_links.
- stock_noany
To filter listing on their stock number on lot.
- soldany
Boolean parameter to fetch only sold listings.
- include_relevant_linksany
To include_relevant_links. Default is true.
- expiredany
Boolean flag to either fetch only the expired listings or active ones.
- exclude_makeany
Make values to exclude from results.
- model_variantany
Model variant filter.
- is_vat_includedany
Boolean filter for VAT inclusion.
- vdp_urlany
Vehicle details page URL filter.
- fetch_all_photosboolean
When False (default), limits photo links to single photo per listing to reduce token usage. When True, returns all photo links.
- include_dealer_objectboolean
When True, includes dealer object in response. Dealer object structure: - id (number): Unique dealer identifier - website (string): Dealer website URL - name (string): Dealer business name - dealer_type (string, optional): Dealer classification (franchise, independent) - street, city, county, country (string, optional): Address components - latitude, longitude (string, optional): Geographic coordinates - postal_code (string, optional): UK postal code - phone (string, optional): Contact phone number - seller_email (string, optional): Contact email address - fca_status (string, optional): FCA authorization status - preferred_dealer (boolean, optional): Flag indicating if this is a preferred dealer
- include_mc_dealership_objectboolean
When True, includes mc_dealership object in response. McDealership object structure: - mc_website_id (number, optional): MarketCheck website identifier - mc_dealer_id (number, optional): MarketCheck dealer identifier - mc_location_id (number, optional): MarketCheck location identifier - mc_rooftop_id (number, optional): MarketCheck rooftop identifier - mc_dealership_group_id (number, optional): MarketCheck dealership group identifier - mc_dealership_group_name (string, optional): MarketCheck dealership group name - mc_sub_dealership_group_id (number, optional): MarketCheck sub-dealership group identifier - mc_sub_dealership_group_name (string, optional): MarketCheck sub-dealership group name - mc_category (string, optional): MarketCheck seller category. UK market only supports: dealer - website (string, optional): Dealer website URL - name (string, optional): Dealer business name - dealer_type (string, optional): Dealer classification (franchise, independent) - street, city, county, country (string, optional): Address components - latitude, longitude (string, optional): Geographic coordinates - postal_code (string, optional): UK postal code - phone (string, optional): Contact phone number - fca_status (string, optional): FCA authorization status
- include_build_objectboolean
When True, includes build object in response. Build object structure: - year (number): Model year - make (string): Vehicle manufacturer - model (string, optional): Vehicle model - model_variant (string, optional): Vehicle model variant - trim (string, optional): Trim level - variant (string, optional): Specific variant identifier - body_type (string, optional): Body style (saloon, hatchback, estate, etc.) - vehicle_type (string, optional): Vehicle category - transmission (string, optional): Transmission type - drivetrain (string, optional): Drivetrain configuration - fuel_type (string, optional): Fuel type (petrol, diesel, electric, hybrid, etc.) - engine (string, optional): Engine description - engine_size (number, optional): Engine displacement - doors (number, optional): Number of doors - cylinders (number, optional): Number of cylinders - made_in (string, optional): Manufacturing country - overall_height, overall_length, overall_width (string, optional): Vehicle dimensions - wheelbase_category (string, optional): Wheelbase classification - std_seating (string, optional): Standard seating capacity - highway_mpg (number, optional): Highway fuel economy - city_mpg (number, optional): City fuel economy - combined_mpg (number, optional): Combined fuel economy - seating_capacity (number, optional): Passenger seating capacity - performance_torque_ftlb (number, optional): Torque in foot-pounds - performance_maxspeed_mph (number, optional): Maximum speed in miles per hour - performance_torque_rpm (number, optional): Torque at RPM - performance_power_bhp (number, optional): Power in brake horsepower - performance_power_rpm (number, optional): Power at RPM - performance_torque_nm (number, optional): Torque in Newton-meters - performance_power_kw (number, optional): Power in kilowatts - performance_co2 (number, optional): CO2 emissions rating - euro_status (number, optional): Euro emissions standard status
get_sold_summary
Get comprehensive sold vehicle summary with advanced filtering, ranking, and grouping capabilities for US market only. This provides historical sales data (up to 5 years) for sold vehicles in the United States. Time period: - date_from: Start date for summary period, should be in YYYY-MM-DD format and first day of the month - date_to: End date for summary period, should be in YYYY-MM-DD format and last day of the month Basic filters: - inventory_type: Filter by inventory type (New, Used), defaults to New - dealer_type: Filter by dealer type (Franchise, Independent) - state: Filter by US state, should be a valid 2-letter state code (e.g., CA, TX, NY, etc.) Vehicle filters: - make: Filter by car make (e.g., Toyota, Ford, etc.) - model: Filter by car model (e.g., F-150, Corolla, etc.) - body_type: Filter by car body type (e.g., SUV, Sedan, Pickup, Hatchback, etc.) - fuel_type_category: Filter by fuel type category (ICE, EV, Hybrid, Unknown, Other) Dealership filters: - dealership_group_name: Filter by dealership group name (e.g., Lithia Motors Inc., etc.) Ranking and grouping: - top_n: Limit the number of results returned per group, must be greater than or equal to 1 - ranking_dimensions: Group results by summary for selected fields (comma separated). VALID VALUES ONLY: 'make', 'model', 'body_type', 'dealership_group_name' - ranking_measure: Measure to rank by (sold_count, average_sale_price, total_sale_price, average_days_on_market) - ranking_order: Order of ranking (asc, desc), defaults to desc - summary_by: Group results by state or city_state Pagination: - limit: Maximum number of results to return, must be greater than or equal to 1, Max is 5000 Advanced filters (use operators like >, <, >=, <=, = followed by a number): - sold_count: Filter by sold count (e.g., ">100", "<=50") - average_sale_price: Filter by average sale price (e.g., ">20000", "<=15000.50") - total_sale_price: Filter by total sale price (e.g., ">500000", "<=300000.75") - average_days_on_market: Filter by average days on market (e.g., ">30", "<=60") - price_over_msrp_percentage: Filter by price over MSRP percentage (e.g., ">5", "<=0") Returns: JSON string with sold vehicle summary results including sold count, average sale price, total sale price, price range, standard deviation, price over MSRP percentage, average MSRP, average days on market, and median days on market
Parameters (21)
- date_fromany
- date_toany
- inventory_typeany
- dealer_typeany
- stateany
- makeany
- modelany
- body_typeany
- fuel_type_categoryany
- dealership_group_nameany
- top_nany
- ranking_dimensionsany
- ranking_measureany
- ranking_orderany
- summary_byany
- limitany
- sold_countany
- average_sale_priceany
- total_sale_priceany
- average_days_on_marketany
- price_over_msrp_percentageany
README not available yet.
Install
claude_desktop_config.json
{
"mcpServers": {
"api": {
"command": "npx",
"args": [
"-y",
"mcp-remote",
"https://developers.marketcheck.com/api/mcp"
]
}
}
}Desktop config is stdio-only; this bridges via mcp-remote. Native remote: Settings > Connectors.