History by VIN

MarketCheck has been tracking vehicle listings since 2015, providing a rich historical dataset for analysis. The History API allows you to access this data by Vehicle Identification Number (VIN), 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/{vin}

Path Parameters:

• vin: The 17-character full Vehicle Identification Number 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 VIN.

import axios from 'axios';

const options = {
  method: 'GET',
  url: 'https://api.marketcheck.com/v2/history/car/1FTEW1EP1MFA57388',
  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

Available Fields

You can specify which fields to include in the history response using the fields parameter. If not specified, the API returns a default set of fields. The available fields include:

Sorting

You can not 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 VIN. 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.

Response

Schema

You can expect the History API response schema to vary based on the fields parameter. The default response schema is as follows:

interface Response {
  history: History[];
}

interface History {
  id: string;
  price: number;
  miles: number;
  data_source: string;
  vdp_url: string;
  seller_type: string;
  inventory_type: string;
  last_seen_at: number;
  last_seen_at_date: string;
  scraped_at: number;
  scraped_at_date: string;
  first_seen_at: number;
  first_seen_at_date: string;
  source: string;
  seller_name: string;
  city: string;
  state: string;
  zip: string;
  status_date: number;
}

Success Response

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

Error Response

Use Cases & Examples

Get Past Listings of a VIN

Given a VIN, you can retrieve all past listings and their details. This is useful for tracking price changes, mileage history, and seller information over time.

Example:

import axios from 'axios';

const options = {
  method: 'GET',
  url: 'https://api.marketcheck.com/v2/history/car/1FTEW1C57MKD83429',
  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);
}

Track a VINs Reappearance

If a dealer or seller had sold a vehicle in the past, they can use VIN History API to track if that VIN has reappeared in the market and with whom. This can help in understanding the vehicle's lifecycle and ownership changes.

Example:

Here in this example, we are fetching the history of a specific VIN to track its past listings and changes in price, mileage, and seller information with fields selected for detailed insights.

import axios from 'axios';

const options = {
  method: 'GET',
  url: 'https://api.marketcheck.com/v2/history/car/5UX13EU09R9V13306',
  params: {
    api_key: 'YOUR_API_KEY',
    fields: 'id,price,miles,seller_type,inventory_type,last_seen_at_date,first_seen_at_date,seller_name,city,state'
  },
  headers: {Accept: 'application/json'}
};

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

Price Tracking

You can use the VIN History API to track the price history of a specific vehicle over time. This can help evaluate depreciation in its value and trend in the price (is it increasing or decreasing).

Example:

import axios from 'axios';

const options = {
  method: 'GET',
  url: 'https://api.marketcheck.com/v2/history/car/5TFJA5DB4PX066997',
  params: {
    api_key: 'YOUR_API_KEY',
    fields: 'id,price,last_seen_at_date,seller_name,seller_type',
    sort_order: 'asc'
  },
  headers: {Accept: 'application/json'}
};

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

Vehicle Research

The VIN History API is a powerful tool for vehicle research. You can analyze the history of a specific vehicle, including its past listings, price changes, miles changes, and seller information. By analyzing miles changes over time, you can also infer the vehicle's usage patterns and potential wear and tear.

Example:

import axios from 'axios';

const options = {
  method: 'GET',
  url: 'https://api.marketcheck.com/v2/history/car/5GTEN63L888227488',
  params: {
    api_key: 'YOUR_API_KEY',
    fields: 'id,price,miles,exterior_color,interior_color,dom,dom_180,dom_active,last_seen_at_date,first_seen_at_date,seller_name,city,state,inventory_type'
  },
  headers: {Accept: 'application/json'}
};

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

See Also

• Inventory Search
• Car Listing Details
• VIN Decode