Inventory Search

The Inventory Search API provides near-real-time access to one of the largest active dealer inventories in the U.S. and Canada, refreshed daily. Its rich filtering, sorting, and analytics capabilities let dealers, lenders, and analysts search current stock and derive market insights quickly.

Overview

• Access a comprehensive inventory of more than 6 million unique vehicles—deduplicated (Understanding Attribution) from over 16 million active dealer listings across the U.S. and Canada.
• All listings have seller_type set to dealer, ensuring completeness and reliability for dealer-focused searches.
• Data updates published daily on or before 11 AM UTC

Units & Conventions:

Base Path

GET https://api.marketcheck.com/v2/search/car/active

The following example demonstrates a basic search request with common parameters:

import axios from 'axios';

const options = {
  method: 'GET',
  url: 'https://api.marketcheck.com/v2/search/car/active',
  params: {
    api_key: 'YOUR_API_KEY',
    year: '2024',
    make: 'ford',
    model: 'f-150',
    start: '0',
    rows: '5',
    facets: 'trim',
    stats: 'price'
  },
  headers: {Accept: 'application/json'}
};

try {
  const { data } = await axios.request(options);
  console.log(data);
} catch (error) {
  console.error(error);
}

Explore the full range of parameters available for filtering, sorting, and configuring search results in the Parameters section below.

Request

The Inventory Search API provides extensive filtering and search capabilities for automotive inventory listings. You can search by vehicle specifications, geographic location, pricing ranges, dealer types, and numerous other criteria to find the exact vehicles you need.

Parameters

Available parameters for filtering, sorting, and configuring search results:

Defaults

• country: Defaults to us for United States market
  • When searching Canadian data, explicitly pass country=ca in each call
  • To search both US and Canadian data, use country=all
• dedup: Defaults to true - only Attributed (Searchable) listings appear in responses
  • Only one listing per VIN is returned, removing duplicates from the dataset
  • use nodedup=true to include all listings, even duplicates

Pagination

API response includes num_found property indicating the total number of listings matching the search criteria. By default, the API returns the first page of results with 10 listings per page.

You can use start and rows parameters to iterate through search results efficiently.

Parameters:

• start - Offset from which listings are returned (starts at 0)
• rows - Number of listings per page (maximum 50, default 10)

Increment start proportionally to rows value for consistent pagination:

• start=0&rows=50 - fetches listings 1-50
• start=50&rows=50 - fetches listings 51-100
• start=100&rows=50 - fetches listings 101-150

Limits:

• The rows parameter accepts a maximum value of 50 (default is 10)
  • If you specify rows greater than 50, the API will automatically use the default value of 10
  • If you're on last page of results, the API will return remaining listings, which may be fewer than the requested rows
• Your subscription package limits the total number of results you can paginate through; exceeding this limit returns an error.
• If the sum of start and rows exceeds your subscription's pagination limit, or if start is greater than the total number of available results (num_found), the API will respond with a HTTP 422 error status.

Sorting

The Search API allows sorting results by a single numeric or date field at a time. Sorting by multiple fields simultaneously is not supported.

Sort Parameters:

• sort_by - Field name to sort by
• sort_order - Sort direction (asc or desc)

Default Behavior:

• With location: sorts by distance (nearest first)
• Without location: sorts by last_seen (desc) and vin (asc)

Common Sort Fields

Below are the most commonly used sort fields. For a complete list, see the next table.

All Available Sort Fields

Facets

The Search API supports facets for building UI filters and analyzing inventory distribution. Use facets to get unique value counts for categorical fields and range-based counts for numeric fields.

Field Facets

Field facets return unique terms and their counts for categorical data, useful for building search filters and understanding inventory distribution.

Parameters and Syntax

• facets — Comma-separated list of field names to facet on. Supports pagination and minimum count:
  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
• facet_sort — Controls sort order of facet terms:
  • count (default): Sort by frequency (highest first)
  • index: Sort alphabetically

Example

import axios from 'axios';

const options = {
  method: 'GET',
  url: 'https://api.marketcheck.com/v2/search/car/active',
  params: {
    api_key: 'YOUR_API_KEY',
    year: '2024',
    make: 'ford',
    model: 'f-150',
    rows: '0',
    facets: 'trim|0|100|0,city|0|100|100'
  },
  headers: {Accept: 'application/json'}
};

try {
  const { data } = await axios.request(options);
  console.log(data);
} catch (error) {
  console.error(error);
}

Response

• Facets are returned in the facets field of the response, structured as key-value pairs
• Keys are field names and values are arrays of objects with item and count properties
  • item is the unique term
  • count is the number of listings for that term.

{
"facets": {
    "make": [
    { "item": "Toyota", "count": 12345 },
    { "item": "Honda", "count": 6789 },
    ...
    ],
    "city": [
    { "item": "Los Angeles", "count": 1000 },
    { "item": "New York", "count": 800 },
    ...
    ]
}
}

If requested field is not allowed for faceting, it will be included in the response but with an error message indicating the field is not supported for facets.

{
  "facets": {
    "xyz": [
      {
        "result": "Error",
        "message": "Field xyz is not allowed in facets"
      }
    ]
  }
}

Available Field Facets

Facet Pagination

By default, facets return the top 20 terms for each field. You can control pagination using positional parameters offset, limit:

• offset - Starting position for terms (default: 0)
• limit - Maximum number of terms to return (default: 20, max: 1000)

