Past Inventory Search

The Past Inventory Search API provides access to expired and inferred sold dealer listings from the past 90 days across UK markets. This powerful historical dataset has recent inventory data from thousands of dealerships, delivering access to extensive expired records for advanced market analysis.

With sophisticated filtering, sorting, and analytics capabilities identical to the Inventory Search API, this tool enables dealers, analysts, and automotive professionals to understand market trends, analyze pricing history, track inventory turnover, and gain insights into sales patterns and dealer performance.

Overview

• Access a comprehensive dataset of expired and sold dealer listings from the past 90 days
• Inferred sales data for sold vehicles, where the sale is attributed to a specific source and VRM. Read more about Inferred Sales
• De-duplication of listings by VRM, with options to include all listings for a VRM across all sources. Read more about Understanding Attribution
• Data updates are published daily, at the same time as the Inventory Search API, by 11:00 AM UTC
• Follows same interface conventions, so units and conventions are also consistent with the Inventory Search API

Key Differences from Active Inventory:

• Historical Data Only: This API exclusively returns expired listings from the past 90 days
• Inferred Sales: Includes sophisticated sold vehicle identification and attribution
• Analytical Focus: Optimized for market trend analysis and dealer performance tracking

Attribution & Sold Listings:

• A VRM (by extension, a vehicle) can have multiple listings over time at a single source website. Refer to Listing Lifecycle for understanding how listings are created, updated, and expired
• By default, only one listing per VRM is returned across all sources to avoid duplicates, unless you're searching within a specific dealer's past inventory (using source or dealer_id like parameters). Refer to Understanding Attribution for more details
• To include all listings for a VRM, you can use the nodedup=true parameter, which will return all listings for a VRM across all sources, including duplicates from the same source
• For a sold vehicle/VRM, its attributed (i.e. searchable) listing is marked as sold, to ensure correct attribution of sale as well
• Refer to Inferred Sales for more details on how sales are inferred and attributed
• All sold listings are expired listings, but not all expired listings are sold. Expired listings VRMs can be active in the market, with new listing created for the same VRM at a later date

Performance Restrictions:

Given the large volume of data, the endpoint has some performance restrictions:

• Only one of facets, stats, or range_facets parameters can be used per request
• Maximum allowed radius is smaller of 100 miles or your subscription's maximum radius

Default behavior, currency and units, request/response structure, and filtering parameters match those in the Inventory Search API overview.

Base Path

GET https://api.marketcheck.com/v2/search/car/uk/recents

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/recents',
  params: {
    api_key: 'YOUR_API_KEY',
    county: 'Leicestershire',
    sold: 'true',
    year: '2023',
    make: 'toyota',
    rows: '2'
  },
  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 Request section below.

Request

The Past Inventory Search API provides extensive filtering and search capabilities for historical automotive inventory listings. You can search by vehicle specifications, geographic location, pricing ranges, dealer types, date ranges, and numerous other criteria to analyze expired and sold vehicles.

All filtering, sorting, analytics, and pagination capabilities match those in the Inventory Search API, with additional parameters specific to historical data analysis.

Parameters

Defaults

• dedup: Defaults to true - only unique listings per VRM are returned, removing duplicates from the dataset
  • Use nodedup=true to include all listings, even duplicates

Special Parameters

sold

• Use sold=true to filter results to only include vehicles that have been marked as sold
• All sold listings are expired, but not all expired listings are sold
• Sold determination requires a 7-day period after expiration for accuracy

expired

• Use expired=true to filter for expired VRMs (VRMs that have no active listings)
• Not all expired VRMs are sold, but all sold VRMs are expired
• Helps identify vehicles that left the market without being sold

active_inventory_date_range

• Filter VRMs that were active between specific dates
• Format: YYYYMMDD-YYYYMMDD (either end can be omitted using *)
• Based on first_seen_at_source and last_seen_at_source timestamps
• Example: active_inventory_date_range=20250501-20250531

Pagination

Past Inventory Search API supports the same pagination capabilities as the Inventory Search API. API response includes num_found property indicating the total number of listings matching the search criteria.

