Copy page

Documentation

Reference data

Filter values

Code
GET /api/filters

Returns the values you can use in search filters, with the number of trims for each. Use it to fill dropdowns in a search form.

Example

Code
curl http://localhost:3000/api/filters

Code
{
  "years": [
    {
      "v": 2022,
      "count": 2938
    },
    {
      "v": 2023,
      "count": 2902
    },
    {
      "v": 2024,
      "count": 2320
    }
  ],
  "body_types": [
    {
      "v": "Convertible",
      "count": 232
    },
    {
      "v": "Coupe",
      "count": 377
    },
    {
      "v": "Ext Van",
      "count": 106
    }
  ],
  "engine_types": [
    {
      "v": "diesel",
      "count": 215
    },
    {
      "v": "electric",
      "count": 478
    },
    {
      "v": "electric (fuel cell)",
      "count": 8
    }
  ],
  "fuel_types": [
    {
      "v": "diesel fuel",
      "count": 215
    },
    {
      "v": "electric",
      "count": 480
    },
    {
      "v": "flex-fuel (unleaded/E85)",
      "count": 171
    }
  ],
  "drive_types": [
    {
      "v": "all wheel drive",
      "count": 3063
    },
    {
      "v": "four wheel drive",
      "count": 1689
    },
    {
      "v": "front wheel drive",
      "count": 1456
    }
  ],
  "countries_of_origin": [
    {
      "v": "Germany",
      "count": 1510
    },
    {
      "v": "Italy",
      "count": 90
    },
    {
      "v": "Japan",
      "count": 2085
    }
  ],
  "car_classifications": [
    {
      "v": "Compact SUV",
      "count": 320
    },
    {
      "v": "Compact car",
      "count": 745
    },
    {
      "v": "Compact crossover SUV",
      "count": 803
    }
  ],
  "price_range": {
    "min": 13600,
    "max": 555000
  },
  "horsepower_range": {
    "min": 76,
    "max": 1111
  },
  "sort_fields": [
    "price",
    "year",
    "make"
  ]
}

Long text and arrays are shortened in these examples.

Fields

Field	Description
years	Model years
body_types	Values for body_type
engine_types	Values for engine_type
fuel_types	Values for fuel_type
drive_types	Values for drive_type
countries_of_origin	Values for country
car_classifications	Size classes
price_range	Lowest and highest base MSRP
horsepower_range	Lowest and highest horsepower
sort_fields	Values for sort

Each value list has items of the form { "v": <value>, "count": <trims> }.

Statistics

Code
GET /api/stats

Returns totals and summaries for the whole dataset.

Example

Code
curl http://localhost:3000/api/stats