Example: facets=make|20|20 returns makes 21-40

Facets Sorting

Facet terms can be sorted by count or alphabetically using the facet_sort parameter:

• count (default) - Sort by frequency (highest first)
• index - Sort alphabetically

Example: facets=make|0|20&facet_sort=index returns makes sorted alphabetically

Range Facets

Range facets provide statistical distribution analysis for numeric fields, creating buckets for data visualization and market insights.

Parameters and Syntax

• range_facets — Comma-separated list of field names to facet on, with optional range and interval:
  range_facets=field_name|start|end|interval
  • start (optional): Lower bound of the range (default varies by field)
  • end (optional): Upper bound of the range (default varies by field)
  • interval (optional): Size of each bucket (default: (end - start)/20)
  • Example: range_facets=price|500|20000|1000 returns price ranges with 1000 intervals between 500 and 20000.
• If start is specified but end is not, the API adds the default end value for that field to the start value.
• Value of interval has to be greater than (end - start)/200, otherwise the API will return an error.

Example

import axios from 'axios';

const options = {
  method: 'GET',
  url: 'https://api.marketcheck.com/v2/search/car/active',
  params: {
    api_key: 'YOUR_API_KEY',
    year: '2020',
    make: 'ford',
    model: 'f-150',
    rows: '0',
    range_facets: 'price|500|100000|10000,miles|5000|50000|5000'
  },
  headers: {Accept: 'application/json'}
};

try {
  const { data } = await axios.request(options);
  console.log(data);
} catch (error) {
  console.error(error);
}

Response

• Range facets are returned in the range_facets field of the response, structured as key-value pairs
• Keys are field names and values are objects containing:
  • counts: Array of buckets with lower_bound, upper_bound, and count properties
  • interval: Size of each bucket
  • start: Lower bound of the range
  • end: Upper bound of the range
  • before: Count of listings below the start value
  • between: Count of listings within the range
  • after: Count of listings above the end value
• If requested field is not allowed for range facets, it will be included in the response but with an error message indicating the field is not supported for range facets.

  {
    "range_facets": {
      "xyz": {
        "result": "Error",
        "message": "Field xyz is not allowed in range facets"
      }
    }
  }
  

Available Range Facets

Stats

The Search API calculates comprehensive statistics for numeric fields, providing market analysis and competitive intelligence insights.

Parameters

• stats — Comma-separated list of fields to calculate statistics on
  • Example: stats=price,miles,msrp
• stats can be combined with other parameters like facets, sort_by, and rows for detailed analysis

Example

import axios from 'axios';

const options = {
  method: 'GET',
  url: 'https://api.marketcheck.com/v2/search/car/active',
  params: {
    api_key: 'YOUR_API_KEY',
    year: '2024',
    make: 'ford',
    model: 'f-150',
    rows: '0',
    stats: 'price,miles'
  },
  headers: {Accept: 'application/json'}
};

try {
  const { data } = await axios.request(options);
  console.log(data);
} catch (error) {
  console.error(error);
}

Response

• Statistics are returned in the stats field of the response, structured as key-value pairs
• Keys are field names and values are objects containing:
  • min: Minimum value
  • max: Maximum value
  • count: Total number of listings with non-null values
  • missing: Number of listings with missing values
  • sum: Total sum of values
  • mean: Average value
  • stddev: Standard deviation
  • sum_of_squares: Sum of squares for variance calculation
  • median: Median value
  • percentiles: Percentile distribution (5th, 25th, 50th, 75th, 90th, 95th, 99th)
• If requested field is not allowed for stats, it will be included in the response but with an error message indicating the field is not supported for stats

  {
    "stats": {
      "xyz": {
        "result": "Error",
        "message": "Field xyz is not allowed in stats"
      }
    }
  }
  

Available Stats Fields

Below are the available fields for statistics calculations:

Financial Metrics

Performance and Efficiency

Market Timing

Finance and Lease Terms

Spatial Search

Search for cars available near specific locations using geographic coordinates, zip codes, or radius parameters for location-based inventory discovery.

Parameters

• latitude and longitude - Exact coordinates
• zip - ZIP code reference point
• radius - Search radius in miles

You can combine location parameters with any other search filters for precise geographic targeting.

Example

import axios from 'axios';

const options = {
  method: 'GET',
  url: 'https://api.marketcheck.com/v2/search/car/active',
  params: {
    api_key: 'YOUR_API_KEY',
    year: '2024',
    make: 'ford',
    model: 'f-150',
    rows: '2',
    zip: '90007',
    radius: '50'
  },
  headers: {Accept: 'application/json'}
};

try {
  const { data } = await axios.request(options);
  console.log(data);
} catch (error) {
  console.error(error);
}

Response

• Each listing includes a dist field with distance from the specified coordinates or ZIP code
• Distance is calculated in miles and returned as a numeric value
• Results are sorted by distance by default, with nearest listings appearing first

Response

The Inventory Search API returns JSON data with comprehensive vehicle listing information, including inventory details, dealer information, vehicle specifications, and optional facets and statistics.

Schema

interface InventorySearchResponse {
  num_found: number; // Total number of listings matching search criteria
  listings: Listing[]; // Array of vehicle listings
  facets?: Facets; // Field facets (when facets parameter is used)
  stats?: Stats; // Statistical data (when stats parameter is used)
  range_facets?: RangeFacets; // Range-based facets (when range_facets parameter is used)
}

