CLASSIC.COM Third-Party API Documentation

CLASSIC.COM Third-Party API Documentation

Version: November 2025
Confidential — For authorized third-party integrators only.

Table of Contents

  1. Overview
  2. Taxonomy API – Taxonomy Hierarchy – Types Reference
  3. Sales History API – Types Reference
  4. Comps API – Types Reference
  5. Widget Creation API – Mutations Reference
  6. Best Practices

Overview

The CLASSIC.COM Third-Party API is a GraphQL API that provides access to vehicle taxonomy data, sales history, comparable vehicle searches, and embeddable market chart widgets. It is organized into four functional areas:

Area Purpose
Taxonomy Hierarchical vehicle classification (Make → Model → Generation → Series → Trim → PowerTrain)
Sales History Query historical and live vehicle sales and listings
Comps Find comparable vehicles based on vehicle attributes
Widget Creation Generate embeddable market chart iframes for your platform

Taxonomy API

Taxonomy Hierarchy

The taxonomy represents the hierarchical structure of vehicle data. Understanding the relationships between these objects is essential for querying accurately.

Key Rules

  • Every vehicle always has a Make and a Model assigned — these are the two required anchors for all taxonomy lookups.
  • Models are bounded by year_start and year_end, which define the overall production lifespan of that model line.
  • Make and Model have direct relations to every other taxonomy object (ModelYear, ModelSeries, Trim, PowerTrain). All child objects carry both make_id and model_id.
  • ModelSeries (Variant) has a many-to-one relationship with Make and Model, and can also be related to one or more ModelYear generations. A single ModelSeries can have one or multiple Trims and PowerTrains associated with it.
  • Trim and PowerTrain only require Make and Model associations but can optionally be associated with a ModelYear (generation) and/or a ModelSeries (variant) for more precise classification.
  • Relationships across the taxonomy are both one-to-many and many-to-one — a generation can have multiple variants, a variant can belong to multiple generations, and a powertrain can appear across multiple series and generations.

Relationship Diagram

Make ──────────────────────────────────────────────────────────┐
 └── Model (bounded by year_start / year_end)                  │
      │                                                         │
      ├── ModelYear / Generation ──────────────────────────┐   │
      │    │  (e.g. 964, 993, 996, 997, 991, 991.2)        │   │
      │    │                                                │   │
      │    └── ModelSeries / Variant ◄────────────────┐    │   │
      │         │  (e.g. GT3, Targa, Cabriolet)        │   │   │
      │         ├── Trim                               │   │   │
      │         │    (e.g. Touring, RS, Sport Classic) │   │   │
      │         └── PowerTrain                         │   │   │
      │              (e.g. 4.0L F6)                    │   │   │
      │                                                │   │   │
      ├── ModelSeries / Variant ───────────────────────┘   │   │
      │    (directly on Model, may span generations)        │   │
      │    ├── modelGeneration → [ModelYear] ───────────────┘   │
      │    ├── Trim                                             │
      │    └── PowerTrain                                       │
      │                                                         │
      ├── PowerTrain  (make_id + model_id required)             │
      │    + optional: model_year_id, model_series_id           │
      │                                                         │
      └── Trim  (make_id + model_id required)  ────────────────┘
           + optional: model_year_id, model_series_id

Porsche 911 Example

The Porsche 911 illustrates how these relationships work in practice, using real taxonomy data.

