Marketcheck Home

Taxonomy Facets

Retrieve all unique values for a specific taxonomy field from MarketCheck's specs database.

The Taxonomy Facets API provides a way to retrieve all unique values for a specific taxonomy field from MarketCheck's comprehensive specifications database. This endpoint is particularly useful for applications that require a complete list of possible values for fields like make, model, trim, and other vehicle specifications without being limited to the current inventory.

This API allows you to gather unique facet values for various taxonomy fields, enabling you to build dynamic search interfaces, auto-complete features, and more. It supports multiple fields in a single request, making it efficient for applications that need to display or filter vehicle specifications.

Base Path

GET https://api.marketcheck.com/v2/specs/car/terms

Request

Parameters

All parameters are optional unless specifically noted as required.

15 Params
api_key
string required

Your MarketCheck API authentication key. Required for every request, unless OAuth is used.

body_subtype
string

Filters listings by body subtype (e.g., Crew, Extended, Regular, Extended Crew). Accepts multiple values separated by commas.

body_type
string

Filters listings by body type (e.g., SUV, Pickup, Sedan, Hatchback, Convertible). Accepts multiple values separated by commas.

drivetrain
string

Filters listings by drivetrain (FWD, RWD, 4WD). Accepts multiple values separated by commas.

engine
string

Filters listings by engine designation (e.g., 2.0L I4, 3.5L V6, 2.5L H4). Accepts multiple values as comma-separated list.

engine_block
string

Filters listings by engine block layout (V, I, H). Accepts multiple values separated by commas.

engine_size
string

Filters listings by engine displacement size (e.g., 2.0, 2.5, 3.5). Accepts multiple values separated by commas.

field
string

The field name for which to perform auto-completion.

fuel_type
string

Filters listings by fuel type (e.g., Unleaded, Diesel, Electric, Premium Unleaded, Electric / Unleaded). Accepts multiple values separated by commas.

make
string

Filters listings by vehicle make (e.g., Toyota, Ford, Mercedes-Benz). Accepts multiple values as comma-separated list.

model
string

Filters listings by specific vehicle model (e.g., Camry). Accepts multiple values separated by commas.

transmission
string

Filters listings by transmission type (Automatic, Manual, etc.). Accepts multiple values separated by commas.

trim
string

Filters listings by vehicle trim (e.g., EX, Limited). Accepts multiple values separated by commas.

vehicle_type
string

Filters listings by vehicle type (Truck, Car). Accepts multiple values separated by commas.

year
string

Filters listings by model year (e.g., 2020). Accepts multiple years separated by commas.

Required Parameters

  • field - The field(s) for which you want to retrieve unique values. You can specify multiple fields in a single request by separating them with commas. Supports pagination syntax: field=<field_name>|<offset>|<limit>

field parameter examples:

  • Single field: field=make
  • Multiple fields: field=make,model,year
  • With pagination: field=make|0|100,model|0|50

Available Fields

The following fields are available for facet retrieval and can be specified in the field parameter:

FieldDescription
makeVehicle manufacturer (e.g., Toyota, Ford)
modelVehicle model name (e.g., Camry, Mustang)
trimSpecific trim level or variant
body_typeMain body style (e.g., sedan, SUV, coupe)
body_subtypeSubcategory of body style (e.g., convertible)
vehicle_typeGeneral vehicle classification (e.g., car, truck)
transmissionTransmission type (e.g., automatic, manual)
drivetrainDrivetrain configuration (e.g., FWD, AWD)
fuel_typeType of fuel used (e.g., gasoline, diesel)
engineEngine name or code
engine_blockEngine block type (e.g., V6, I4)
engine_sizeEngine displacement or size (e.g., 2.0L, 3.5L)
yearModel year of the vehicle

Pagination

By default, the API returns the first 20 unique values for each specified field. You can control pagination using the syntax in the field parameter:

Syntax: field=<field_name>|<offset>|<limit>

  • field_name: The name of the field you want to retrieve values for
  • offset (default: 0): The starting index for the results (0-based)
  • limit (default: 20, max: 1000): The maximum number of unique values to return

Examples:

  • field=make|0|100 - Get first 100 makes
  • field=model|50|25 - Get 25 models starting from index 50
  • field=make|0|100&field=model|0|50 - Get first 100 makes and first 50 models

Sorting

Results are sorted alphabetically in ascending order by default. The sorting cannot be customized.

Response

Schema

interface TaxonomyFacetsResponse {
  terms: string[];
}

Success Response

  • Status Code: 200 OK
  • The API returns a JSON object where each key represents a field name and the value is an array of unique values for that field.

Use Cases & Examples

Get Unique Values For Any Field

Retrieve unique values for specific taxonomy fields to build dynamic search interfaces or dropdown menus.

Example:

request.js
import axios from 'axios';

const options = {
  method: 'GET',
  url: 'https://api.marketcheck.com/v2/specs/car/terms',
  params: {api_key: 'YOUR_API_KEY', field: 'make,fuel_type'},
  headers: {Accept: 'application/json'}
};

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

Retrieve Unique Fuel Types For Configurations

Retrieve unique fuel types filtered by specific vehicle make to get more targeted results.

Example:

request.js
import axios from 'axios';

const options = {
  method: 'GET',
  url: 'https://api.marketcheck.com/v2/specs/car/terms',
  params: {api_key: 'YOUR_API_KEY', field: 'fuel_type', make: 'toyota'},
  headers: {Accept: 'application/json'}
};

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

See Also