interface Listing {
  id: string; // Unique listing identifier
  vin: string; // Vehicle Identification Number
  heading?: string; // Formatted listing title
  price?: number; // Current listing price
  miles?: number; // Vehicle mileage
  msrp?: number; // Manufacturer's Suggested Retail Price (as per dealer website)
  data_source: string; // Original data source identifier. Mostly `mc` for MarketCheck
  vdp_url?: string; // Vehicle detail page URL
  carfax_1_owner?: boolean; // Single owner history flag (If mentioned on dealer website)
  carfax_clean_title?: boolean; // Clean title status (If mentioned on dealer website)
  exterior_color?: string; // Exterior color description
  interior_color?: string; // Interior color description
  base_int_color?: string; // Standardized interior color
  base_ext_color?: string; // Standardized exterior color
  dom: number; // Days on market (lifetime)
  dom_180: number; // Days on market in last 180 days
  dom_active: number; // Days on market while active
  dos_active: number; // Days on site while active
  seller_type: string; // Type of seller (dealer, fsbo, auction)
  inventory_type: string; // Inventory classification (new, used)
  is_certified?: number; // Certified pre-owned flag (1 if certified, only appears when car is certified)
  stock_no?: string; // Dealer stock number
  last_seen_at: number; // Last seen timestamp (Unix Seconds), when the listing was last updated
  last_seen_at_date: string; // Last seen date (ISO format)
  scraped_at: number; // First seen timestamp (Unix Seconds), when the listing was first scraped
  scraped_at_date: string; // First seen date (ISO format)
  first_seen_at: number; // First seen timestamp (Unix Seconds), when the listing was first seen. Copy of `scraped_at` field
  first_seen_at_date: string; // First seen date (ISO format)
  first_seen_at_source: number; // First seen at source website timestamp (Unix Seconds)
  first_seen_at_source_date: string; // First seen at source website date (ISO format)
  first_seen_at_mc: number; // First seen at MarketCheck timestamp (Unix Seconds)
  first_seen_at_mc_date: string; // First seen at MarketCheck date (ISO format)
  ref_price?: number; // Previously listed price at same source for reference
  price_change_percent?: number; // Price change percentage from reference price
  ref_price_dt?: number; // Reference price date timestamp (Unix Seconds)
  ref_miles?: number; // Previously listed mileage at same source for reference
  ref_miles_dt?: number; // Reference mileage date timestamp (Unix Seconds)
  source: string; // Data source website domain
  model_code?: string; // Manufacturer model code
  in_transit?: boolean; // Vehicle in transit status
  availability_status?: string; // Current availability status
  financing_options?: ListingFinance; // Finance information (when available)
  leasing_options?: ListingLease; // Lease information (when available)
  media?: Media; // Photos and media content links
  dealer?: Dealer; // Dealer information
  mc_dealership?: McDealership; // Enhanced dealer information from MarketCheck's new dealership system
  build?: Build; // Vehicle specifications
}

interface ListingFinance {
  loan_term?: number; // Loan term in months
  loan_apr?: number; // Annual percentage rate
  down_payment?: number; // Required down payment amount
  down_payment_percentage?: number; // Down payment as percentage
  estimated_monthly_payment?: number; // Monthly payment estimate
}

interface ListingLease {
  lease_term?: number; // Lease term in months
  down_payment?: number; // Required down payment amount
  estimated_monthly_payment?: number; // Monthly lease payment estimate
}

interface Media {
  photo_links?: string[]; // Array of photo URLs from dealer website
  photo_links_cached?: string[]; // Array of cached photo URLs from MarketCheck
}

interface Dealer {
  id: number; // Unique dealer identifier
  website: string; // Dealer website URL
  name: string; // Dealer business name
  dealer_type?: string; // Dealer classification (franchise, independent)
  street?: string; // Street address
  city?: string; // City name
  state?: string; // State or province
  country?: string; // Country code
  latitude?: string; // Geographic latitude
  longitude?: string; // Geographic longitude
  zip?: string; // Postal/ZIP code
  phone?: string; // Contact phone number
  seller_email?: string; // Contact email address
  dealership_group_name?: string; // Parent dealership group
  msa_code?: string; // Metropolitan Statistical Area code
}

interface McDealership {
  mc_website_id?: number; // MarketCheck website identifier
  mc_dealer_id?: number; // MarketCheck dealer identifier
  mc_location_id?: number; // MarketCheck location identifier
  mc_rooftop_id?: number; // MarketCheck rooftop identifier
  mc_dealership_group_id?: number; // MarketCheck dealership group identifier
  mc_dealership_group_name?: string; // MarketCheck dealership group name
  mc_sub_dealership_group_id?: number; // MarketCheck sub-dealership group identifier
  mc_sub_dealership_group_name?: string; // MarketCheck sub-dealership group name
  mc_category?: string; // MarketCheck seller category (Dealer, FSBO, Auction, etc.)
  website?: string; // Dealer website URL
  name?: string; // Dealer business name
  dealer_type?: string; // Dealer classification (franchise, independent)
  street?: string; // Street address
  city?: string; // City name
  state?: string; // State or province
  country?: string; // Country code
  latitude?: string; // Geographic latitude
  longitude?: string; // Geographic longitude
  zip?: string; // Postal/ZIP code
  msa_code?: string; // Metropolitan Statistical Area code
  phone?: string; // Contact phone number
}