Make: Porsche (id: 1)
 └── Model: 911 (id: 5)  year_start: 1965 / year_end: 2026
      │
      │  ── Accessed via model.modelGeneration ──────────────────────────────
      │
      ├── ModelYear: F Body SWB (id: 6563)  1964–1968
      │    ├── Variants: T, S, L, Base Model, 901, 912, R, T/R
      │    └── Powertrains: 2.0L H6 (901/01/05), 2.0L H6 (S - 901/02/08), ...
      │
      ├── ModelYear: F Body LWB (id: 6564)  1969–1973
      │    ├── Variants: T, S/T, S, E, Carrera RS, Carrera RSR, 912
      │    └── Powertrains: 2.0L H6 (S-MFI), 2.2L H6 (S-MFI), 2.4L H6 (S-MFI), ...
      │
      ├── ModelYear: G Body (id: 6565)  1974–1989
      │    ├── Variants: Carrera, Speedster, Turbo, SC, Carrera RS, 935, 934, ...
      │    └── Powertrains: 2.7L H6-MFI, 3.0L H6, 3.2L H6-G50, 3.3L Turbo H6, ...
      │
      ├── ModelYear: 964 (id: 27)  1989–1994
      │    ├── Variants: Carrera, Carrera 4, Carrera RS, Turbo, Turbo S, Speedster, ...
      │    └── Powertrains: 3.6L H6, 3.8L H6, 3.3L Turbo H6, 3.6L Turbo H6 (X88), ...
      │
      ├── ModelYear: 993 (id: 18)  1994–1998
      │    ├── Variants: Carrera, Carrera 4, Carrera 4S, Carrera RS, Turbo, Turbo S, GT2, Targa, ...
      │    └── Powertrains: 3.6L H6, 3.8L H6, 3.6L Turbo H6, ...
      │
      ├── ModelYear: 996.1 (id: 16)  1997–2001
      │    ├── Variants: Carrera, Carrera 4, GT3, GT3 R, GT3 Cup
      │    └── Powertrains: 3.4L H6, 3.6L H6, 3.4L H6-X51
      │
      ├── ModelYear: 996.2 (id: 7316)  2000–2005
      │    ├── Variants: Carrera, Carrera 4, Carrera 4S, GT2, GT3, GT3 RS, GT3 RSR,
      │    │             GT3 Cup, Turbo, Turbo S, Targa
      │    └── Powertrains: 3.6L H6, 3.6L H6-X51, 3.6L Turbo H6, ...
      │
      ├── ModelYear: 997.1 (id: 17)  2004–2009
      │    ├── Variants: Carrera, Carrera S, Carrera 4, Carrera 4S, GT2, GT3, GT3 RS,
      │    │             GT3 RSR, GT3 Cup, Turbo, Targa 4, Targa 4S
      │    └── Powertrains: 3.6L H6, 3.8L H6, 3.6L Turbo H6, ...
      │
      ├── ModelYear: 997.2 (id: 6596)  2008–2013
      │    ├── Variants: Carrera, Carrera S, Carrera 4, Carrera 4S, Carrera GTS,
      │    │             Carrera 4 GTS, GT2 RS, GT3, GT3 RS, GT3 RS 4.0, GT3 R,
      │    │             GT3 RSR, GT3 Cup, Sport Classic, Speedster, Turbo, Turbo S,
      │    │             Turbo S Edition 918 Spyder, Targa 4S, Targa 4
      │    └── Powertrains: 3.6L H6, 3.8L H6, 4.0L H6, 3.6L Turbo H6, ...
      │
      ├── ModelYear: 991.1 (id: 180)  2011–2016
      │    ├── Variants: Carrera, Carrera S, Carrera 4, Carrera 4S, Carrera GTS,
      │    │             Carrera 4 GTS, GT2 RS, GT3, GT3 RS, GT3 Cup, GT America,
      │    │             R, Turbo, Turbo S, Targa 4, Targa 4S, Targa 4 GTS
      │    └── Powertrains: 3.8L H6, 3.8L Turbo H6, 4.0L H6, ...
      │
      ├── ModelYear: 991.2 (id: 6595)  2016–2020  ← example used throughout docs
      │    ├── ModelSeries: GT3 (id: 43)  ◄────────────────────────────────────┐
      │    │    ├── Trim: Clubsport                                              │
      │    │    ├── Trim: Standard                                               │
      │    │    ├── Trim: Touring                                                │
      │    │    ├── Trim: Manthey                                                │
      │    │    ├── Trim: Weissach                                               │
      │    │    └── Powertrains: 4.0L H6, 3.8L H6, 3.6L H6                     │
      │    ├── ModelSeries: Carrera GTS  (spans 991.1, 991.2, 997.2, 992.1, 992.2)
      │    │    ├── Trims: Club Coupe, America Edition, Spirit 70, ...           │
      │    │    └── Powertrains: 3.0L Turbo H6 (991), 3.8L H6-X51, ...         │
      │    ├── ModelSeries: Carrera, Carrera 4, Carrera 4S, Carrera S, Carrera T │
      │    ├── ModelSeries: GT3 RS, GT2 RS, GT2 RS Clubsport, GT3 Cup, GT3 R    │
      │    ├── ModelSeries: Turbo, Turbo S, 935, Speedster, Targa 4, Targa 4S   │
      │    └── Powertrains (gen-level): 3.8L Turbo H6, 4.0L H6, 3.0L Turbo H6 │
      │                                                                           │
      ├── ModelYear: 992.1 (id: 225)  2019–2025                                  │
      │    ├── Variants: Carrera, Carrera S, Carrera 4, Carrera 4S, Carrera GTS, │
      │    │             Carrera 4 GTS, Carrera T, GT3, GT3 RS, GT3 R Rennsport, │
      │    │             GT3 Cup, Turbo, Turbo S, Sport Classic, Dakar,          │
      │    │             Targa 4, Targa 4S, Targa 4 GTS, S/T                    │
      │    └── Powertrains: 3.0L Turbo H6, 4.0L H6, 4.2L H6, ...              │
      │                                                                           │
      └── ModelYear: 992.2 (id: 14582)  2024–2027                               │
           ├── Variants: Carrera, Carrera S, Carrera 4, Carrera 4S, Carrera GTS,│
           │             Carrera 4 GTS, Carrera T, GT3, GT3 RS, Targa 4S        │
           └── Powertrains: 3.0L Turbo H6 (992.2), 3.6L Turbo H6 (T-Hybrid), 4.0L H6
      │
      │  ── Accessed via model.modelVariant (directly on Model) ────────────────
      │     Same ModelSeries objects, traversable without going through a generation.
      │     Each carries its own year_ranges and links back to its generation(s).
      │
      ├── ModelSeries: GT3 (id: 43) ──────────────────────────────────────────┘
      │    year_ranges: 1999–2001, 2003–2011, 2014–2019, 2021–2027
      │    modelGeneration: [996.1, 997.1, 997.2, 991.1, 991.2, 992.1, 992.2]
      │    Trims: Clubsport, Standard, Touring, Manthey, Weissach
      │    Powertrains: 4.0L H6, 3.8L H6, 3.6L H6
      │
      ├── ModelSeries: Carrera (id: 44)
      │    year_ranges: 1974–2027
      │    modelGeneration: [G Body, 964, 993, 996.1, 996.2, 997.1, 997.2,
      │                       991.1, 991.2, 992.1, 992.2]
      │    Trims: 25th Anniversary Edition, 40th Anniversary, Club Sport,
      │           Black Edition, America Roadster, Widebody (M491), Singer variants, ...
      │    Powertrains: 2.7L H6-MFI, 3.0L H6, 3.2L H6-G50, 3.4L H6, 3.6L H6, ...
      │
      ├── ModelSeries: Turbo (id: 52)
      │    year_ranges: 1975–2026
      │    modelGeneration: [G Body, 964, 993, 997.1, 997.2, 991.1, 991.2, 992.1, 996.2]
      │    Trims: Slant Nose, LE, Martini Edition, 50 Years, Group B, Singer Turbo Study
      │    Powertrains: 3.0L Turbo H6, 3.3L Turbo H6, 3.6L Turbo H6, 3.8L Turbo H6, ...
      │
      ├── ModelSeries: GT3 RS (id: 55)
      │    year_ranges: 2002–2004, 2007–2008, 2010–2011, 2015–2016, 2018–2020, 2023–2025
      │    modelGeneration: [996.2, 997.1, 997.2, 991.1, 991.2, 992.1, 992.2]
      │    Trims: Clubsport, Weissach, Manthey, Racing, Tribute to Carrera RS
      │    Powertrains: 3.6L H6, 3.8L H6, 4.0L H6
      │
      └── ... (57 total ModelSeries directly on Model)
      │
      │  ── Accessed via model.trim / model.powertrain (directly on Model) ─────
      │     Trims and PowerTrains also accessible at Model level.
      │     Each carries make_id + model_id, and optionally model_series_id
      │     and model_year_id for more precise placement.
      │
      ├── Trim: Touring  series_id:43(GT3)  year_id:6595(991.2)
      ├── Trim: Weissach  series_id:55(GT3 RS)  year_id:6595(991.2)
      ├── Trim: 25th Anniversary Edition  series_id:44(Carrera)  year_id:6565(G Body)
      ├── Trim: Endurance Racing Edition  series_id:47(Carrera S)  year_id:6595(991.2)
      └── ... (100 total Trims directly on Model)