Parameters:

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

Refer to the Inventory Search API pagination documentation for complete details and examples.

Sorting

The Past Inventory Search API supports sorting results by a single numeric or date field at a time, with the same functionality as the Inventory Search API.

Sort Parameters:

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

Refer to the Inventory Search API sorting documentation for complete field reference and examples.

Core Features & Functionality

Past Inventory Search supports all major features from the Inventory Search API with identical functionality:

• Facets - Build dynamic filters and analyze market distribution
• Range Facets - Statistical distribution for numeric fields
• Stats - Comprehensive market analytics
• Spatial Search - Location-based discovery

Use Cases & Examples

Find Recent Sold Vehicles

To find recently sold vehicles, you can use the sold=true parameter. This will filter results to only include vehicles that have been marked as sold in the past 90 days.

Example:

Here we search for sold vehicles in Leicestershire county with specific criteria, including price range of £1,000 to £30,000 and sorting by the most recent sale date.

import axios from 'axios';

const options = {
  method: 'GET',
  url: 'https://api.marketcheck.com/v2/search/car/uk/recents',
  params: {
    api_key: 'YOUR_API_KEY',
    county: 'Leicestershire',
    sold: 'true',
    price_range: '10000-30000',
    sort_by: 'last_seen',
    sort_order: 'desc',
    rows: '2'
  },
  headers: {Accept: 'application/json'}
};

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

Filter for Expired VRMs

• All listings in this endpoint are expired listings, but not all VRMs are expired.
• To find expired VRMs (i.e. vehicles that have no active listings), you can use the expired=true parameter.
• Not all expired VRMs are sold, but all sold VRMs are expired.

Example:

Here we search for expired VRMs in the London city.

import axios from 'axios';

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

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

Typical Days to Sell

• To find the typical days to sell a vehicle, you can use the stats parameter with either dom_active or dos_active fields.
• Based on the use case, you can choose the appropriate field to get the desired statistics.
  • dom_active gives you the days on market for the VRM across all sources. So you can use this to get the average days on market for a VRM across all sources.
  • dos_active gives you the days on site for the VRM on a specific source. So you can use this to get the average days it took for a dealer to sell this vehicle on a specific source.

Example:

Here we search for the average days to sell a vehicle in specific UK counties, across all sources using the dom_active field.

import axios from 'axios';

const options = {
  method: 'GET',
  url: 'https://api.marketcheck.com/v2/search/car/uk/recents',
  params: {
    api_key: 'YOUR_API_KEY',
    state: 'Leicestershire',
    sold: 'true',
    stats: 'dom_active',
    rows: '0'
  },
  headers: {Accept: 'application/json'}
};

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

Example:

Here we search for the average days to sell a vehicle for a specific dealer, using the dos_active field.

import axios from 'axios';

const options = {
  method: 'GET',
  url: 'https://api.marketcheck.com/v2/search/car/uk/recents',
  params: {
    api_key: 'YOUR_API_KEY',
    source: 'sytner.co.uk',
    county: 'Leicestershire',
    sold: 'true',
    stats: 'dos_active',
    rows: '0'
  },
  headers: {Accept: 'application/json'}
};

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

Average Sale Prices

• Using the stats parameter, you can retrieve average sale prices for vehicles in the past N days.
• This can be done for all vehicles or filtered by make, model, year, etc.

Example:

Here we search for the average sale prices of vehicles similar to a specific VRM in the past 30 days, around a specific location.

import axios from 'axios';

const options = {
  method: 'GET',
  url: 'https://api.marketcheck.com/v2/search/car/uk/recents',
  params: {
    api_key: 'YOUR_API_KEY',
    postal_code: 'ST5 9HX',
    radius: '50',
    vrm: 'NA22URU',
    match: 'year,make,model,variant',
    sold: 'true',
    last_seen_days: '30-*',
    stats: 'price',
    rows: '0'
  },
  headers: {Accept: 'application/json'}
};

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

Listings Active Between Two Dates