interface Build {
  year: number; // Model year
  make: string; // Vehicle manufacturer
  model?: string; // Vehicle model
  trim?: string; // Trim level
  version?: string; // Specific version/variant
  body_type?: string; // Body style (sedan, SUV, truck, etc.)
  vehicle_type?: string; // Vehicle category
  transmission?: string; // Transmission type
  drivetrain?: string; // Drivetrain configuration
  fuel_type?: string; // Fuel type (gasoline, electric, hybrid, etc.)
  engine?: string; // Engine description
  engine_size?: number; // Engine displacement
  engine_block?: string; // Engine block configuration
  doors?: number; // Number of doors
  cylinders?: number; // Number of cylinders
  made_in?: string; // Manufacturing country
  overall_height?: string; // Vehicle height
  overall_length?: string; // Vehicle length
  overall_width?: string; // Vehicle width
  std_seating?: string; // Standard seating capacity
  highway_mpg?: number; // Highway fuel economy
  city_mpg?: number; // City fuel economy
  powertrain_type?: string; // Powertrain classification
}

interface Facets {
  [key: string]: {
    item: string; // Facet term/value
    count: number; // Number of listings for this term
  }[];
}

interface Stats {
  [key: string]: {
    min: number; // Minimum value
    max: number; // Maximum value
    count: number; // Number of values
    missing: number; // Count of missing values
    sum: number; // Sum of all values
    mean: number; // Arithmetic mean
    stddev: number; // Standard deviation
    sum_of_squares: number; // Sum of squared values
    median: number; // Median value
    percentiles: {
      [key: string]: number; // Percentile values
    };
  };
}

interface RangeFacets {
  [key: string]: {
    counts: {
      lower_bound: number; // Range lower bound
      upper_bound: number; // Range upper bound
      count: number; // Number of listings in range
    }[];
    interval: number; // Interval size
    start: number; // Starting value
    end: number; // Ending value
    before?: number; // Count below start
    between: number; // Count within range
    after?: number; // Count above end
  };
}

Success Response

• 200 OK - Returns JSON object with search results
• Always includes num_found field indicating total matching listings
• listings array contains vehicle data (empty if no matches)
• Optional facets, stats, and range_facets based on request parameters
• Missing or null fields are excluded from individual listing objects

Error Response

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>"
}

Best Practices

• Always check HTTP status codes
• Implement retry logic for 5xx errors
• Respect rate limits (429 responses)
• Validate parameters before sending requests

Use Cases & Examples

Filtering by Specifications

• Filter listings based on specific vehicle attributes like make, model, year, and more. This allows users to find vehicles that match their exact preferences.
• Refer to the Parameters section for available filters.
• All parameters support multiple values, by using comma-separated values. For example, to filter by multiple makes, you can use make=Toyota,Honda,Ford.
• API searches are case-insensitive, yet we recommend using facets to get exact values for filtering. And pass them in the same case as they appear in the facets response to ensure consistency.

Example:

Here we're filtering for electric, 4 wheel drive SUVs from 2023 to 2025 from Ford, Audi, Hyundai, Chevrolet, and Toyota.

import axios from 'axios';

const options = {
  method: 'GET',
  url: 'https://api.marketcheck.com/v2/search/car/active',
  params: {
    api_key: 'YOUR_API_KEY',
    rows: '2',
    fuel_type: 'Electric',
    drivetrain: '4WD',
    body_type: 'SUV',
    year: '2023,2024,2025',
    make: 'Ford,Audi,Hyundai,Chevrolet,Toyota'
  },
  headers: {Accept: 'application/json'}
};

try {
  const { data } = await axios.request(options);
  console.log(data);
} catch (error) {
  console.error(error);
}

Inventory Types

• Use car_type to filter by new or used vehicles:
  • car_type=new for new vehicles
  • car_type=used for used vehicles
  • car_type=certified for certified pre-owned vehicles. These are subset of used vehicles.
• If car_type is not specified, the API returns all types by default.
• The API response contains the inventory_type field which shows new or used values. When car_type=certified is used, the inventory_type will be used since certified cars are used vehicles, but they will have an additional is_certified field with value 1 to distinguish them from regular used cars.

Example:

Here we're filtering for used vehicles.

import axios from 'axios';

const options = {
  method: 'GET',
  url: 'https://api.marketcheck.com/v2/search/car/active',
  params: {api_key: 'YOUR_API_KEY', car_type: 'used', rows: 2},
  headers: {Accept: 'application/json'}
};

try {
  const { data } = await axios.request(options);
  console.log(data);
} catch (error) {
  console.error(error);
}

Certified Pre-Owned Vehicles:

• Certified vehicles are a subset of used vehicles, so when you filter by car_type=used, you will also get certified vehicles included in the results.
• To filter for certified vehicles specifically, you can use car_type=certified.
  • This will return only certified pre-owned vehicles, excluding other used vehicles.
  • These vehicles will have inventory_type=used and an additional is_certified=1 field.
• If you want to exclude certified vehicles from your search, you can use exclude_certified=true parameter.

Example:

Here we're filtering for certified pre-owned vehicles.

import axios from 'axios';

const options = {
  method: 'GET',
  url: 'https://api.marketcheck.com/v2/search/car/active',
  params: {api_key: 'YOUR_API_KEY', car_type: 'certified', rows: 2},
  headers: {Accept: 'application/json'}
};