Key takeaway: The same ModelSeries object (e.g., GT3, id: 43) is accessible both nested under a specific ModelYear generation and directly from the Model. When accessed from a generation, it is scoped to that generation’s context. When accessed directly from the model via modelVariant, it carries its full year_ranges and a modelGeneration list covering all generations it spans. Trim and PowerTrain objects at the model level each carry model_series_id and model_year_id to indicate their exact placement in the hierarchy.

There are four taxonomy sub-fields associated with Models in the API: ModelSeries, ModelYear, PowerTrain, and Trim.

Types Reference

Make

Represents a vehicle manufacturer (e.g., Porsche, Ferrari, BMW).

Field Type Description
id String Unique identifier for the make.
created String Creation date of the record.
modified String Last modification date of the record.
name String The name of the make.
search_phrases [String] Keywords associated with this make.
image String URL to an image of the make’s logo.
models [Model] List of Model objects associated with this make.

Model

Represents a specific model under a vehicle make (e.g., 911, F40, M3).

Field Type Description
id String Unique identifier for the model.
created String Creation date of the record.
modified String Last modification date of the record.
name String The name of the model.
search_phrases [String] Keywords associated with this model.
make_id ID ID of the make this model belongs to.
year_start String Starting year of production. Not all models have a year range specified.
year_end String Ending year of production. Not all models have a year range specified.
modelGeneration [ModelYear] List of ModelYear (generation) objects.
modelVariant [ModelSeries] List of ModelSeries (variant) objects.
default_title_format String Default title format string for this model.
powertrain [PowerTrain] List of PowerTrain objects associated with this model.
trim [Trim] List of Trim objects associated with this model.

