Guides: Vehicle statistics

Vehicle statistics

Count vehicles in one call: how many match a set of filters, and how they split by make, kind, usage, color, model year or registration status.

Count registered passenger cars by make

curl -H "X-Api-Key: $MOTORBAY_API_KEY" \
  "https://api.motorbay.app/v1/statistics/vehicles?kindId=1&registrationStatus=registered&groupBy=make&limit=3"

The answer, shortened, with made-up numbers:

json

{
  "total": 2734520,
  "groupCount": 312,
  "groups": [
    { "make": { "id": "10", "name": "VOLKSWAGEN", "originalName": "VOLKSWAGEN" }, "count": 331208 },
    { "make": { "id": "34", "name": "TOYOTA", "originalName": "TOYOTA" }, "count": 222914 },
    { "make": { "id": "41", "name": "PEUGEOT", "originalName": "PEUGEOT" }, "count": 187455 }
  ]
}

kindId=1 is the id of passenger cars in GET /v1/kinds. Look up the ids you need there, and in /v1/makes, /v1/usages and /v1/colors.

Filters

The filters are the same as in vehicle search, GET /v1/vehicles, and mean the same:

Parameter	Keeps
`makeId`, `kindId`, `usageId`, `colorId`	Vehicles with that make, kind, primary usage or color
`fromModelYear`, `toModelYear`	Model years in the range, both ends included. Vehicles without a model year are left out
`registrationStatus`	`registered`, `deregistered`, `unknown` or `pending`, spelled as a vehicle's `registrationStatus`

registrationStatus works in vehicle search too: GET /v1/vehicles?registrationStatus=registered lists only registered vehicles.

Grouping

groupBy takes one or two of make, kind, usage, color, modelYear and registrationStatus, comma separated. Two fields give one group per combination: groupBy=make,modelYear counts each make per model year.

Each group has only the fields it is grouped by, and count. Makes, kinds, usages and colors come as { "id", "name", "originalName" }, as on a vehicle.
A grouped field is null for the vehicles without that value, for example vehicles with no color recorded. They are a group of their own.
Groups come largest count first. Groups with the same count keep the same order every time.
limit sets how many groups you get, 1 to 1000, and 50 if you leave it out.
total counts every vehicle that matches the filters, and groupCount every group, including those past limit.

Without groupBy the answer is just the total, with "groups": [].

What the numbers describe

The counts come from the weekly extract of Motorstyrelsen's DMR register that we loaded. They are exact for that extract, and equal the totalCount that vehicle search reports for the same filters. They are not a live view of the register. The Motorbay-Data-As-Of header on the answer says which extract they come from, as on every response, and they change only when the next extract is loaded. Motorbay is not affiliated with Motorstyrelsen.

Usage and errors

One call is one request against your rate limit and monthly quota, however many groups it returns.

Status	Code	When
400	`GroupByInvalid`	A field in `groupBy` is not one of the six, or the same field appears twice
400	`GroupByTooMany`	`groupBy` names three or more fields
400	`LimitOutOfRange`	`limit` is below 1 or above 1000
400	`RegistrationStatusInvalid`	`registrationStatus` is not one of the four values

These come as problem details with the code in errors, like every validation error.

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