try {
  const { data } = await axios.request(options);
  console.log(data);
} catch (error) {
  console.error(error);
}

Here we're filtering for used vehicles, excluding certified pre-owned vehicles.

import axios from 'axios';

const options = {
  method: 'GET',
  url: 'https://api.marketcheck.com/v2/search/car/active',
  params: {api_key: 'YOUR_API_KEY', car_type: 'used', exclude_certified: 'true', rows: 2},
  headers: {Accept: 'application/json'}
};

try {
  const { data } = await axios.request(options);
  console.log(data);
} catch (error) {
  console.error(error);
}

Country and Region

• Use country parameter to specify the market:
  • country=us for US listings (default)
  • country=ca for Canadian listings
  • country=all for both US and Canadian listings
• Country parameter is required for all requests, and defaults to us if not specified. This is most common gotcha when using the API for Canadian data, as you need to explicitly pass country=ca in each request.
• Use state and city parameters to filter by specific regions within the US or Canada.
• Use msa_code to filter by Metropolitan Statistical Area (MSA) codes for more precise regional targeting (US only).

Example:

Here we're filtering for vehicles in Michigan, USA.

import axios from 'axios';

const options = {
  method: 'GET',
  url: 'https://api.marketcheck.com/v2/search/car/active',
  params: {api_key: 'YOUR_API_KEY', country: 'us', state: 'MI', rows: 2},
  headers: {Accept: 'application/json'}
};

try {
  const { data } = await axios.request(options);
  console.log(data);
} catch (error) {
  console.error(error);
}

Here we're filtering for vehicles in Ontario, Canada.

import axios from 'axios';

const options = {
  method: 'GET',
  url: 'https://api.marketcheck.com/v2/search/car/active',
  params: {api_key: 'YOUR_API_KEY', country: 'ca', state: 'ON', rows: 2},
  headers: {Accept: 'application/json'}
};

try {
  const { data } = await axios.request(options);
  console.log(data);
} catch (error) {
  console.error(error);
}

Find a Car by VIN

• Use vin parameter to search for a specific vehicle by its VIN (Vehicle Identification Number).
• This returns single listing (if exists) of that VIN, which is searchable (aka Attributed, Understanding Attribution).
• If you want all listings of that VIN, including duplicates, then add nodedup=true parameter to your request. This will return all listings of that VIN, including those that are not attributed (i.e. not searchable).

Example:

Here we're searching for a vehicle by its VIN.

import axios from 'axios';

const options = {
  method: 'GET',
  url: 'https://api.marketcheck.com/v2/search/car/active',
  params: {api_key: 'YOUR_API_KEY', vin: '1FTFW1E81PKE39204'},
  headers: {Accept: 'application/json'}
};

try {
  const { data } = await axios.request(options);
  console.log(data);
} catch (error) {
  console.error(error);
}

Here we're searching for all listings of that VIN, including duplicates.

import axios from 'axios';

const options = {
  method: 'GET',
  url: 'https://api.marketcheck.com/v2/search/car/active',
  params: {api_key: 'YOUR_API_KEY', vin: '1FTFW1E81PKE39204', nodedup: 'true'},
  headers: {Accept: 'application/json'}
};

try {
  const { data } = await axios.request(options);
  console.log(data);
} catch (error) {
  console.error(error);
}

Similar Cars

This is the most common use case for the Search API, allowing you to find similar vehicles based on various attributes.

• To find similar cars to a specific vehicle, use vins and match parameters:
  • vins - Comma-separated list of VINs to find similar vehicles for
  • match - Comma-separated list of attributes to match on (allowed values: year, make, model, trim, version, build_code, options_packages)
• The API returns listings that match the specified VINs and specified attributes.
• match parameter is optional, and if not specified, the API will match similar cars based on squish vin of the provided VINs.
  • Squish VIN is a simplified version of the VIN in which last 6 characters (which are serial number) and 9th character (a security check digit) are removed
  • Squish VIN thus signifies the general characteristics of the vehicle without being tied to a specific instance.
  • From these 10 character squish VINs, the 10th character (11th in the original 17 digit VIN) is replaced with ?, to remove plant code information, which is not relevant for matching similar cars.
  • For example, squish VIN for 1FTEW1EG9HKC35917 is 1FTEW1EGHK. From this squish VIN, the 10th character is replaced with ?, resulting in 1FTEW1EGH?. This is the squish VIN that is used for matching similar cars.
  • This is not generally what users want, so we recommend using match parameter to specify the attributes you want to match on.
• If the match parameter includes version, build_code, or options_packages:
  • Matching is performed exclusively on valid 17-character VINs.
  • version: A field derived from the Neovin decode. It represents a unique combination of the vehicle's year, make, model, trim, transmission, drivetrain, wheelbase, and body type.
  • build_code: A field derived from the Neovin decode that combines the vehicle's body style with its specific set of installed options packages.
  • options_packages: A list of the options packages installed on the vehicle. When used for matching, the API returns vehicles that have at least all the packages present in the input VIN. The returned vehicles may also contain additional options.
  • If any of the provided VINs are invalid or cannot be decoded, the API will return similar cars only for the valid VINs, excluding the invalid ones.
  • If none of the provided VINs are valid or decodable, the API will respond with a 422 Unprocessable Entity error.

Example:

Here we're finding similar cars to a specific VIN, matching on year, make, model, and trim.