ModelYear (Generation)

Represents a specific production year or range of years for a vehicle model. ModelYear is often used to denote significant updates, facelifts, or generational changes within the lifecycle of a model. Changes between model years can include aesthetic updates, mechanical improvements, or feature enhancements.

Note: All ModelYear records have a year range specified (year_start and year_end are always present).

Field Type Description
id String Unique identifier for the generation.
created String Creation date of the record.
modified String Last modification date of the record.
name String Name of the generation/model year (e.g., “991.2”).
search_phrases [String] Keywords associated with this generation.
make_id ID ID of the make this generation belongs to.
model_id ID ID of the model this generation is part of.
year_start String Beginning of the production year range. May match year_end for single-year models.
year_end String End of the production year range. May match year_start for single-year models.
powertrain [PowerTrain] PowerTrain objects detailing engine options available in this generation.
modelVariant [ModelSeries] ModelSeries objects indicating different variants within this generation.

ModelSeries (Variant)

Represents a specific series within a model, often denoting variations in design, features, or specifications offered over the model’s lifecycle (e.g., GT3, Targa, Convertible).

Field Type Description
id ID Unique identifier for the series.
created String Creation date of the record.
modified String Last modification date of the record.
name String Name of the model series. May indicate market positioning or design variation.
search_phrases [String] Keywords associated with this model series.
make_id ID ID of the make this series belongs to.
model_id ID ID of the model this series is part of.
modelGeneration [ModelYear] ModelYear objects indicating production years that apply to this series.
modelTrim [Trim] Trim objects available within this series.
powertrain [PowerTrain] PowerTrain objects detailing engine options for this series.
default_title_format String Default title format string for this series.
year_ranges String Production year range(s) this series was available.

Trim

Represents a specific trim level within a model series — a unique combination of features, configurations, and options. Trim levels often differentiate vehicles based on luxury, performance, or other characteristics (e.g., Touring, RS, Sport).

Field Type Description
id ID Unique identifier for the trim.
created String Creation date of the record.
modified String Last modification date of the record.
name String Name of the trim. May indicate market positioning or special features.
search_phrases [String] Keywords associated with this trim.
make_id ID ID of the make this trim belongs to.
model_id ID ID of the model this trim is part of.
model_year_id ID ID of the ModelYear associated with this trim.
model_series_id ID ID of the ModelSeries associated with this trim.
year_ranges String Production year range(s) this trim was available.

PowerTrain

Describes the engine of a vehicle (not the full drivetrain). The name typically encodes displacement, layout type, and any special designations (e.g., 2.5L I6 (M20B25)).

Field Type Description
id ID Unique identifier for the powertrain.
created String Creation date of the record.
modified String Last modification date of the record.
name String Name of the engine, including displacement, layout, and designations.
search_phrases [String] Keywords associated with this engine.
make_id ID ID of the make this engine belongs to.
model_id ID ID of the model this engine is part of.
model_year_id ID ID of the ModelYear associated with this engine.
model_series_id ID ID of the ModelSeries associated with this engine.
year_ranges String Production year range(s) this powertrain was available.

