MarketCheck Market API

openapi: 3.2.0
info:
  title: MarketCheck Cars Market API
  description: Access the New, Used and Certified cars inventories for all Car Dealers in US.
  version: 1.0.3
  contact:
    name: MarketCheck
    url: https://www.marketcheck.com/
  termsOfService: https://www.marketcheck.com/terms/
servers:
- url: https://mc-api.marketcheck.com/v1
  description: MarketCheck Production API
tags:
- name: Market
  description: Market analytics, trends, and pricing insights
paths:
  /averages:
    get:
      tags:
      - Market
      summary: Get Averages for YMM
      operationId: getAverages
      description: '[Merged with the /search API - Please check the ''stats'' parameter to the Search API] Get market averages for price / miles / msrp / dom (days on market) fields for active cars matching the given reference VIN''s basic specification or Year, Make, Model, Trim (Optional) criteria.'
      parameters:
      - name: vin
        in: query
        required: true
        description: VIN as a reference to the type of car for which averages data is to be returned
        schema:
          type: string
      - name: api_key
        in: query
        description: The API Authentication Key. Mandatory with all API calls.
        schema:
          type: string
      - name: year
        in: query
        description: Year of the car
        schema:
          type: string
      - name: make
        in: query
        description: Make of the car
        schema:
          type: string
      - name: model
        in: query
        description: Model of the Car
        schema:
          type: string
      - name: trim
        in: query
        description: Trim of the Car
        schema:
          type: string
      - name: fields
        in: query
        description: 'Comma separated list of fields to generate stats for. Allowed fields: price, miles, msrp, dom (days on market)'
        schema:
          type: string
      responses:
        '200':
          description: Successful response with market averages
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Averages'
  /comparison:
    get:
      tags:
      - Market
      summary: Compare market
      operationId: getComparison
      description: '[MOCK] Get historical market trends for cars matching the given VIN''s basic specification or Year, Make, Model, Trim (Optional) criteria'
      parameters:
      - name: vin
        in: query
        required: true
        description: VIN as a reference to the type of car for which comparison data is to be returned
        schema:
          type: string
      - name: api_key
        in: query
        description: The API Authentication Key. Mandatory with all API calls.
        schema:
          type: string
      responses:
        '200':
          description: Successful response with market comparison data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ComparisonPoint'
  /competition:
    get:
      tags:
      - Market
      summary: Competitors
      operationId: getCompetition
      description: '[MOCK] Competitor cars in market for current vin'
      parameters:
      - name: vin
        in: query
        required: true
        description: VIN as a reference to the type of car for which competitors data is to be returned
        schema:
          type: string
      - name: api_key
        in: query
        description: The API Authentication Key. Mandatory with all API calls.
        schema:
          type: string
      responses:
        '200':
          description: Successful response with competitor data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompetitorsPoint'
  /depreciation:
    get:
      tags:
      - Market
      summary: Depreciation
      operationId: getDepreciation
      description: '[MOCK] Model resale value based on depreciation'
      parameters:
      - name: vin
        in: query
        required: true
        description: VIN as a reference to the type of car for which Depreciation stats is to be returned
        schema:
          type: string
      - name: api_key
        in: query
        description: The API Authentication Key. Mandatory with all API calls.
        schema:
          type: string
      responses:
        '200':
          description: Successful response with depreciation data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DepreciationPoint'
  /mds:
    get:
      tags:
      - Market
      summary: Market Days Supply
      operationId: getMDS
      description: Get Market Days Supply (MDS) for a car identified by a valid VIN
      parameters:
      - name: vin
        in: query
        required: true
        description: VIN to decode
        schema:
          type: string
      - name: api_key
        in: query
        description: The API Authentication Key. Mandatory with all API calls.
        schema:
          type: string
      - name: exact
        in: query
        description: Exact parameter
        schema:
          type: string
      - name: latitude
        in: query
        description: Latitude component of location
        schema:
          type: number
          format: float
      - name: longitude
        in: query
        description: Longitude component of location
        schema:
          type: number
          format: float
      - name: radius
        in: query
        description: Radius around the search location
        schema:
          type: integer
      - name: debug
        in: query
        description: Debug parameter
        schema:
          type: string
      - name: include_sold
        in: query
        description: To fetch sold vins
        schema:
          type: string
      responses:
        '200':
          description: Successful response with market days supply data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Mds'
  /popularity:
    get:
      tags:
      - Market
      summary: Popularity
      operationId: getPopularity
      description: '[MOCK] Get the Popularity for the given simple filter criteria (by given Year, Make, Model, Trim criteria)'
      parameters:
      - name: year
        in: query
        required: true
        description: Year of the car
        schema:
          type: string
      - name: make
        in: query
        required: true
        description: Make of the car
        schema:
          type: string
      - name: model
        in: query
        required: true
        description: Model of the Car
        schema:
          type: string
      - name: trim
        in: query
        required: true
        description: Trim of the Car
        schema:
          type: string
      - name: body_type
        in: query
        required: true
        description: Body type to filter the cars on
        schema:
          type: string
      - name: api_key
        in: query
        description: The API Authentication Key. Mandatory with all API calls.
        schema:
          type: string
      - name: stats
        in: query
        description: The list of fields for which stats need to be generated. Allowed fields are - price, miles, msrp, dom.
        schema:
          type: string
      responses:
        '200':
          description: Successful response with popularity data
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PopularityItem'
  /trends:
    get:
      tags:
      - Market
      summary: Get Trends for criteria
      operationId: getTrends
      description: Get historical market trends for cars matching the given VIN's basic specification or Year, Make, Model, Trim (Optional) criteria
      parameters:
      - name: vin
        in: query
        required: true
        description: VIN as a reference to the type of car for which trend data is to be returned
        schema:
          type: string
      - name: car_type
        in: query
        required: true
        description: 'Car type. Allowed values are: new / used / certified'
        schema:
          type: string
          enum:
          - new
          - used
          - certified
      - name: api_key
        in: query
        description: The API Authentication Key. Mandatory with all API calls.
        schema:
          type: string
      - name: year
        in: query
        description: Year of the car
        schema:
          type: string
      - name: make
        in: query
        description: Make of the car
        schema:
          type: string
      - name: model
        in: query
        description: Model of the Car
        schema:
          type: string
      - name: trim
        in: query
        description: Trim of the Car
        schema:
          type: string
      responses:
        '200':
          description: Successful response with trend data
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TrendPoint'
components:
  schemas:
    Averages:
      type: object
      description: Market averages for a vehicle type
      properties:
        price:
          type: number
          description: Average price
        miles:
          type: number
          description: Average mileage
        msrp:
          type: number
          description: Average MSRP
        dom:
          type: number
          description: Average days on market
    DepreciationStats:
      type: object
      description: Annual depreciation statistics
      properties:
        year:
          type: integer
          description: Calendar year
        avg_price:
          type: number
          description: Average price for that year
        depreciation_pct:
          type: number
          description: Depreciation percentage from original
    DepreciationPoint:
      type: object
      description: Depreciation data for a vehicle
      properties:
        vin:
          type: string
        current_value:
          type: number
        depreciation_stats:
          type: array
          items:
            $ref: '#/components/schemas/DepreciationStats'
    CompetitorsPoint:
      type: object
      description: Competitor vehicle data
      properties:
        vin:
          type: string
        same_cars:
          $ref: '#/components/schemas/CompetitorsSameCars'
        similar_cars:
          $ref: '#/components/schemas/CompetitorsSimilarCars'
    CompetitorsCarDetails:
      type: object
      description: Competitor car details
      properties:
        id:
          type: string
        vin:
          type: string
        price:
          type: number
        miles:
          type: integer
        make:
          type: string
        model:
          type: string
        trim:
          type: string
        year:
          type: integer
    ComparisonPoint:
      type: object
      description: Market comparison data point
      properties:
        vin:
          type: string
        price:
          type: number
        miles:
          type: number
        dom:
          type: number
        data_points:
          type: array
          items:
            type: object
            additionalProperties: true
    TrendPoint:
      type: object
      description: Historical trend data point
      properties:
        date:
          type: string
          description: Date of the trend data point (YYYY-MM-DD)
        avg_price:
          type: number
          description: Average price on that date
        avg_miles:
          type: number
          description: Average miles on that date
        avg_dom:
          type: number
          description: Average days on market on that date
        num_listings:
          type: integer
          description: Number of listings on that date
    CompetitorsSameCars:
      type: object
      description: Same vehicle competitors
      properties:
        avg_price:
          type: number
        avg_miles:
          type: number
        num_listings:
          type: integer
        cars:
          type: array
          items:
            $ref: '#/components/schemas/CompetitorsCarDetails'
    PopularityItem:
      type: object
      description: Popularity data item
      properties:
        year:
          type: integer
        make:
          type: string
        model:
          type: string
        trim:
          type: string
        popularity_index:
          type: number
          description: Popularity index score
        num_listings:
          type: integer
    Mds:
      type: object
      description: Market Days Supply data
      properties:
        vin:
          type: string
        mds:
          type: number
          description: Market Days Supply value
        supply:
          type: integer
          description: Number of supply units
        sales_per_day:
          type: number
          description: Average sales per day
    CompetitorsSimilarCars:
      type: object
      description: Similar vehicle competitors
      properties:
        avg_price:
          type: number
        avg_miles:
          type: number
        num_listings:
          type: integer
        cars:
          type: array
          items:
            $ref: '#/components/schemas/CompetitorsCarDetails'
externalDocs:
  description: MarketCheck API Documentation
  url: https://docs.marketcheck.com/docs/api/cars