Code
{
  "totals": {
    "makes": 46,
    "models": 443,
    "trims": 8168,
    "colors": 109022
  },
  "by_year": [
    {
      "year": 2022,
      "trims": 2938,
      "models": 393,
      "avg_msrp": 55405,
      "avg_hp": 314,
      "electric_trims": 115
    },
    {
      "year": 2023,
      "trims": 2902,
      "models": 384,
      "avg_msrp": 59408,
      "avg_hp": 319,
      "electric_trims": 186
    }
  ],
  "by_body_type": [
    {
      "body_type": "SUV",
      "trims": 3502,
      "avg_msrp": 55142
    },
    {
      "body_type": "Sedan",
      "trims": 1168,
      "avg_msrp": 60469
    }
  ],
  "top_horsepower": [
    {
      "id": 401931137,
      "make": "Lucid",
      "model": "Air",
      "year": 2022,
      "trim": "Dream Edition Performance",
      "trim_description": "Dream Edition Performance 4dr Sedan AWD (electric DD)",
      "body_type": "Sedan",
      "base_msrp": 169000,
      "horsepower_hp": 1111,
      "engine_type": "electric",
      "fuel_type": "electric",
      "drive_type": "all wheel drive",
      "transmission": "1-speed direct drive",
      "total_seating": 5,
      "epa_combined_mpg": null,
      "epa_combined_mpge": 111,
      "epa_electricity_range_mi": 451,
      "image_urls": [
        "https://media.ed.edmunds-media.com/lucid/air/2022/oem/2022_lucid_air_sedan_dream-editio...",
        "https://media.ed.edmunds-media.com/lucid/air/2022/oem/2022_lucid_air_sedan_dream-editio..."
      ]
    },
    {
      "id": 401991128,
      "make": "Lucid",
      "model": "Air",
      "year": 2023,
      "trim": "Grand Touring Performance",
      "trim_description": "Grand Touring Performance 4dr Sedan AWD (electric DD)",
      "body_type": "Sedan",
      "base_msrp": 179000,
      "horsepower_hp": 1050,
      "engine_type": "electric",
      "fuel_type": "electric",
      "drive_type": "all wheel drive",
      "transmission": "1-speed direct drive",
      "total_seating": 5,
      "epa_combined_mpg": null,
      "epa_combined_mpge": 111,
      "epa_electricity_range_mi": 446,
      "image_urls": [
        "https://media.ed.edmunds-media.com/lucid/air/2023/oem/2023_lucid_air_sedan_grand-tourin...",
        "https://media.ed.edmunds-media.com/lucid/air/2023/oem/2023_lucid_air_sedan_grand-tourin..."
      ]
    }
  ],
  "most_affordable": [
    {
      "id": 401894900,
      "make": "Chevrolet",
      "model": "Spark",
      "year": 2022,
      "trim": "LS",
      "trim_description": "LS 4dr Hatchback (1.4L 4cyl 5M)",
      "body_type": "Hatchback",
      "base_msrp": 13600,
      "horsepower_hp": 98,
      "engine_type": "gas",
      "fuel_type": "regular unleaded",
      "drive_type": "front wheel drive",
      "transmission": "5-speed manual",
      "total_seating": 4,
      "epa_combined_mpg": 33,
      "epa_combined_mpge": null,
      "epa_electricity_range_mi": null,
      "image_urls": [
        "https://media.ed.edmunds-media.com/chevrolet/spark/2021/oem/2021_chevrolet_spark_4dr-ha...",
        "https://media.ed.edmunds-media.com/chevrolet/spark/2022/evox/2022_chevrolet_spark_4dr-h..."
      ]
    },
    {
      "id": 401925892,
      "make": "Mitsubishi",
      "model": "Mirage",
      "year": 2022,
      "trim": "ES",
      "trim_description": "ES 4dr Hatchback (1.2L 3cyl 5M)",
      "body_type": "Hatchback",
      "base_msrp": 14645,
      "horsepower_hp": 76,
      "engine_type": "gas",
      "fuel_type": "regular unleaded",
      "drive_type": "front wheel drive",
      "transmission": "5-speed manual",
      "total_seating": 5,
      "epa_combined_mpg": 36,
      "epa_combined_mpge": null,
      "epa_electricity_range_mi": null,
      "image_urls": [
        "https://media.ed.edmunds-media.com/mitsubishi/mirage/2022/oem/2022_mitsubishi_mirage_4d...",
        "https://media.ed.edmunds-media.com/mitsubishi/mirage/2022/evox/2022_mitsubishi_mirage_4..."
      ]
    }
  ]
}

Long text and arrays are shortened in these examples.

Fields

Field	Description
totals	Number of makes, models, trims and colors
by_year	Per model year: trims, models, average price, average horsepower, electric trims
by_body_type	Per body type: trims and average price, most common first
top_horsepower	The 5 most powerful trims, as trim summaries
most_affordable	The 5 cheapest trims, as trim summaries

Health check

Code
GET /health

Code
{
  "status": "ok"
}

Use it for uptime monitoring.

OpenAPI spec

Code
GET /openapi.json

Returns the OpenAPI 3.0 description of the API. You can import it into Postman, Swagger UI or API gateways.