import axios from 'axios';

const options = {
  method: 'GET',
  url: 'https://api.marketcheck.com/v2/search/car/active',
  params: {
    api_key: 'YOUR_API_KEY',
    vins: '1FTFW1E81PKE39204',
    match: 'year,make,model,trim',
    rows: 2
  },
  headers: {Accept: 'application/json'}
};

try {
  const { data } = await axios.request(options);
  console.log(data);
} catch (error) {
  console.error(error);
}

Market Value Analysis

• Use stats parameter to calculate statistics for specific fields, such as price, miles, and days on market to analyze market trends and vehicle competitiveness.
• Combining this with similar cars search allows you to find average price and mileage for similar vehicles, providing insights into market value and trends.

Example:

Here we're finding average price and mileage for similar cars to a specific VIN, matching on year, make, model, and trim.

import axios from 'axios';

const options = {
  method: 'GET',
  url: 'https://api.marketcheck.com/v2/search/car/active',
  params: {
    api_key: 'YOUR_API_KEY',
    vins: '1FTFW1E81PKE39204',
    match: 'year,make,model,trim',
    stats: 'price,miles',
    rows: 0
  },
  headers: {Accept: 'application/json'}
};

try {
  const { data } = await axios.request(options);
  console.log(data);
} catch (error) {
  console.error(error);
}

Time on Market Analysis

• There are several parameters that can be used to analyze time on market:
  • dom - Days on market, throughout the entire lifetime of the car
  • dom_180 - Days on market in the last 180 days
  • dom_active - Active days on market across all sources
  • dos_active - Days on source active
• Use stats parameter to calculate statistics for these fields, such as average days on market, minimum and maximum days on market, and percentiles.
• In addition, you can use first_seen_range and last_seen_range parameters to filter listings based on when they were first and last seen, respectively.

Example:

Here we're finding average days on market for similar cars to a specific VIN, matching on year, make, model, and trim, and filtering by first seen date in the last 30 days.

import axios from 'axios';

const options = {
  method: 'GET',
  url: 'https://api.marketcheck.com/v2/search/car/active',
  params: {
    api_key: 'YOUR_API_KEY',
    vins: '1FTFW1E81PKE39204',
    match: 'year,make,model,trim',
    stats: 'dom,dom_active,dos_active',
    first_seen_days: '30-0',
    rows: 0
  },
  headers: {Accept: 'application/json'}
};

try {
  const { data } = await axios.request(options);
  console.log(data);
} catch (error) {
  console.error(error);
}

Dealer Inventory Analytics and Insights

The Search API provides specialized functionality for dealer-level analysis, allowing you to gain comprehensive insights into specific dealer inventories, performance metrics, and market positioning. This is designed for competitive analysis, dealer performance monitoring, market research, and business intelligence applications.

Key Characteristics:

• Analytics-Focused: Returns comprehensive statistics, facets, and range distributions without individual listing data for optimal performance
• Complete Inventory View: Includes all listings for the specified dealer, including duplicates that are normally filtered out in standard searches
• Performance Optimized: Automatically configured for fast analytics queries rather than listing browsing, enabling rapid insights across large dealer inventories
• Comprehensive Coverage: Access to all dealer-related parameters for granular analysis at dealership, location, rooftop, and website levels

Behavioral Changes with Dealer Parameters:

When any dealer-related parameter is used (dealer_id, source, mc_website_id, etc.), the API automatically:

• Sets rows=0 and start=0 (no individual listings returned) to focus computational resources on analytics
• Disables deduplication (nodedup=true behavior) to show complete dealer inventory including all non-attributed (non-searchable) listings
• Focuses computational resources on statistics and facet calculations for faster response times

Need Individual Listings? If you require access to individual dealer listings with enhanced pagination limits, use the Dealership Syndication API which provides specialized endpoints for retrieving complete dealer inventories with higher pagination thresholds and detailed listing data.

Available Dealer Parameters:

• dealer_id
• source
• dealership_group_name
• 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

Examples:

Dealer Inventory Statistics

Here we're analyzing price and mileage statistics for a specific dealer's inventory:

import axios from 'axios';

const options = {
  method: 'GET',
  url: 'https://api.marketcheck.com/v2/search/car/active',
  params: {api_key: 'YOUR_API_KEY', source: 'stgautogroup.com', stats: 'price,miles'},
  headers: {Accept: 'application/json'}
};

try {
  const { data } = await axios.request(options);
  console.log(data);
} catch (error) {
  console.error(error);
}

Dealer Make and Model Distribution

Here we're analyzing the make and model distribution for a specific dealer to understand their inventory composition:

import axios from 'axios';

const options = {
  method: 'GET',
  url: 'https://api.marketcheck.com/v2/search/car/active',
  params: {api_key: 'YOUR_API_KEY', source: 'autonationusa.com', facets: 'make,model'},
  headers: {Accept: 'application/json'}
};

try {
  const { data } = await axios.request(options);
  console.log(data);
} catch (error) {
  console.error(error);
}

Dealer Price Range Analysis

Here we're analyzing price distribution for a specific dealer using range facets:

import axios from 'axios';

const options = {
  method: 'GET',
  url: 'https://api.marketcheck.com/v2/search/car/active',
  params: {
    api_key: 'YOUR_API_KEY',
    source: 'carmax.com',
    range_facets: 'price|10000|100000'
  },
  headers: {Accept: 'application/json'}
};

