---
title: "Search and rank vehicles by metric"
method: GET
path: "/v1/specs/search"
tags: ["Vehicle Specifications"]
---

# Search and rank vehicles by metric

`GET /v1/specs/search`

## Request

- Base URL: `https://api.carstat.app`
- URL: `https://api.carstat.app/v1/specs/search`
- Auth: HTTP bearer

Search and rank vehicles by a performance or efficiency metric. Supports filtering by year, make, model, body type, fuel type, drive type, and transmission. For electrified vehicles, horsepower and torque use total system output when available. Fuel economy supports combined values from all available test cycles and MPGe for EVs. Requires credit access; charged at the published vehicle search rate.

## Query parameters

- `metric` 'horsepower' | 'torque' | 'mpg' | 'acceleration' | 'max_speed' | 'curb_weight' | 'cargo', required
- `order` 'asc' | 'desc'
- `limit` integer
- `year` integer
- `year_min` integer
- `year_max` integer
- `make` string
- `model` string
- `body_type` 'sedan' | 'hatchback' | 'liftback' | 'coupe' | 'cabriolet' | 'roadster' | 'targa' | 'suv' | 'crossover' | 'station_wagon' | 'pickup' | 'van' | 'minivan' | 'minibus' | 'offroad' | 'quadricycle'
- `fuel_type` 'petrol' | 'diesel' | 'electric' | 'natural_gas' | 'lpg' | 'hydrogen' | 'ethanol' | 'ethanol_e85' | 'ethanol_e100' | 'synthetic_gasoline' | 'mixture_of_two_stroke_engine'
- `drive_type` 'fwd' | 'rwd' | 'awd' | 'unknown'
- `transmission` 'at' | 'mt' | 'dct' | 'cvt' | 'amt' | 'imt' | 'unknown'

## Response `200`

successful search

- SearchResultsResponse
  - `metric` 'horsepower' | 'torque' | 'mpg' | 'acceleration' | 'max_speed' | 'curb_weight' | 'cargo', required: The metric used for ranking. Available metrics and their data sources: - `horsepower` — total system power (hp) for electrified vehicles; engine hp for ICE; summed motor output when no aggregate is available. Default order: desc. - `torque` — total system torque (Nm) for electrified vehicles; engine torque for ICE; summed motor output when no aggregate is available. Default order: desc. - `mpg` — combined US mpg from the available test cycle (combined, WLTC, EPA, CLTC, NEDC-equivalent, or NEDC); falls back to extra-urban mpg or EV MPGe. Default order: desc. - `acceleration` — 0–100 km/h time in seconds. Default order: asc (faster = lower). - `max_speed` — top speed in km/h. Default order: desc. - `curb_weight` — kerb weight in kg. Default order: asc (lighter = lower). - `cargo` — maximum trunk/boot volume in litres. Default order: desc.
  - `order` 'asc' | 'desc', required: Sort order applied
  - `total_matching` integer, required: Total vehicles matching the filters (before limit)
  - `showing` integer, required: Number of results returned
  - `results` SearchResultItem[], required
    - `modification_id` string, uuid: Unique modification identifier
    - `name` string: Engine/powertrain configuration name
    - `year_start` integer: First model year this configuration was available
    - `year_end` integer, nullable: Last confirmed production year; null when no final year is available
    - `make` string: Manufacturer name
    - `model` string: Model name
    - `generation` string, nullable: Vehicle generation name
    - `model_year` integer: Deprecated compatibility alias for year_start
    - `body_type` string, nullable: Body type(s), comma-separated when multiple (e.g. 'sedan', 'suv, crossover')

## Other responses

- `400`: invalid metric
- `401`: unauthorized
- `402`: Insufficient prepaid credits; the query is not charged
- `403`: No activated prepaid credits or account under review
- `503`: Query pricing is temporarily unavailable; the query is not charged

---

[API](https://skmtc.dev/carstat/apis/rest-api-reference.md) · [All operations](https://skmtc.dev/carstat/apis/rest-api-reference/llms.txt) · [OpenAPI document](https://skmtc.dev/carstat/apis/rest-api-reference/revisions/4dc0a7ab42ec?raw)