Inventory Search

The Inventory Search API offers near real-time access to active dealer inventories in the UK market, updated daily. With advanced filtering, sorting, and analytics features, it enables dealers, lenders, and analysts to efficiently explore current stock and extract valuable market insights.

Overview

• Access a comprehensive inventory of over 500,000 unique vehicles, fully deduplicated (Understanding Attribution) from active dealer listings across the UK market
• Data updates published daily on or before 11 AM UTC

Units & Conventions:

Base Path

GET https://api.marketcheck.com/v2/search/car/uk/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/uk/active',
  params: {
    api_key: 'YOUR_API_KEY',
    year: '2022',
    make: 'ford',
    model: 'puma',
    start: '0',
    rows: '5',
    facets: 'variant',
    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 UK 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

• dedup: Defaults to true - only Attributed (Searchable) listings appear in responses
  • Only one listing per VRM 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 vrm (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/uk/active',
  params: {
    api_key: 'YOUR_API_KEY',
    year: '2023',
    make: 'Ford',
    model: 'Puma',
    rows: '0',
    facets: 'variant|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": "Lincoln", "count": 1000 },
    { "item": "London", "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/uk/active',
  params: {
    api_key: 'YOUR_API_KEY',
    year: '2020',
    make: 'ford',
    model: 'puma',
    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 can calculate statistics for numeric fields, providing insights into inventory distribution and market trends.

Parameters

• stats — Comma-separated list of fields to calculate statistics on
  • Example: stats=price,miles,dos_active
• 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/uk/active',
  params: {
    api_key: 'YOUR_API_KEY',
    year: '2024',
    make: 'ford',
    model: 'puma',
    rows: '0',
    stats: 'price,dos_active'
  },
  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

Spatial Search

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

Parameters

• latitude and longitude - Exact coordinates
• postal_code - Postal 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: 'puma',
    rows: '2',
    postal_code: 'CO4 9YA',
    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 postal code
• Distance is calculated in miles and returned as a numeric value
• Results are sorted by distance by default, with nearest listings appearing first

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 SUVs from 2023 to 2025 from Volvo, Ford, Audi, Hyundai and Chevrolet.

import axios from 'axios';

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

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

Dealer Inventory Management

Access specific dealer inventories using dealer_id or source parameters. By default, these return all listings from a dealer's website, including duplicates and listings not attributed to them.

Example:

All Dealer Listings:

Here we're retrieving all listings from a specific dealer using their dealer_id:

import axios from 'axios';

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

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

Dealer's Owned Inventory:

Use owned=true with source parameter to get only vehicles attributed to the dealer through MarketCheck's attribution algorithm:

import axios from 'axios';

const options = {
  method: 'GET',
  url: 'https://api.marketcheck.com/v2/search/car/uk/active',
  params: {api_key: 'YOUR_API_KEY', source: 'cinch.co.uk', owned: 'true', rows: '1'},
  headers: {Accept: 'application/json'}
};

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

County and Region

• Use county and city parameters to filter by specific regions within the UK.
• Use postal_code to filter by specific postal codes for precise regional targeting.

Example:

Here we're filtering for vehicles in Greater London.

import axios from 'axios';

const options = {
  method: 'GET',
  url: 'https://api.marketcheck.com/v2/search/car/uk/active',
  params: {api_key: 'YOUR_API_KEY', county: 'Greater London', 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 VRM

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

Example:

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

import axios from 'axios';

const options = {
  method: 'GET',
  url: 'https://api.marketcheck.com/v2/search/car/uk/active',
  params: {api_key: 'YOUR_API_KEY', vrm: 'B21CLN'},
  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 VRM, including duplicates.

import axios from 'axios';

const options = {
  method: 'GET',
  url: 'https://api.marketcheck.com/v2/search/car/uk/active',
  params: {api_key: 'YOUR_API_KEY', rows: 2, vrm: 'B21CLN', 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 vrm and match parameters:
  • vrm - Vehicle Registration Mark to find similar vehicles for
  • match - Comma-separated list of attributes to match on (allowed values: year, make, model, variant, body_type)
• The API returns listings that match the specified VRM and specified attributes.
• match parameter is optional, and if not specified, the API will match similar cars based on internal decoded VRM specifications.

Example:

Here we're finding similar cars to a BMW 3 Series by matching year, make, model, and variant.

import axios from 'axios';

const options = {
  method: 'GET',
  url: 'https://api.marketcheck.com/v2/search/car/uk/active',
  params: {
    api_key: 'YOUR_API_KEY',
    vrm: 'AJ17XGA',
    match: 'year,make,model,variant',
    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 VRM, matching on year, make, model, and variant.

import axios from 'axios';

const options = {
  method: 'GET',
  url: 'https://api.marketcheck.com/v2/search/car/uk/active',
  params: {
    api_key: 'YOUR_API_KEY',
    vrm: 'SG64FYJ',
    match: 'year,make,model,variant',
    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/uk/active',
  params: {
    api_key: 'YOUR_API_KEY',
    vrm: 'SG64FYJ',
    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);
}

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 Lancashire, UK, with limited fields.

import axios from 'axios';

const options = {
  method: 'GET',
  url: 'https://api.marketcheck.com/v2/search/car/uk/active',
  params: {api_key: 'YOUR_API_KEY', county: 'Lancashire', 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/uk/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 Puma vehicles, with a minimum count of 10 listings for each variant 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: 'Puma',
    facets: 'variant|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/uk/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-VRM listings in your search results as well for completeness sake
• Read here to understand what non-VRM listings are: Understanding VIN v/s Non-VIN Listings
• To include non-VRM listings in your search results, use include_non_vin_listings=true parameter in your request
• This will return listings that do not have a VRM, but are otherwise valid listings
• Since VRM is missing, the specifications data is not normalized and may pollute the results

Example:

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

import axios from 'axios';

const options = {
  method: 'GET',
  url: 'https://api.marketcheck.com/v2/search/car/uk/active',
  params: {api_key: 'YOUR_API_KEY', rows: 1, 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/uk/active',
  params: {api_key: 'YOUR_API_KEY', first_seen_at_source_days: '1-*', rows: '1'},
  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/uk/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/uk/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);
}

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/uk/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, Petrol/electric, 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/uk/active',
  params: {
    api_key: 'YOUR_API_KEY',
    fuel_type: 'electric,Petrol/electric,Electric Hydrogen',
    rows: '2'
  },
  headers: {Accept: 'application/json'}
};

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

Typical Mileage for Year, Make, Model

• You can find the typical mileage for a specific year, make, and model using the stats parameter
• This allows you to understand how much vehicles of a specific year, make, and model are typically driven, which can be useful for understanding market trends and typical vehicle usage

Example:

Here we're finding the typical mileage for 2022 Volkswagen Golf models.

import axios from 'axios';

const options = {
  method: 'GET',
  url: 'https://api.marketcheck.com/v2/search/car/uk/active',
  params: {
    api_key: 'YOUR_API_KEY',
    year: '2022',
    make: 'Volkswagen',
    model: 'Golf',
    stats: 'miles',
    rows: '0'
  },
  headers: {Accept: 'application/json'}
};

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

FCA Compliance Filtering

The UK market includes specific regulatory filtering options for Financial Conduct Authority (FCA) compliance. Use the fca_status parameter to ensure you're only dealing with properly authorized dealers listings, which is crucial for regulatory compliance and consumer protection in the UK automotive finance sector.

Example:

Here we're filtering for vehicles from FCA authorized listings only.

import axios from 'axios';

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

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

Environmental and Efficiency Filtering

You can filter vehicles based on environmental criteria and fuel efficiency, important for UK market regulations like ULEZ compliance. This is particularly valuable for London and other UK cities with environmental zones where emissions standards determine vehicle access and charges.

Example:

Here we're filtering for ULEZ compliant vehicles with good fuel efficiency for the city London.

import axios from 'axios';

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

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

Electric Vehicle Search

You can search specifically for electric vehicles with battery and range specifications. Use EV-specific parameters like ev_battery_capacity_range, ev_vehicle_range, and ev_battery_type to find vehicles that meet specific electric performance requirements and charging infrastructure compatibility.

Example:

Here we're searching for electric vehicles with battery capacity between 0 and 10 kWh, vehicle range between 100 and 500 miles, and battery type as BEV.

import axios from 'axios';

const options = {
  method: 'GET',
  url: 'https://api.marketcheck.com/v2/search/car/uk/active',
  params: {
    api_key: 'YOUR_API_KEY',
    ev_battery_capacity_range: '0-10',
    ev_vehicle_range: '100-500',
    ev_battery_type: 'BEV',
    rows: 2
  },
  headers: {Accept: 'application/json'}
};

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

Preferred Dealers

You can designate certain dealers as preferred, allowing them to be uniquely identified in the API response. When you set a list of dealers as preferred, you can leverage this feature in the Search API.

Benefits

• Flagging Preferred Dealers: Listings from your preferred dealers will be marked with a preferred_dealer flag in the Dealers section of response
• Filtering Preferred Dealers: You can filter the API response to show only listings published by your preferred dealers

API Parameters for Preferred Dealers

Example:

Here we're filtering for listings from preferred dealers only.

import axios from 'axios';

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

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

Setup

To set up a preferred dealers list for your account, please contact MarketCheck team at sales@marketcheck.com. Once the preferred dealers are configured, the include_preferred_dealer_flag & preferred_dealers_only parameters will allow you to see the preferred dealer flag & only preferred dealers in the API responses.

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.

Response 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
  vehicle_registration_mark?: string; // Vehicle Registration Mark (UK)
  uvc_id?: string; // Unique Vehicle Code identifier
  heading?: string; // Formatted listing title
  price?: number; // Current listing price in GBP
  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
  is_certified?: number; // Certification status
  vdp_url?: string; // Vehicle detail page URL
  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)
  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
  ulez_compliant?: boolean; // ULEZ compliance status
  fca_status?: string; // FCA authorization status
  write_off_category?: string; // Write-off category classification
  num_owners?: number; // Number of previous owners
  vehicle_registration_date?: string; // Vehicle registration date
  insurance_group?: number; // UK insurance group rating
  is_vat_included?: boolean; // VAT inclusion status
  co2_emissions?: number; // CO2 emissions rating
  performance_co2?: number; // CO2 performance rating
  ev_battery_capacity?: number; // Electric vehicle battery capacity
  ev_battery_type?: string; // Electric vehicle battery type
  ev_vehicle_range?: number; // Electric vehicle range
  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 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
  county?: string; // County name (UK)
  country?: string; // Country code
  latitude?: string; // Geographic latitude
  longitude?: string; // Geographic longitude
  postal_code?: string; // UK postal code
  phone?: string; // Contact phone number
  seller_email?: string; // Contact email address
  fca_status?: string; // FCA authorization status
  preferred_dealer?: boolean; // Flag indicating if this is a preferred dealer
}

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
  county?: string; // County name (UK)
  country?: string; // Country code
  latitude?: string; // Geographic latitude
  longitude?: string; // Geographic longitude
  postal_code?: string; // UK postal code
  phone?: string; // Contact phone number
  fca_status?: string; // FCA authorization status
}

interface Build {
  year: number; // Model year
  make: string; // Vehicle manufacturer
  model?: string; // Vehicle model
  model_variant?: string; // Vehicle model variant
  trim?: string; // Trim level
  variant?: string; // Specific variant identifier
  body_type?: string; // Body style (saloon, hatchback, estate, etc.)
  vehicle_type?: string; // Vehicle category
  transmission?: string; // Transmission type
  drivetrain?: string; // Drivetrain configuration
  fuel_type?: string; // Fuel type (petrol, diesel, electric, hybrid, etc.)
  engine?: string; // Engine description
  engine_size?: number; // Engine displacement
  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
  wheelbase_category?: string; // Wheelbase classification
  std_seating?: string; // Standard seating capacity
  highway_mpg?: number; // Highway fuel economy
  city_mpg?: number; // City fuel economy
  combined_mpg?: number; // Combined fuel economy
  seating_capacity?: number; // Passenger seating capacity
  performance_torque_ftlb?: number; // Torque in foot-pounds
  performance_maxspeed_mph?: number; // Maximum speed in miles per hour
  performance_torque_rpm?: number; // Torque at RPM
  performance_power_bhp?: number; // Power in brake horsepower
  performance_power_rpm?: number; // Power at RPM
  performance_torque_nm?: number; // Torque in Newton-meters
  performance_power_kw?: number; // Power in kilowatts
  performance_co2?: number; // CO2 emissions rating
  euro_status?: number; // Euro emissions standard status
}

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

Performance Considerations

Optimal Request Patterns

1. Use specific filters instead of broad searches to reduce response times
2. Limit the number of facets and stats fields, as these can increase processing time
3. Avoid deep pagination - consider data feeds for large datasets
4. Use lower radius values for spatial searches to improve performance. If too large area is desired then consider using county or city parameters instead of radius, as they are more efficient.

Response Time Expectations

See Also

• Past Inventory Search