try {
  const { data } = await axios.request(options);
  console.log(data);
} catch (error) {
  console.error(error);
}

Dealer Performance Metrics

Here we're analyzing market timing metrics for a specific dealer:

import axios from 'axios';

const options = {
  method: 'GET',
  url: 'https://api.marketcheck.com/v2/search/car/active',
  params: {api_key: 'YOUR_API_KEY', mc_website_id: '1035095', stats: 'dom_active'},
  headers: {Accept: 'application/json'}
};

try {
  const { data } = await axios.request(options);
  console.log(data);
} catch (error) {
  console.error(error);
}

Search by Features

• Use high_value_features and options_packages parameters to filter listings based on specific features and options.
• high_value_features allows you to filter by premium features like navigation, sun/moonroof, leather seats, etc.
• options_packages allows you to filter by specific option packages that are available for the vehicle. These are codes that are sourced from NeoVIN
• Use exclude_high_value_features and exclude_options_packages to exclude listings with specific features or option packages.

Example:

Here we're filtering for vehicles with navigation and sun/moonroof, and excluding those with leather seats.

import axios from 'axios';

const options = {
  method: 'GET',
  url: 'https://api.marketcheck.com/v2/search/car/active',
  params: {
    api_key: 'YOUR_API_KEY',
    high_value_features: 'Navigation,connected camera,Sun/moonroof',
    rows: 2
  },
  headers: {Accept: 'application/json'}
};

try {
  const { data } = await axios.request(options);
  console.log(data);
} catch (error) {
  console.error(error);
}

Plot

• plot is a special parameter that allows you to pull more number of listings but with limited fields, for the purpose of plotting data on a map or chart
• It can also be used for analytical purposes
• When plot is set to true, the API returns upto 1000 listings with limited fields in one go

Example:

Here we're pulling a plot of vehicles in California, USA, with limited fields.

import axios from 'axios';

const options = {
  method: 'GET',
  url: 'https://api.marketcheck.com/v2/search/car/active',
  params: {api_key: 'YOUR_API_KEY', state: 'CA', plot: 'true', rows: 1000},
  headers: {Accept: 'application/json'}
};

try {
  const { data } = await axios.request(options);
  console.log(data);
} catch (error) {
  console.error(error);
}

Filter by Ranges

• For numeric fields, there are corresponding range parameters that allow you to filter listings based on specific ranges.
• For example, price_range, miles_range, msrp_range, dom_range, dom_180_range, dom_active_range, dos_active_range, highway_mpg_range, city_mpg_range and more
• These parameters allow you to filter listings based on specific ranges for each field, such as price, mileage, days on market, and fuel efficiency.

Example:

Here we're filtering for vehicles with price between $10,000 and $20,000, mileage between 0 and 50,000 miles, and days on market between 0 and 30 days.

import axios from 'axios';

const options = {
  method: 'GET',
  url: 'https://api.marketcheck.com/v2/search/car/active',
  params: {
    api_key: 'YOUR_API_KEY',
    price_range: '10000-20000',
    miles_range: '0-50000',
    dom_active: '0-30',
    rows: 2
  },
  headers: {Accept: 'application/json'}
};

try {
  const { data } = await axios.request(options);
  console.log(data);
} catch (error) {
  console.error(error);
}

Unique Values / Drill-Downs

• Use facets and range_facets parameters to get unique values and distributions for specific fields.
• These values can be used for drill-downs in your application, allowing users to explore inventory based on specific attributes.
• facets provides unique counts for categorical fields, while range_facets provides distribution analysis for numeric fields.
• We recommend using facets to get unique values for filtering, as it provides a more accurate and consistent set of values compared to using the raw data from other input sources

Example:

Here we're getting unique trim and fuel types for 2023 Ford F-150 vehicles, with a minimum count of 10 listings for each trim and fuel type.

import axios from 'axios';

const options = {
  method: 'GET',
  url: 'https://api.marketcheck.com/v2/search/car/active',
  params: {
    api_key: 'YOUR_API_KEY',
    rows: 0,
    year: '2023',
    make: 'Ford',
    model: 'F-150',
    facets: 'trim|0|1000|10,fuel_type|0|1000|10'
  },
  headers: {Accept: 'application/json'}
};

try {
  const { data } = await axios.request(options);
  console.log(data);
} catch (error) {
  console.error(error);
}

Valid Photo Links Only

• Use photo_links or photo_links_cached parameters to get only the listings that have valid photo links or cached photo links.
• This is useful for filtering out listings that do not have photos, which can be important for applications that require images for display or analysis.
• photo_links returns the original photo links, while photo_links_cached returns the cached photo links that are stored in the MarketCheck database.

Example:

Here we're filtering for vehicles with valid photo links, and returning only the listings that have photos.

import axios from 'axios';

const options = {
  method: 'GET',
  url: 'https://api.marketcheck.com/v2/search/car/active',
  params: {api_key: 'YOUR_API_KEY', min_photo_links: '5', photo_links: 'true', rows: 2},
  headers: {Accept: 'application/json'}
};

try {
  const { data } = await axios.request(options);
  console.log(data);
} catch (error) {
  console.error(error);
}

Non-VIN Listings