Taxonomy Queries

Query: makes

Retrieve a list of vehicle makes, optionally filtered by vehicle type.

Signature

makes(options: MakeFilterOptions): [Make]

Parameters

Parameter Type Description
options MakeFilterOptions Optional filter object.
options.type VehicleType Filters makes by vehicle type. Currently supports Automobile.

Returns: A list of Make objects.

Example — Retrieve makes with models and variants

query {
  makes {
    id
    name
    models {
      id
      name
      modelVariant {
        id
        name
      }
    }
  }
}

This returns all makes along with their associated models and model variants.

Sales History API

The Sales History API allows you to query CLASSIC.COM’s vehicle listings and sales data. Vehicles can be searched by keyword/VIN, by taxonomy names, by taxonomy IDs, or by price range.

Sales History Types

SimpleVehicle

The core vehicle object returned by all Sales History queries.

Listing fields

Field Type Description
title String Full vehicle title.
status String Current status of the listing (e.g., sold, for sale).
listing_type String Type of listing (e.g., auction, fixed price).
is_online Boolean Whether the listing is currently active/online.
is_featured Boolean Whether the listing is featured.
lot String Auction lot identifier.
lot_date String Date of the auction lot or listing.
route String URL path to the vehicle’s listing page on CLASSIC.COM.
image_url String URL to the vehicle’s primary image.
vin String Vehicle Identification Number.
matching_percentage String How closely this vehicle matches the search criteria.

Price fields

Field Type Description
price Int Listed or sale price in the original currency.
price_usd Int Price converted to USD.
price_currency String Original currency of the price.
high_bid_price Boolean Indicates whether the price reflects a high bid.
price_change [PriceChange] History of price changes for this listing. ⚠️ See note in PriceChange.

Mileage fields

Field Type Description
mileage Int The quantitative figure shown on the odometer. The actual unit depends on mileage_is_km. Use mileage_in_miles or mileage_in_km for normalized values.
mileage_is_km Boolean If true, the raw mileage value is in kilometers; if false, it is in miles.
mileage_in_km Int Mileage normalized and expressed in kilometers.
mileage_in_miles Int Mileage normalized and expressed in miles.
total_mileage_unknown Boolean Indicates whether total mileage is unknown (TMU).

Vehicle identity fields

Field Type Description
year Int Model year of the vehicle.
make Make The vehicle’s make (taxonomy object).
model Model The vehicle’s model (taxonomy object).
modelGeneration ModelYear The vehicle’s generation (taxonomy object).
modelVariant ModelSeries The vehicle’s series/variant (taxonomy object).
modelTrim Trim The vehicle’s trim (taxonomy object).
powertrain PowerTrain The vehicle’s engine (taxonomy object).
attributes [Attribute] List of additional vehicle attributes.

Location fields

Field Type Description
location_place_name String Name of the vehicle’s location.
location_country_code String Country code of the vehicle’s location.
location_state String State/province of the vehicle’s location.
location_state_code String State/province code.

PriceChange

⚠️ Work in Progress — The price_change field and the PriceChange object are currently under active development. The data returned may be incomplete or subject to change. Avoid building critical workflows that depend on this field until it is marked stable.

Represents a single price change event on a vehicle listing.

Field Type Description
id ID Unique identifier.
created String Record creation date.
modified String Record last modified date.
source_kind String Source of the price change.
price_kind String Kind of price (e.g., asking, reserve).
price Int The price value at this event.
price_status String Status associated with this price.
event_date String Date of the price change event.
currency_id ID Currency reference ID.
vehicle_id ID ID of the vehicle this change belongs to.

Attribute

Represents a key-value attribute of a vehicle (e.g., color, transmission, body style).

Field Type Description
id ID Unique identifier.
created String Record creation date.
modified String Record last modified date.
kind String Attribute category (e.g., exterior_color, transmission).
value String Attribute value (e.g., Guards Red, Manual).
search_phrases [String] Search keywords for this attribute.
description String Human-readable description.

Enums

SimpleVehicleFilter

Filters listings by their source or format.

Value Description
ALL Return all listing types.
LIVEEVENTS Return only live auction event listings.
ONLINE Return only online listings.

SimpleVehicleTypeFilter

Filters listings by their sale mechanism.

Value Description
ALL Return all sale types.
AUCTION Return only auction listings.
FIXEDPRICE Return only fixed-price listings.

