search_active_cars

com.marketcheck/api · Verify this server

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.