History by VRM

MarketCheck has been tracking vehicle listings since 2022, providing a rich historical dataset for analysis. The History API allows you to access this data by Vehicle Registration Mark (VRM), enabling you to retrieve detailed historical information about any vehicle.

Read Understanding MarketCheck Data to learn more about what data is available and how to interpret it.

Base Path

GET https://api.marketcheck.com/v2/history/car/uk/{vrm}

Path Parameters:

• vrm: The Vehicle Registration Mark for which you want to retrieve history. Case-insensitive.

The following example demonstrates how to use the History API to get historical data for a specific VRM:

import axios from 'axios';

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

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

Request

Parameters

Defaults

Sorting

You cannot specify the sort by field, but you can control the sort order using the sort_order parameter.

The results are sorted by status_date in descending order by default, meaning the most recent listings appear first. You can change this to ascending order by setting sort_order=asc.

Pagination

• In History API, pagination is controlled by the page parameter
• By default, the API returns the first page of results with a limit of 50 records per page
• You can specify the page parameter to retrieve subsequent pages of results. Increase the page value by 1 to get the next set of results
• If you receive fewer than 50 records in a page, it indicates that there are no more records available for that VRM. You can stop paginating at that point
• If you attempt to paginate beyond the available records, the API will return an HTTP 422 error indicating that the requested page exceeds the number of records found

Use Cases & Examples

The VRM History API provides comprehensive historical data for vehicle analysis across multiple scenarios. This powerful tool enables you to retrieve detailed historical records for any Vehicle Registration Mark, supporting various business and research applications.

Key Use Cases:

• Historical Listing Analysis: Retrieve all past listings and their details to track price changes, mileage progression, and seller information over time
• Vehicle Reappearance Tracking: Monitor if a previously sold vehicle has reappeared in the market, helping understand vehicle lifecycle and ownership changes
• Price Trend Analysis: Track price history to evaluate depreciation patterns, market value trends, and pricing strategies
• Vehicle Research & Due Diligence: Analyze comprehensive vehicle history including listing patterns, usage indicators through mileage changes, and seller transition patterns

Example:

The following example demonstrates retrieving historical data for a specific VRM, which provides all the information needed for the above use cases:

import axios from 'axios';

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

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

Response

Success Response

• The API returns a JSON object with historical records for the specified VRM with HTTP status code 200 OK
• If the VRM is not found in the historical database, the API will return an empty array with HTTP status code 200 OK
  • VRM is not checked for validity, so if you provide an invalid VRM, the API will still return an empty array with 200 OK

Error Response

Response Schema

The VRM History API response schema includes the following structure:

type Response = HistoryResponse[];

interface HistoryResponse {
  id: string; // Unique identifier for the listing
  price: number; // Price of the vehicle
  miles: number; // Mileage of the vehicle
  data_source: string; // Source of the listing data
  vdp_url: string; // Vehicle Detail Page URL
  seller_type: string; // Type of seller (dealer, fsbo, auction)
  inventory_type: string; // Type of inventory (new, used)
  last_seen_at: number; // Timestamp when the listing was last seen
  last_seen_at_date: string; // Date when the listing was last seen
  scraped_at: number; // Timestamp when the listing was first seen
  scraped_at_date: string; // Date when the listing was first seen
  first_seen_at: number; // Timestamp when the listing was first seen
  first_seen_at_date: string; // Date when the listing was first seen
  source: string; // Source website of the listing
  seller_name: string; // Name of the seller
  city: string; // City of the seller
  zip: string; // Postal code of the seller
  postal_code: string; // Postal code of the seller
  status_date: number; // Timestamp when the listing was last seen
}

See Also

• Inventory Search
• Car Listing Details