Skip to main content
GET
/
v1
/
facets
Filter facets
curl --request GET \
  --url https://api.visor.vin/v1/facets \
  --header 'Authorization: Bearer <token>'
{
  "data": {
    "total": 62152,
    "facets": {
      "make": [
        {
          "value": "Toyota",
          "count": 62152
        }
      ],
      "model": [
        {
          "value": "Camry",
          "count": 13730
        },
        {
          "value": "Tacoma",
          "count": 10682
        },
        {
          "value": "RAV4",
          "count": 7499
        }
      ]
    },
    "range_facets": {
      "price": {
        "buckets": [
          {
            "min": 24608,
            "max": 28732,
            "count": 5270
          },
          {
            "min": 28732,
            "max": 32856,
            "count": 5528
          },
          {
            "min": 32856,
            "max": 36980,
            "count": 8392
          }
        ],
        "interval": 4124,
        "min": 3988,
        "max": 86468
      }
    },
    "stats": {
      "price": {
        "min": 0,
        "max": 148085,
        "count": 60556,
        "missing": 1596,
        "mean": 38889.62,
        "median": 38300,
        "stddev": 15641.34
      }
    }
  },
  "meta": {
    "facets": [
      "make",
      "model",
      "price"
    ],
    "metric": "count",
    "sort": "-count",
    "minimum_metric_count": 10
  }
}

Authorizations

​
Authorization
string
header
required

Send API keys as Authorization: Bearer <api_key>. Query-string API keys are rejected.

Query Parameters

​
facets
string
required

Required comma-separated facet names to return. Supported facets: make, model, inventory_type, year, trim, version, base_exterior_color, exterior_color, base_interior_color, interior_color, seating_capacity, doors, engine, state, drivetrain, assembly_location, assembly_country, transmission, fuel_type, body_type, cylinders, dealer_type, availability_status, options_packages, features, keywords, price, msrp, miles, days_on_market.

​
facet_value_limit
string

Maximum number of values returned per categorical facet. Defaults to 20; maximum 100. Numeric range facets always return fixed buckets.

​
metric
string

Facet Metric used to compute an optional per-bucket aggregate. Defaults to count. Supported measures: price, miles, msrp, days_on_market, discount_from_msrp. Supported aggregates: mean, p5, p25, median, p75, p95. Use ., for example price.p95 or days_on_market.median. Non-count metrics require exactly one categorical facet.

​
sort
enum<string>

Facet bucket ordering. Defaults to -count. Sorting by metric requires a non-count metric.

Available options:
count,
-count,
metric,
-metric
​
make
string

Comma-separated make names or slugs to apply before counting facet buckets.

​
model
string

Comma-separated model names or slugs to apply before counting facet buckets.

​
trim
string

Comma-separated trim names to apply before counting facet buckets.

​
year
string

Comma-separated model years to apply before counting facet buckets.

​
state
string

Comma-separated two-letter dealer states to apply before counting facet buckets.

​
dealer_id
string

Comma-separated dealer UUIDs to apply before counting facet buckets. Accepts up to 50 dealer IDs.

​
dealer_type
string

Comma-separated dealer types to apply before counting facet buckets.

​
availability_status
string

Comma-separated availability statuses to apply before counting facet buckets: stock, transit, build.

​
inventory_type
string

Comma-separated inventory classes to apply before counting facet buckets: new, used, certified. cpo is accepted as an alias for certified.

​
body_type
string

Comma-separated body types.

​
transmission
string

Comma-separated transmission values.

​
drivetrain
string

Comma-separated drivetrain values.

​
assembly_location
string

Pipe-separated assembly locations. Uses | because locations often contain commas.

​
assembly_country
string

Comma-separated assembly country values.

​
fuel_type
string

Comma-separated fuel type values.

​
powertrain_type
string

Comma-separated powertrain type values.

​
engine
string

Comma-separated engine descriptions.

​
version
string

Comma-separated vehicle version values.

​
exterior_color
string