• All listings in this endpoint are expired listings, to find listings that were active between two dates, you can use the last_seen_range and first_seen_range parameters.
• For a listing to be considered active, it must have been seen in the market within the specified date range.
  • This means that the last_seen timestamp must be greater than or equal to the lower bound of the date range
  • And the first_seen timestamp must be less than or equal to the upper bound of the date range
• Both last_seen_range and first_seen_range parameters accept a date range in the format YYYYMMDD-YYYYMMDD, where the first date is the lower bound and the second date is the upper bound.
• Either end of the range can be omitted (by using a *) to indicate no limit on that side of the range.
• As mentioned earlier, only attributed (i.e. searchable) listings are returned by default, but in this case, the nodedup=true parameter can be used to return all listings for a VRM across all sources, including duplicates from the same source that were active during the specified date range.

Example:

Here we search for listings that were active between 1st May 2025 and 31st May 2025 including all listings across all sources for each VRM, around a specific location.

import axios from 'axios';

const options = {
  method: 'GET',
  url: 'https://api.marketcheck.com/v2/search/car/uk/recents',
  params: {
    api_key: 'YOUR_API_KEY',
    postal_code: 'ST5 9HX',
    radius: '50',
    last_seen_range: '20250501-*',
    first_seen_range: '*-20250531',
    nodedup: 'true',
    rows: '2'
  },
  headers: {Accept: 'application/json'}
};

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

VRMs Active Between Two Dates

• To find VRMs that were active between two dates, you can use the active_inventory_date_range parameter.
• This parameter accepts a date range in the format YYYYMMDD-YYYYMMDD, where the first date is the lower bound and the second date is the upper bound.
• Either end of the range can be omitted (by using a *) to indicate no limit on that side of the range.
• The active_inventory_date_range parameter filters the results to only include VRMs that had at least one listing active during the specified date range.
• By default, only attributed (i.e. searchable) listings are returned, but you can use the nodedup=true parameter to return all listings for a VRM across all sources, including duplicates from the same source.
• Key thing to understand is that this parameter filters the listings based on first_seen_at_source and last_seen_at_source timestamps, which are the timestamps when the listing was first and last seen on the source website respectively.

Example:

Here we search for VRMs that were active between 1st May 2025 and 31st May 2025.

import axios from 'axios';

const options = {
  method: 'GET',
  url: 'https://api.marketcheck.com/v2/search/car/uk/recents',
  params: {
    api_key: 'YOUR_API_KEY',
    postal_code: 'PA1 2BH',
    radius: '50',
    active_inventory_date_range: '20250501-20250531',
    nodedup: 'true',
    rows: '2'
  },
  headers: {Accept: 'application/json'}
};

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

Track Dealer Performance

• To track dealer performance, you can use the dealer_id or source parameters to filter results by a specific dealer or source website along with stats parameter to retrieve aggregated data
• This allows you to analyze how a dealer's inventory performance compares to the market, including average sale prices, days to sell, and more
• When using the dealer_id or source parameters, the results will include only listings from that specific dealer or source website. Attribution is disabled, so all listings from that dealer or source will be returned, including duplicates for the same VRM
• If you want to include only those VRMs that were attributed to that dealer or source, you can use the owned=true parameter, which will return only those listings that were attributed to that dealer or source

Example:

Here we search for a specific dealer's performance in UK counties, including average sale price.

import axios from 'axios';

const options = {
  method: 'GET',
  url: 'https://api.marketcheck.com/v2/search/car/uk/recents',
  params: {
    api_key: 'YOUR_API_KEY',
    rows: '0',
    dealer_id: '10037694',
    sold: 'true',
    stats: 'price'
  },
  headers: {Accept: 'application/json'}
};

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

Example:

Here we search for a specific source's performance, including average sale prices but only for cars that were attributed to that source.

import axios from 'axios';

const options = {
  method: 'GET',
  url: 'https://api.marketcheck.com/v2/search/car/uk/recents',
  params: {
    api_key: 'YOUR_API_KEY',
    rows: '0',
    source: 'sytner.co.uk',
    sold: 'true',
    stats: 'price'
  },
  headers: {Accept: 'application/json'}
};

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

