Copy page

Documentation

Conventions

These rules apply to every endpoint.

Requests

• Every endpoint uses GET.
• No authentication is needed.
• Query parameters are plain strings, for example ?year=2024&sort=-price.
• Text filters such as make, model, body_type and country ignore upper and lower case.
• CORS is open (Access-Control-Allow-Origin: *), so browsers can call the API directly.

Responses

• Every response is JSON.
• Lists come back in a data array.
• Short lists also have a count field.
• Paged lists have a pagination object instead (see below).

IDs

Resource	ID field	Example
Make	id / make_id	1 (Acura)
Model	id / model_id	2 (Acura Integra)
Trim	id	401901022

Trim IDs come from the source dataset and stay the same when the database is rebuilt. Make and model IDs are assigned when the database is built and can change if it is rebuilt from a newer file. Do not store them long term; store names, or trim IDs.

Pagination

GET /api/trims returns results in pages.

Parameter	Default	Limits
page	1	1 or more
limit	20	1 to 100

Code
"pagination": { "page": 1, "limit": 20, "total": 77, "pages": 4 }

Sorting

GET /api/trims accepts a sort parameter. Prefix the field with - to sort in descending order.

Value	Sorts by
price	Base MSRP
year	Model year
make	Make name
model	Model name
horsepower	Horsepower
torque	Torque
mpg	EPA combined MPG
range	EV range
weight	Curb weight
towing	Max towing capacity
seats	Total seating

Trims with no value for the sort field always come last.

Example: ?sort=-horsepower returns the most powerful trims first.

Units

All values use US units. The unit is part of the field name.

Suffix	Unit
_in	inches
_ft	feet
_lbs	pounds
_l	litres
_gal	US gallons
_cu_ft	cubic feet
_mi	miles
_hp	horsepower
_ft_lbs	pound-feet
_rpm	revolutions per minute
_kwh	kilowatt-hours
_hr	hours

Prices (base_msrp, base_invoice) are in US dollars, without cents.

Missing values

If a value is not known, the field is still returned with the value null. For example, gas cars have epa_electricity_range_mi: null and electric cars have epa_combined_mpg: null.