Comma-separated exterior color values.

​
interior_color
string

Comma-separated interior color values.

​
base_exterior_color
string

Comma-separated normalized exterior color values.

​
base_interior_color
string

Comma-separated normalized interior color values.

​
seating_capacity
string

Comma-separated seating capacity integers.

​
cylinders
string

Comma-separated cylinder count integers.

​
doors
string

Comma-separated door count integers.

​
options_packages
string

Comma-separated manufacturer option/package codes.

​
features
string

Comma-separated feature tokens.

​
keywords
string

Comma-separated provenance/history keyword tokens to apply before counting facet buckets. Supported values: one_owner, clean_title, branded, fleet.

​
vin_pattern
string

Comma-separated VIN masks, up to 10 distinct patterns. VIN characters match themselves, ? matches one VIN position, and * is allowed only at the end. Short masks are treated as prefixes, for example 1HG or 1HGCM826*.

​
exclude_make
string

Comma-separated makes to exclude.

​
exclude_model
string

Comma-separated models to exclude.

​
exclude_trim
string

Comma-separated trims to exclude.

​
exclude_year
string

Comma-separated model years to exclude.

​
exclude_state
string

Comma-separated dealer states to exclude.

​
exclude_inventory_type
string

Comma-separated inventory classes to exclude: new, used, certified. cpo is accepted as an alias for certified.

​
exclude_body_type
string

Comma-separated body types to exclude.

​
exclude_transmission
string

Comma-separated transmission values to exclude.

​
exclude_drivetrain
string

Comma-separated drivetrain values to exclude.

​
exclude_version
string

Comma-separated vehicle versions to exclude.

​
exclude_engine
string

Comma-separated engine descriptions to exclude.

​
exclude_assembly_location
string

Plus-separated assembly locations to exclude. Uses + to match the private API separator.

​
exclude_assembly_country
string

Comma-separated assembly countries to exclude.

​
exclude_exterior_color
string

Comma-separated exterior colors to exclude.

​
exclude_interior_color
string

Comma-separated interior colors to exclude.

​
exclude_base_exterior_color
string

Comma-separated normalized exterior colors to exclude.

​
exclude_base_interior_color
string

Comma-separated normalized interior colors to exclude.

​
exclude_options_packages
string

Comma-separated manufacturer option/package codes to exclude.

​
exclude_features
string

Comma-separated feature tokens to exclude.

​
exclude_fuel_type
string

Comma-separated fuel types to exclude.

​
exclude_powertrain_type
string

Comma-separated powertrain types to exclude.

​
exclude_keywords
string

Comma-separated keyword tokens to exclude.

​
inventory_status
enum<string>

Inventory mode used for facet counts. active is the default.

Available options:
active,
sold
​
sold_within_days
string

Positive integer day window for sold inventory facets.

​
snapshot_date
string

Historical active-inventory snapshot date in YYYY-MM-DD format.

​
min_price
string

Minimum listed price in whole dollars.

​
max_price
string

Maximum listed price in whole dollars.

​
min_mileage
string

Minimum odometer mileage.

​
max_mileage
string

Maximum odometer mileage.

​
min_msrp
string

Minimum combined MSRP in whole dollars.

​
max_msrp
string

Maximum combined MSRP in whole dollars.

​
min_days_on_market
string

Minimum days on market.

​
max_days_on_market
string

Maximum days on market.

​
latitude
string

Search origin latitude for radius filtering.

​
longitude
string

Search origin longitude for radius filtering.

​
postal_code
string

US ZIP/postal search origin for radius filtering.

​
radius
string

Maximum distance from the search origin, in miles. Requires postal_code or latitude and longitude. Maximum 500.

​
bbox
string

Map viewport as west,south,east,north. Cannot be combined with radius. Maximum diagonal is 1000 miles.

Response

Successful public API response.

Facet response envelope.

​
data
object
required

Facet counts and numeric ranges for the supplied filters.

​
meta
object
required

Facet response metadata.