• MarketCheck Search API allows you to include non-VIN listings in your search results as well for completeness sake
• Read here to understand what non-VIN listings are: Understanding VIN v/s Non-VIN Listings
• To include non-VIN listings in your search results, use include_non_vin_listings=true parameter in your request
• This will return listings that do not have a VIN, but are otherwise valid listings
• Since VIN is missing, the specifications data is not normalized and may pollute the results

Example:

Here we're including non-VIN listings in our search results, which will return listings that do not have a VIN.

import axios from 'axios';

const options = {
  method: 'GET',
  url: 'https://api.marketcheck.com/v2/search/car/active',
  params: {api_key: 'YOUR_API_KEY', rows: 2, include_non_vin_listings: 'true'},
  headers: {Accept: 'application/json'}
};

try {
  const { data } = await axios.request(options);
  console.log(data);
} catch (error) {
  console.error(error);
}

Daily New Arrivals

• You can find new vehicles that have entered the market in the last 24 hours using first_seen_at_source_range (absolute) or first_seen_at_source_days (relative) parameters
• These would be the vehicles that have been added to the source website for the first time in the last 24 hours

Example:

import axios from 'axios';

const options = {
  method: 'GET',
  url: 'https://api.marketcheck.com/v2/search/car/active',
  params: {api_key: 'YOUR_API_KEY', first_seen_at_source_days: '1-*', rows: '2'},
  headers: {Accept: 'application/json'}
};

try {
  const { data } = await axios.request(options);
  console.log(data);
} catch (error) {
  console.error(error);
}

Vehicles with Recent Price Changes

• You can find vehicles that have had their prices changed in the last 24 hours using price_change parameter or price_change_range parameter, used in conjunction with first_seen_at_range or first_seen_days parameters
• This allows you to identify vehicles that have recently been discounted or had their prices adjusted, which can be useful for finding deals or understanding market trends
• Pairing with first seen parameters allows you to avoid listings whose ref_price is substantially older due to the listing being stale, or past historic listing of the same vehicle that has been re-listed at a later date

Example:

Here we're finding vehicles that have had their prices increased in last 24 hours, sorted by price change percentage in descending order.

import axios from 'axios';

const options = {
  method: 'GET',
  url: 'https://api.marketcheck.com/v2/search/car/active',
  params: {
    api_key: 'YOUR_API_KEY',
    rows: '2',
    first_seen_days: '1-*',
    price_change: 'positive',
    sort_by: 'price_change_percent',
    sort_order: 'desc'
  },
  headers: {Accept: 'application/json'}
};

try {
  const { data } = await axios.request(options);
  console.log(data);
} catch (error) {
  console.error(error);
}

As is evident from the example above, it can return listings that have had their prices corrected due to crawling errors. That is the reason why we recommend using price_change_range parameter to filter out listings that have had their prices changed within a specific range, such as 50% or lower, to avoid such listings.

import axios from 'axios';

const options = {
  method: 'GET',
  url: 'https://api.marketcheck.com/v2/search/car/active',
  params: {
    api_key: 'YOUR_API_KEY',
    rows: '2',
    first_seen_days: '1-*',
    price_change: 'positive',
    price_change_range: '0-50',
    sort_by: 'price_change_percent',
    sort_order: 'desc'
  },
  headers: {Accept: 'application/json'}
};

try {
  const { data } = await axios.request(options);
  console.log(data);
} catch (error) {
  console.error(error);
}

Find In-Transit Vehicles

• You can find vehicles that are currently in transit using the in_transit parameter
• These are vehicles that have been marked as in transit by the dealer, indicating they are on their way to the dealership or another location
• Typically, these are available in new inventory type

Example:

import axios from 'axios';

const options = {
  method: 'GET',
  url: 'https://api.marketcheck.com/v2/search/car/active',
  params: {api_key: 'YOUR_API_KEY', in_transit: 'true', car_type: 'new', rows: '2'},
  headers: {Accept: 'application/json'}
};

try {
  const { data } = await axios.request(options);
  console.log(data);
} catch (error) {
  console.error(error);
}

Finding Electric Cars

• You can find electric vehicles using the fuel_type parameter
• But for values that should be passed in the fuel_type parameter, we recommend using facets to get the exact values for filtering
• As besides pure electric vehicles, there are also hybrid and plug-in hybrid vehicles that may be classified as electric vehicles

Example:

Here we're first gathering the unique fuel types using facets

import axios from 'axios';

const options = {
  method: 'GET',
  url: 'https://api.marketcheck.com/v2/search/car/active',
  params: {api_key: 'YOUR_API_KEY', facets: 'fuel_type|0|100', rows: '0'},
  headers: {Accept: 'application/json'}
};

try {
  const { data } = await axios.request(options);
  console.log(data);
} catch (error) {
  console.error(error);
}

Next, we can filter for electric vehicles using the fuel_type parameter with many values, including electric, Electric / Unleaded, Electric / Premium Unleaded, Electric / E85 and Electric / Hydrogen, which are the values that are returned in the facets response.

import axios from 'axios';

const options = {
  method: 'GET',
  url: 'https://api.marketcheck.com/v2/search/car/active',
  params: {
    api_key: 'YOUR_API_KEY',
    fuel_type: 'electric,Electric / Unleaded,Electric / Premium Unleaded,Electric / E85,Electric / Hydrogen',
    rows: '2'
  },
  headers: {Accept: 'application/json'}
};

try {
  const { data } = await axios.request(options);
  console.log(data);
} catch (error) {
  console.error(error);
}