Sales History Queries

Query: searchVehicle

Search for vehicles using a keyword or VIN, with optional date and listing filters.

Signature

searchVehicle(
  keyword: String
  vin: String
  filter: SimpleVehicleFilter
  min_date: Float
  max_date: Float
  listing_type: SimpleVehicleTypeFilter
): [SimpleVehicle]

Parameters

Parameter Type Required Description
keyword String No Free-text search keyword.
vin String No Vehicle Identification Number (or chassis/serial number).
filter SimpleVehicleFilter No Filter by listing source (ALL, LIVEEVENTS, ONLINE).
min_date Float No Earliest listing/lot date as a Unix timestamp.
max_date Float No Latest listing/lot date as a Unix timestamp.
listing_type SimpleVehicleTypeFilter No Filter by sale type (ALL, AUCTION, FIXEDPRICE).

Returns: A list of SimpleVehicle objects.

Query: searchVehicleByTaxonomyName

Search for vehicles using human-readable taxonomy names. Useful when you have make/model names but not IDs.

Signature

searchVehicleByTaxonomyName(
  make: String!
  model: String!
  year: String
  modelGeneration: String
  modelVariant: String
  modelTrim: String
  powertrain: String
  bodystyle: String
  transmission: String
  doors: String
  filter: SimpleVehicleFilter
  min_date: Float
  max_date: Float
  listing_type: SimpleVehicleTypeFilter
): [SimpleVehicle]

Parameters

Parameter Type Required Description
make String Yes Make name (e.g., "Porsche").
model String Yes Model name (e.g., "911").
year String No Vehicle year (e.g., "2019").
modelGeneration String No Generation name (e.g., "991.2").
modelVariant String No Series/variant name (e.g., "GT3").
modelTrim String No Trim name (e.g., "Touring").
powertrain String No Engine descriptor (e.g., "4.0L F6").
bodystyle String No Body style name (e.g., "Coupe").
transmission String No Transmission type (e.g., "Manual").
doors String No Number of doors (e.g., "2").
filter SimpleVehicleFilter No Filter by listing source.
min_date Float No Earliest date as Unix timestamp.
max_date Float No Latest date as Unix timestamp.
listing_type SimpleVehicleTypeFilter No Filter by sale type.

Returns: A list of SimpleVehicle objects.

Query: searchVehicleByTaxonomyId

Search for vehicles using taxonomy IDs. Recommended when you have already resolved taxonomy IDs from the makes query, as it provides the most precise results.

Signature

searchVehicleByTaxonomyId(
  make: ID!
  model: ID!
  year: String
  modelGeneration: ID
  modelVariant: ID
  modelTrim: ID
  powertrain: ID
  bodystyle: ID
  transmission: ID
  doors: ID
  filter: SimpleVehicleFilter
  min_date: Float
  max_date: Float
  listing_type: SimpleVehicleTypeFilter
): [SimpleVehicle]

Parameters

Parameter Type Required Description
make ID Yes Make taxonomy ID.
model ID Yes Model taxonomy ID.
year String No Vehicle year string.
modelGeneration ID No ModelYear taxonomy ID.
modelVariant ID No ModelSeries taxonomy ID.
modelTrim ID No Trim taxonomy ID.
powertrain ID No PowerTrain taxonomy ID.
bodystyle ID No Body style taxonomy ID.
transmission ID No Transmission taxonomy ID.
doors ID No Doors taxonomy ID.
filter SimpleVehicleFilter No Filter by listing source.
min_date Float No Earliest date as Unix timestamp.
max_date Float No Latest date as Unix timestamp.
listing_type SimpleVehicleTypeFilter No Filter by sale type.

Returns: A list of SimpleVehicle objects.

Query: getVehiclesFromPriceRange

Retrieve vehicles that sold or are listed within a specified price range, optionally filtered by date.

Signature

getVehiclesFromPriceRange(input: VehiclesFromPriceRangeInput): [SimpleVehicle]

Input: VehiclesFromPriceRangeInput

Field Type Required Description
min_price Float Yes Minimum price (in USD).
max_price Float Yes Maximum price (in USD).
min_date Float No Earliest date as Unix timestamp.
max_date Float No Latest date as Unix timestamp.

Returns: A list of SimpleVehicle objects.

Comps API