Find Most Popular Makes and Models

• To find the most popular makes and models in the past 90 days, you can use the facets parameter to retrieve aggregated data along with sold=true to include only sold vehicles
• This allows you to analyze the distribution of makes and models in the market, including the number of sold vehicles

Example:

Here we search for the most popular makes and models in specific county, including only sold vehicles.

import axios from 'axios';

const options = {
  method: 'GET',
  url: 'https://api.marketcheck.com/v2/search/car/uk/recents',
  params: {
    api_key: 'YOUR_API_KEY',
    county: 'Leicestershire',
    sold: 'true',
    facets: 'make|0|100,model|0|100',
    rows: '0'
  },
  headers: {Accept: 'application/json'}
};

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

Find Top Dealers by Sales Volume

• To find the top dealers by sales volume, you can use the facets parameter to retrieve aggregated data along with sold=true to include only sold vehicles
• This allows you to analyze the distribution of dealers in the market, including the number of sold vehicles

Example:

Here we get aggregated data for the top dealers by sales volume in specific county, including only sold vehicles.

import axios from 'axios';

const options = {
  method: 'GET',
  url: 'https://api.marketcheck.com/v2/search/car/uk/recents',
  params: {
    api_key: 'YOUR_API_KEY',
    county: 'Leicestershire',
    sold: 'true',
    facets: 'source|0|1000',
    rows: '0'
  },
  headers: {Accept: 'application/json'}
};

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

Inventory Turnover Analysis

Analyze how quickly different vehicle segments move through the market by comparing days on market across various categories.

Example:

Here we're analyzing inventory turnover rates for different body types to understand which vehicle categories sell fastest.

First we'll get valid body types using the facets parameter, then we'll use the stats parameter to get the average days on market for each body type.

import axios from 'axios';

const options = {
  method: 'GET',
  url: 'https://api.marketcheck.com/v2/search/car/uk/recents',
  params: {
    api_key: 'YOUR_API_KEY',
    county: 'Leicestershire',
    sold: 'true',
    facets: 'body_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'll use the stats parameter to get the average days on market for each body type. One example is shown below, where we analyze the average days on market for SUVs in UK counties.

import axios from 'axios';

const options = {
  method: 'GET',
  url: 'https://api.marketcheck.com/v2/search/car/uk/recents',
  params: {
    api_key: 'YOUR_API_KEY',
    county: 'Leicestershire',
    sold: 'true',
    body_type: 'SUV',
    stats: 'dos_active',
    rows: '0'
  },
  headers: {Accept: 'application/json'}
};

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

Seasonal Market Trends

Track seasonal patterns in vehicle sales by analyzing sold vehicles within specific time periods and comparing across different months or seasons.

Example:

Here we're analyzing seasonal trends by looking at sold vehicles during a specific month to understand market patterns.

import axios from 'axios';

const options = {
  method: 'GET',
  url: 'https://api.marketcheck.com/v2/search/car/uk/recents',
  params: {
    api_key: 'YOUR_API_KEY',
    county: 'Greater London',
    sold: 'true',
    last_seen_range: '20250501-20250531',
    stats: 'price',
    rows: '0'
  },
  headers: {Accept: 'application/json'}
};

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

Insurance Group Analysis

Analyze pricing and market distribution across different insurance group categories.

Example:

Here we analyze average sale prices across different insurance groups to understand pricing patterns.

import axios from 'axios';

const options = {
  method: 'GET',
  url: 'https://api.marketcheck.com/v2/search/car/uk/recents',
  params: {
    api_key: 'YOUR_API_KEY',
    sold: 'true',
    insurance_group: '15E',
    stats: 'price',
    rows: '0'
  },
  headers: {Accept: 'application/json'}
};

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

Regional Market Share Analysis

Analyze brand and dealer market share within specific UK regions using sold vehicle data.

Example:

Here we analyze market share by examining the distribution of sold vehicles by make within city of London.

import axios from 'axios';

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

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

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 PastSearchResponse {
  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.

See Also

• Introduction to UK Vehicle Inventory APIs
• Inventory Search