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.

type Response = HistoryResponse[];

interface HistoryResponse {
  // Default Fields
  id: string; // Unique listing identifier
  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 (e.g., dealer, fsbo, auction)
  inventory_type: string; // Type of inventory (e.g., new, used)
  last_seen_at: number; // Timestamp when the listing was last seen (Unix seconds)
  last_seen_at_date: string; // Date when the listing was last seen (ISO format)
  scraped_at: number; // Timestamp when the listing was first scraped (Unix seconds)
  scraped_at_date: string; // Date when the listing was first scraped (ISO format)
  first_seen_at: number; // Timestamp when the listing was first seen (Unix seconds)
  first_seen_at_date: string; // Date when the listing was first seen (ISO format)
  source: string; // Source website of the listing
  seller_name: string; // Name of the seller
  city: string; // City of the seller
  state: string; // State of the seller
  zip: string; // ZIP code of the seller
  status_date: number; // Status date timestamp (Unix seconds)

  // Optional Fields (Available via fields parameter)
  vin?: string; // Vehicle Identification Number
  msrp?: number; // Manufacturer's Suggested Retail Price
  is_certified?: boolean; // Whether the vehicle is certified
  exterior_color?: string; // Exterior color of the vehicle
  interior_color?: string; // Interior color of the vehicle
  base_int_color?: string; // Base interior color
  base_ext_color?: string; // Base exterior color
  dom?: number; // Days on market (lifetime)
  dom_180?: number; // Days on market in the last 180 days
  dom_active?: number; // Active days on market
  stock_no?: string; // Stock number of the vehicle
  is_searchable?: boolean; // Whether the listing is searchable
  dealer_id?: number; // Dealer identifier
  street?: string; // Street address of the seller
  country?: string; // Country of the seller
  latitude?: string; // Latitude of the seller's location
  longitude?: string; // Longitude of the seller's location
  dos_active?: number; // Days on site actively listed
}

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