The Comps API finds comparable vehicles based on a detailed set of vehicle attributes. It is useful for determining market context for a specific vehicle by returning similar vehicles and a match count.

Comps Types

SimpleVehicleCompsResponse

The response object returned by the comps query.

Field Type Description
count Int Total number of comparable vehicles found.
similar [SimpleVehicle] List of comparable SimpleVehicle objects.

Comps Queries

Query: getCompsFromTaxonomy

Find comparable vehicles based on a detailed vehicle description. All fields in VehicleCompsInput are optional, but providing more fields yields more precise results.

Signature

getCompsFromTaxonomy(
  input: VehicleCompsInput
  vin: String
  location: [String]
): SimpleVehicleCompsResponse

Parameters

Parameter Type Required Description
input VehicleCompsInput No Detailed vehicle attribute input object (see below).
vin String No VIN to directly identify the vehicle.
location [String] No Location filter (e.g., country or region codes).

Input: VehicleCompsInput

Field Type Description
year Int Vehicle model year.
make String Make name.
model String Model name.
model_generation String Generation name.
model_variant String Series/variant name.
model_trim String Trim name.
engine String Engine descriptor.
exterior_color ExtColor Exterior color enum value.
interior_color IntColor Interior color enum value.
transmission Transmission Transmission type enum value.
driver_side DriverSide Driver side (LHD/RHD).
body_style BodyStyle Body style enum value.
doors Int Number of doors.
vehicle_type VehicleType Type of vehicle.
originality Originality Originality/condition category.
mileage Int Vehicle mileage.
tmu Boolean Total mileage unknown flag.
min_date Float Earliest date filter as Unix timestamp.
max_date Float Latest date filter as Unix timestamp.

Returns: A SimpleVehicleCompsResponse object.

Widget Creation API

The Widget Creation API allows you to generate embeddable market chart widgets for any vehicle. Widgets are returned as an <iframe> embed code and hosted on CLASSIC.COM. Two mutations are available:

Mutation Input Method
createMarketWidget Uses taxonomy IDs
createMarketWidgetFromTaxonomy Uses taxonomy names

Both mutations find the best market match for the provided input and return an embeddable iframe widget showing a sales history chart. When a VIN is provided (recommended), the mutation queries the CLASSIC.COM vehicle database for the most accurate market match.

Mutations Reference

Mutation: createMarketWidget

Creates a market widget using taxonomy IDs.

Signature

mutation {
  createMarketWidget(input: CreateMarketWidgetInput!): CreateMarketWidgetPayload
}

Input: CreateMarketWidgetInput

Required fields:

Field Type Description
makeId ID! Unique identifier for the make.
modelId ID! Unique identifier for the model.
domain String! Domain where the widget will be embedded (e.g., "yourdomain.com").

Optional fields:

Field Type Description
vehicleVin String VIN, chassis number, or serial number. Used to query the CLASSIC.COM database for the best market match. Recommended best practice.
vehicleYear Int Vehicle year used to refine the market match.
modelVariant ID ID of the model variant (ModelSeries).
modelGeneration ID ID of the model generation (ModelYear).
modelTrim ID ID of the trim level.
marketYear Int Filters the chart to only include data points from this specific year.

Mutation: createMarketWidgetFromTaxonomy

Creates a market widget using human-readable taxonomy names. Produces the same result as createMarketWidget when equivalent inputs are provided.

Signature

mutation {
  createMarketWidgetFromTaxonomy(
    input: CreateMarketWidgetTaxonomyInput
  ): CreateMarketWidgetPayload
}

Input: CreateMarketWidgetTaxonomyInput

Required fields:

Field Type Description
makeName String! Make name (e.g., "Porsche").
modelName String! Model name (e.g., "911").
domain String! Domain where the widget will be embedded.

Optional fields:

Field Type Description
vehicleVin String VIN, chassis number, or serial number. Recommended best practice.
vehicleYear Int Vehicle year used to refine the market match.
modelVariantName String Series/variant name (e.g., "GT3").
modelGenerationName String Generation name (e.g., "991.2").
modelTrimName String Trim name (e.g., "Touring").
marketYear Int Filters the chart to only include data points from this specific year.

Response Types

CreateMarketWidgetPayload

The object returned by both widget creation mutations.

Field Type Description
code String! HTTP status code (e.g., "200").
success Boolean! Whether the mutation ran successfully.
message String! Status message (e.g., "widget created").
data [SimpleMarketWidget] Array containing the created widget object.

