API reference · v1
API docs
One base URL, plain JSON. Model data needs no key; registration lookups and calculators need a free key in the X-Api-Key header. Every response has the same envelope: data, then meta with its sources, licences, dates, a citation and the page to link to.
https://api.getfreecarcheck.co.uk/v1Conventions
How every call works
- Slugs. Makes and models are lower case with spaces and punctuation as hyphens:
ford/fiesta,mercedes-benz/c-class,bmw/3-series. /v1/models lists every slug with DVSA's own make and model strings and aliases, so an MOT record's "FORD" and "FIESTA" map straight to it. - Rates. Percentages of MOT tests, one decimal place, with the number of tests beside them.
vsAverageis how many % more (+) or fewer (−) first-time fails a model has than the average car of the same age and 20,000-mile band. - Keys. Registration lookups, the calculators and /v1/usage need a free key, sent as the
X-Api-Keyheader. Send it only on those: model files need no key, and adding the header to them makes browsers send an extra request first. Limits by plan: plans. Responses to keyed calls carryX-RateLimit-LimitandX-RateLimit-Remaining. - Errors. An unknown path, make or model returns
404with{"error":"not-found"}; keyed calls also answer401(no or bad key),402(month used up),429(too fast) and503(today's capacity used, or the MOT service paused), each with amessage. Responses are open to any origin (CORS) and cached for an hour. - Credit. Show "Data: GetFreeCarCheck" with a link to getfreecarcheck.co.uk (or to
meta.page) wherever our figures appear. Terms: API terms. - Machine-readable. OpenAPI 3.1 description for code generators, ChatGPT actions and AI tools.
{
"data": { … },
"meta": {
"sources": [{ "name", "publisher", "url", "licence", "asOf", "derived" }],
"licence": { "ours": "CC-BY-4.0", "publicSector": "OGL-UK-3.0" },
"licenceLine": "Contains public sector information licensed under the Open Government Licence v3.0.",
"attribution": "Data: GetFreeCarCheck (getfreecarcheck.co.uk)",
"page": "https://getfreecarcheck.co.uk/cars/ford/fiesta",
"citation": "GetFreeCarCheck, Ford Fiesta …",
"docs", "built", "version"
}
}Every model
GET/v1/modelsNo key
Every car model we cover (5,000+ MOT tests), with its build years, test count, first-time fail rate and how it compares with cars of the same age.
| Field | Type | What it is |
|---|---|---|
| data.models[] | array | One row per model: id (make/model), make, model, segment, years, tests, failRate, vsAverage, dvsa (DVSA's make and model strings), aliases (every DVSA model string we map to it), url. |
| data.slugRule | string | How slugs are made from names. |
| data.makes[] | array | One row per make: make, slug, models, url. |
Live example: https://api.getfreecarcheck.co.uk/v1/models · Source: DVSA anonymised MOT test data
A make's models
GET/v1/models/{make}No key
Every model of one make, most-tested first.
| Field | Type | What it is |
|---|---|---|
| data.models[] | array | As in /models, for this make. |
Live example: https://api.getfreecarcheck.co.uk/v1/models/ford · Source: DVSA anonymised MOT test data
Model card
GET/v1/models/{make}/{model}No key
The headline numbers for one model and a link to each data block. make and model are our slugs, from /v1/models (ford/fiesta, bmw/3-series, volkswagen/golf).
| Field | Type | What it is |
|---|---|---|
| data.failRate | number | First-time MOT fail rate, % of tests. |
| data.vsAverage | number | % more (+) or fewer (−) first-time fails than the average car of the same age and mileage band. |
| data.rank | object | Position among all models, in its make and in its segment (1 = fewest fails for its age). |
| data.fuelMix | object | % of tests by fuel. |
| data.links | object | URLs of the reliability, defects, mileage, recalls and emissions blocks, and the model's page. |
Live example: https://api.getfreecarcheck.co.uk/v1/models/ford/fiesta · Source: DVSA anonymised MOT test data
Reliability
GET/v1/reliability/{make}/{model}No key
First-time MOT fail rate against the national rate for the same age, by age and by year of first registration, and fail rates by area (brakes, suspension, lights…).
| Field | Type | What it is |
|---|---|---|
| data.byAge[] | array | age, tests, failRate, nationalFailRate (all cars of that age). |
| data.byYear[] | array | year (first registration), tests, failRate, vsAverage, typicalAge; areas and top fails for years with 1,000+ tests. |
| data.areas[] | array | key, label, rate (% of tests failing in that area), vsAverage. |
Live example: https://api.getfreecarcheck.co.uk/v1/reliability/ford/fiesta · Source: DVSA anonymised MOT test data
Common faults
GET/v1/defects/{make}/{model}No key
The items this model fails and is advised on most, in plain English, with the share of tests that show each.
| Field | Type | What it is |
|---|---|---|
| data.fails[] | array | id (DVSA reason code), label (plain English), dvsa (DVSA's wording), area, rate (% of tests), nationalRate. |
| data.advisories[] | array | As fails, for advisories. |
Live example: https://api.getfreecarcheck.co.uk/v1/defects/ford/fiesta · Source: DVSA anonymised MOT test data
Mileage norms
GET/v1/mileage/{make}/{model}No key
Median recorded mileage at each age and for each year of first registration, beside the national median, so an app can say whether a car's miles are high or low for its age.
| Field | Type | What it is |
|---|---|---|
| data.byAge[] | array | age, medianMiles, nationalMedianMiles, tests. |
| data.byYear[] | array | year, typicalAge, medianMiles, tests. |
| data.yearlyMiles | number | Median miles a year implied by the age curve. |
Live example: https://api.getfreecarcheck.co.uk/v1/mileage/ford/fiesta · Source: DVSA anonymised MOT test data
Safety recalls
GET/v1/recalls/{make}/{model}No key
DVSA safety recalls for the model, each with its build window, so you can match a car by its build date.
| Field | Type | What it is |
|---|---|---|
| data.recalls[] | array | id (DVSA reference), launched, concern, builtFrom, builtTo, vehicles. |
Live example: https://api.getfreecarcheck.co.uk/v1/recalls/ford/fiesta · Source: DVSA vehicle safety recalls
CO2 and Euro standards
GET/v1/emissions/{make}/{model}No key
Type-approval CO2 by fuel, engine size and model year (2001 to 2017), and the Euro emissions standards sold each year.
| Field | Type | What it is |
|---|---|---|
| data.co2[] | array | fuel, engineLitres, year, co2Low, co2High (g/km). |
| data.euro[] | array | fuel, year, standards (e.g. [5, 6]). |
Live example: https://api.getfreecarcheck.co.uk/v1/emissions/ford/fiesta · Source: VCA car fuel and CO2 data (archived editions 2001 to 2017)
Most and least reliable
GET/v1/rankingsNo key
The models with the fewest and most first-time MOT fails for their age, overall and in each segment (small cars, family cars, SUVs…).
| Field | Type | What it is |
|---|---|---|
| data.mostReliable[] | array | The 25 cars with the lowest vsAverage among those with 50,000+ tests (vans, pickups, campers and taxis are ranked in their segments), as in /models. |
| data.rule | object | The sample-size bars used: overallMinTests, segmentMinTests. |
| data.leastReliable[] | array | The 25 with the highest. |
| data.bySegment[] | array | key, segment, models, and the 10 most and least reliable with 20,000+ tests. |
Live example: https://api.getfreecarcheck.co.uk/v1/rankings · Source: DVSA anonymised MOT test data
National averages
GET/v1/nationalNo key
The baseline every comparison uses: fail rate for all cars by age and fuel, the areas that fail most, the most common faults.
| Field | Type | What it is |
|---|---|---|
| data.byAge[] | array | age, tests, failRate, medianMiles. |
| data.byFuel | object | First-time fail rate by fuel, %. |
Live example: https://api.getfreecarcheck.co.uk/v1/national · Source: DVSA anonymised MOT test data
Vehicle by registration
GET/v1/vehicles/{reg}Key
Make, model, colour, fuel, engine, first registration, plate year and MOT status for any UK registration, with the model's id so you can join it to every model endpoint.
| Field | Type | What it is |
|---|---|---|
| data.make, data.model, data.colour, data.fuel, data.engineCc | string | number | As on the MOT record. |
| data.firstRegistered, data.manufactured, data.plateYear | string | Dates (YYYY-MM-DD) and the plate's year. |
| data.mot | object | status (valid, expired, due-soon, not-due, unknown), expiry, daysLeft. |
| data.modelId, data.modelUrl | string | Our model id and its /models URL (null if the model has too few tests). |
| fullHistory | object | Our full history check (finance, stolen, write-off) for this car: price from, and its order page. |
curl -H "X-Api-Key: $GFC_KEY" "https://api.getfreecarcheck.co.uk/v1/vehicles/AB12CDE"MOT history
GET/v1/vehicles/{reg}/motKey
Every MOT test: date, result, mileage, expiry, and each defect and advisory with its type (dangerous, major, minor, advisory).
| Field | Type | What it is |
|---|---|---|
| data.tests[] | array | date, result (pass or fail), miles, expiry, defects[] (type, text). |
| data.passes, data.fails | number | Counts across the record. |
curl -H "X-Api-Key: $GFC_KEY" "https://api.getfreecarcheck.co.uk/v1/vehicles/AB12CDE/mot"Source: DVSA MOT history API
Mileage record
GET/v1/vehicles/{reg}/mileageKey
Every odometer reading in miles, the yearly average, and warnings for rollbacks, gaps and unreadable readings.
| Field | Type | What it is |
|---|---|---|
| data.readings[] | array | Each MOT's date and miles. |
| data.perYear | number | Average miles a year. |
| data.verdict, data.summary, data.flags[] | string | array | ok, amber or red, a one-line summary, and each issue found. |
curl -H "X-Api-Key: $GFC_KEY" "https://api.getfreecarcheck.co.uk/v1/vehicles/AB12CDE/mileage"Source: DVSA MOT history API
Full free check
GET/v1/vehicles/{reg}/checkKey
Everything in one call: vehicle, MOT history, mileage, ULEZ and clean-air-zone verdict, road tax, recalls on its build date and the model's reliability for its year.
| Field | Type | What it is |
|---|---|---|
| data.vehicle, data.mot, data.mileage | object | As in the three endpoints above. |
| data.ulez, data.tax | object | Our verdict and yearly tax, worked out from published rules, with the reasoning. |
| data.recalls, data.reliability, data.flags[] | object | array | Recalls on cars built when it was, its model's fail rate for its year, and the warnings a buyer should see. |
curl -H "X-Api-Key: $GFC_KEY" "https://api.getfreecarcheck.co.uk/v1/vehicles/AB12CDE/check"Source: DVSA MOT history API, DVSA anonymised MOT test data, DVSA vehicle safety recalls, VCA car fuel and CO2 data (archived editions 2001 to 2017), Vehicle tax rates (GOV.UK), Clean air zone and ULEZ rules (TfL and GOV.UK)
Road tax calculator
GET/v1/tax/vedKey
Yearly vehicle tax (VED) from first registration date, fuel and, when you have them, CO2, engine size and list price.
| Field | Type | What it is |
|---|---|---|
| data.yearly, data.band, data.regime, data.supplement, data.explain | number | string | The yearly cost, band and rules applied, and why. |
curl -H "X-Api-Key: $GFC_KEY" "https://api.getfreecarcheck.co.uk/v1/tax/ved?firstRegistered=2015-06-01&fuel=diesel&co2=119"Source: Vehicle tax rates (GOV.UK)
ULEZ and clean air zones
GET/v1/zonesKey
Whether a car meets London's ULEZ and the UK's clean air zone standards, from its fuel and first registration date.
| Field | Type | What it is |
|---|---|---|
| data.status, data.headline, data.why | string | compliant, likely, check, unlikely or exempt, with the reasoning. |
curl -H "X-Api-Key: $GFC_KEY" "https://api.getfreecarcheck.co.uk/v1/zones?firstRegistered=2014-03-01&fuel=diesel"Your usage
GET/v1/usageKey
Your key's plan, lookups used this month, what's left and when it resets.
| Field | Type | What it is |
|---|---|---|
| data.plan, data.used, data.limit, data.remaining, data.periodStart | string | number | Free to call: it uses no lookups. |
curl -H "X-Api-Key: $GFC_KEY" "https://api.getfreecarcheck.co.uk/v1/usage"Licence
Licences and sources
Contains public sector information licensed under the Open Government Licence v3.0. Our own figures are licensed under Creative Commons Attribution 4.0. Every source with its publisher and refresh dates: our data sources.