Guides: Units

Units

Motorbay serves Motorstyrelsen's numbers in the units they are recorded in: kg, mm, kW, cm³, km/h, km/l, g/km, Wh/km, mg/km, and the odometer in thousands of km. Each field's unit is in the API reference. If you'd rather have pounds, inches, miles per gallon or horsepower, ask for them, and every answer with a measured value gets a converted object next to the raw fields.

Ask for imperial units

curl -H "X-Api-Key: $MOTORBAY_API_KEY" \
  "https://api.motorbay.app/v1/vehicles/9000000006320919/engine?units=imperial&power=hp"

json

{
  "maximumPower": 100,
  "displacement": 1998,
  "odometerReading": 228,
  "converted": {
    "maximumPower": { "value": 134.1, "unit": "hp" },
    "displacement": { "value": 121.9, "unit": "in3" },
    "odometerReading": { "value": 141.7, "unit": "thousandMi" }
  }
}

Shortened. The raw fields never change: maximumPower is kW whatever you ask for. converted holds every field with a unit, each as { "value", "unit" }, so you never have to guess which unit a number is in. A value that isn't recorded is { "value": null, "unit": "lb" }.

The parameters

Parameter	Values	Default
`units`	`metric`, `imperial`	`metric`
`power`	`kw`, `hp`	`kw`
`mpg`	`us`, `uk`	`us`, and only with `units=imperial`

Without any of them, or with units=metric, the answer is the same as it has always been, with no converted.
power works with either system: units=metric&power=hp keeps kg and km and gives the power in hp.
A value not in the table, or mpg without units=imperial, is a 400 with the code ValidationFailed and UnitsInvalid in errors.

They work on /engine, /technical-details, /environmental-information, /inspection and /fuel-types, and on the vehicle lookups (/v1/vehicles/{id}, /plate/{plate}, /vin/{vin} and /lookup/{plateOrVin}) for the parts include adds.

What is converted

Fields	Recorded in	With `units=imperial`
Weights and axle loads on `/technical-details`	kg	`lb`
Wheelbase and track widths	mm	`in`
Top speed	km/h	`mph`
Displacement	cm³	`in3`
Odometer on `/engine` and `/inspection`	1,000 km	`thousandMi`
Fuel efficiency on `/fuel-types`	km/l	`mpgUs`, or `mpgUk` with `mpg=uk`
CO₂ on `/fuel-types`	g/km	`gPerMi`
Electric consumption	Wh/km	`whPerMi`
CO, HC+NOx, NOx and particles	mg/km	`mgPerMi`
Maximum power	kW	`hp` with `power=hp`, in either system

Converted values are rounded half away from zero, to 1 decimal, and emissions to 2 because particle figures are small. A value left in its raw unit, such as kw without power=hp, is passed through as recorded. Noise (dB), engine speeds (rpm), smoke density and the heavy-duty CO₂ figure in g/tkm are not converted.

Two kinds of horsepower

power=hp is mechanical horsepower, 745.7 W: 100 kW is 134.1 hp, the figure used in the US and the UK. horsepower on /v1/vehicles/{vehicleId}/calculated is metric horsepower (hk or PS), 735.5 W, rounded to a whole number: 136 for the same engine, the figure Danish and German car ads use. Both come from the same maximumPower, so neither is wrong. Pick the one your users expect.

Calculated by Motorbay

Converted values are calculated by Motorbay from the raw fields, with the exact definitions (1 lb is 0.45359237 kg, 1 in is 25.4 mm, 1 mi is 1.609344 km, a US gallon is 3.785411784 l and a UK gallon 4.54609 l). They are not in Motorstyrelsen's extract. A request with units counts as one request, the same as without.

Didn't find the answer? Email support@motorbay.app.