SimpleMarketWidget

The data object for the created widget.

Field Type Description
id ID Unique identifier of the created widget.
name String Internal name of the widget.
domain String Domain the widget is registered to.
createdAt String Unix timestamp of widget creation.
hashId String Hash ID used to construct the widget URL: https://www.classic.com/widget/{hashId}/
url String The complete <iframe> embed code including the widget URL.
vehicleVin String VIN specified in the input (if provided).
vehicleYear Int Vehicle year specified in the input (if provided).
userId ID ID of the user/account that generated the widget.
marketYear Int Market year filter applied to the widget (if specified).
chartType String Chart type generated. Currently only SALES charts are supported.
rangeInterval String Time range interval for the chart (5y, 1y, 6m, 3m, 1m). All widgets are currently created with a 5y interval.
deleted Boolean Whether the widget has been deleted from the database.

Full Examples

Generate a market chart for a 2019 Porsche 911 GT3 Touring using its VIN.

Mutation:

mutation {
  createMarketWidgetFromTaxonomy(
    input: {
      domain: "yourdomain.com"
      makeName: "Porsche"
      modelName: "911"
      vehicleYear: 2019
      vehicleVin: "WP0AC2A93KS149420"
    }
  ) {
    code
    success
    message
    data {
      id
      name
      domain
      createdAt
      hashId
      url
      vehicleVin
      vehicleYear
      userId
      marketYear
      chartType
      rangeInterval
      deleted
    }
  }
}

Response:

{
  "data": {
    "createMarketWidgetFromTaxonomy": {
      "code": "200",
      "success": true,
      "message": "widget created",
      "data": {
        "id": "1405599",
        "name": "user-3-market-19763",
        "domain": "yourdomain.com",
        "createdAt": "1709843186760",
        "hashId": "z4ypNSG",
        "url": "<iframe src='https://www.classic.com/widget/z4ypNSG/' width='100%' height='480' style='border:0;'></iframe>",
        "vehicleVin": "WP0AC2A93KS149420",
        "vehicleYear": 2019,
        "userId": "3",
        "marketYear": null,
        "chartType": "SALES",
        "rangeInterval": "5y",
        "deleted": null
      }
    }
  }
}

The url field contains the ready-to-use <iframe> embed code. Simply insert it into your page HTML.

Example 2 — Create Widget via Taxonomy Names

Generate the same widget using full taxonomy name inputs (no VIN).

mutation {
  createMarketWidgetFromTaxonomy(
    input: {
      domain: "yourdomain.com"
      makeName: "Porsche"
      modelName: "911"
      modelGenerationName: "991.2"
      modelVariantName: "GT3"
      modelTrimName: "Touring"
      vehicleYear: 2019
    }
  ) {
    code
    success
    message
    data {
      id
      hashId
      url
      chartType
      rangeInterval
    }
  }
}

This produces the same widget and payload response as Example 1.

Example 3 — Retrieve Taxonomy Makes

Query all makes along with their models.

query {
  makes {
    id
    name
    models {
      id
      name
      modelVariant {
        id
        name
      }
    }
  }
}

Best Practices

Widget Creation – Provide vehicleVin when the vehicle exists in the CLASSIC.COM database. This ensures the widget is generated specifically for that individual vehicle, using the most accurate market match on record. If the VIN is not found or not provided, the widget will fall back to the query parameters you supply — so be as specific as possible with modelGenerationName, modelVariantName, modelTrimName, and vehicleYear to avoid the widget matching an incorrect or overly broad market. – Always include vehicleYear alongside the required make and model fields, whether using VIN or taxonomy inputs. – If the generated widget does not match the intended vehicle or market, review your input parameters and add more specificity — the fallback matching logic prioritizes the most granular taxonomy inputs available.

Sales History Queries – Use searchVehicleByTaxonomyId when you have resolved taxonomy IDs for the most precise results. – Use searchVehicleByTaxonomyName for quick integration when taxonomy IDs are not yet available. – Apply min_date and max_date filters (Unix timestamps) to scope results to relevant time periods.

Taxonomy – Traverse the hierarchy top-down (makes → models → modelGeneration/modelVariant) to resolve IDs before making vehicle searches or widget mutations. – Use search_phrases fields to understand how each taxonomy entity can be matched in free-text scenarios.

© 2024 CLASSIC.COM — Proprietary and Confidential. For authorized third-party use only.