{
 "openapi": "3.1.0",
 "info": {
  "title": "GetFreeCarCheck API",
  "version": "1.0.0",
  "summary": "UK car reliability, common faults, mileage norms, recalls and emissions from over 100 million DVSA MOT tests.",
  "description": "Model data is open: no key, CORS on, JSON. Registration lookups and calculators need a free key (X-Api-Key header); send the key only on those. Every response carries meta.sources (name, publisher, licence, asOf), meta.page and meta.citation. Slugs are lower case with spaces and punctuation as hyphens (\"MERCEDES-BENZ\" → mercedes-benz, \"3 SERIES\" → 3-series). Match DVSA's own make and model strings with dvsa and aliases. Contains public sector information licensed under the Open Government Licence v3.0.",
  "contact": {
   "name": "GetFreeCarCheck",
   "url": "https://getfreecarcheck.co.uk/developers",
   "email": "hello@getfreecarcheck.co.uk"
  },
  "license": {
   "name": "CC BY 4.0 (our figures); OGL v3.0 (the public sector information under them)",
   "identifier": "CC-BY-4.0"
  },
  "termsOfService": "https://getfreecarcheck.co.uk/terms#api"
 },
 "externalDocs": {
  "url": "https://getfreecarcheck.co.uk/developers/docs"
 },
 "servers": [
  {
   "url": "https://api.getfreecarcheck.co.uk/v1"
  }
 ],
 "paths": {
  "/models": {
   "get": {
    "operationId": "models",
    "summary": "Every model",
    "description": "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. Sources: DVSA anonymised MOT test data.",
    "parameters": [],
    "responses": {
     "200": {
      "description": "data.models[]: 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: How slugs are made from names. data.makes[]: One row per make: make, slug, models, url.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Envelope"
        }
       }
      }
     },
     "404": {
      "description": "No such make or model.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   }
  },
  "/models/{make}": {
   "get": {
    "operationId": "make",
    "summary": "A make's models",
    "description": "Every model of one make, most-tested first. Sources: DVSA anonymised MOT test data.",
    "parameters": [
     {
      "name": "make",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "Make slug, e.g. ford"
     }
    ],
    "responses": {
     "200": {
      "description": "data.models[]: As in /models, for this make.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Envelope"
        }
       }
      }
     },
     "404": {
      "description": "No such make or model.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   }
  },
  "/models/{make}/{model}": {
   "get": {
    "operationId": "model",
    "summary": "Model card",
    "description": "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). Sources: DVSA anonymised MOT test data.",
    "parameters": [
     {
      "name": "make",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "Make slug, e.g. ford"
     },
     {
      "name": "model",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "Model slug, e.g. fiesta"
     }
    ],
    "responses": {
     "200": {
      "description": "data.failRate: First-time MOT fail rate, % of tests. data.vsAverage: % more (+) or fewer (−) first-time fails than the average car of the same age and mileage band. data.rank: Position among all models, in its make and in its segment (1 = fewest fails for its age). data.fuelMix: % of tests by fuel. data.links: URLs of the reliability, defects, mileage, recalls and emissions blocks, and the model's page.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Envelope"
        }
       }
      }
     },
     "404": {
      "description": "No such make or model.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   }
  },
  "/reliability/{make}/{model}": {
   "get": {
    "operationId": "reliability",
    "summary": "Reliability",
    "description": "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…). Sources: DVSA anonymised MOT test data.",
    "parameters": [
     {
      "name": "make",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "Make slug, e.g. ford"
     },
     {
      "name": "model",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "Model slug, e.g. fiesta"
     }
    ],
    "responses": {
     "200": {
      "description": "data.byAge[]: age, tests, failRate, nationalFailRate (all cars of that age). data.byYear[]: year (first registration), tests, failRate, vsAverage, typicalAge; areas and top fails for years with 1,000+ tests. data.areas[]: key, label, rate (% of tests failing in that area), vsAverage.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Envelope"
        }
       }
      }
     },
     "404": {
      "description": "No such make or model.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   }
  },
  "/defects/{make}/{model}": {
   "get": {
    "operationId": "defects",
    "summary": "Common faults",
    "description": "The items this model fails and is advised on most, in plain English, with the share of tests that show each. Sources: DVSA anonymised MOT test data.",
    "parameters": [
     {
      "name": "make",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "Make slug, e.g. ford"
     },
     {
      "name": "model",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "Model slug, e.g. fiesta"
     }
    ],
    "responses": {
     "200": {
      "description": "data.fails[]: id (DVSA reason code), label (plain English), dvsa (DVSA's wording), area, rate (% of tests), nationalRate. data.advisories[]: As fails, for advisories.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Envelope"
        }
       }
      }
     },
     "404": {
      "description": "No such make or model.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   }
  },
  "/mileage/{make}/{model}": {
   "get": {
    "operationId": "mileage",
    "summary": "Mileage norms",
    "description": "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. Sources: DVSA anonymised MOT test data.",
    "parameters": [
     {
      "name": "make",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "Make slug, e.g. ford"
     },
     {
      "name": "model",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "Model slug, e.g. fiesta"
     }
    ],
    "responses": {
     "200": {
      "description": "data.byAge[]: age, medianMiles, nationalMedianMiles, tests. data.byYear[]: year, typicalAge, medianMiles, tests. data.yearlyMiles: Median miles a year implied by the age curve.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Envelope"
        }
       }
      }
     },
     "404": {
      "description": "No such make or model.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   }
  },
  "/recalls/{make}/{model}": {
   "get": {
    "operationId": "recalls",
    "summary": "Safety recalls",
    "description": "DVSA safety recalls for the model, each with its build window, so you can match a car by its build date. Sources: DVSA vehicle safety recalls.",
    "parameters": [
     {
      "name": "make",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "Make slug, e.g. ford"
     },
     {
      "name": "model",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "Model slug, e.g. fiesta"
     }
    ],
    "responses": {
     "200": {
      "description": "data.recalls[]: id (DVSA reference), launched, concern, builtFrom, builtTo, vehicles.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Envelope"
        }
       }
      }
     },
     "404": {
      "description": "No such make or model.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   }
  },
  "/emissions/{make}/{model}": {
   "get": {
    "operationId": "emissions",
    "summary": "CO2 and Euro standards",
    "description": "Type-approval CO2 by fuel, engine size and model year (2001 to 2017), and the Euro emissions standards sold each year. Sources: VCA car fuel and CO2 data (archived editions 2001 to 2017).",
    "parameters": [
     {
      "name": "make",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "Make slug, e.g. ford"
     },
     {
      "name": "model",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "Model slug, e.g. fiesta"
     }
    ],
    "responses": {
     "200": {
      "description": "data.co2[]: fuel, engineLitres, year, co2Low, co2High (g/km). data.euro[]: fuel, year, standards (e.g. [5, 6]).",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Envelope"
        }
       }
      }
     },
     "404": {
      "description": "No such make or model.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   }
  },
  "/rankings": {
   "get": {
    "operationId": "rankings",
    "summary": "Most and least reliable",
    "description": "The models with the fewest and most first-time MOT fails for their age, overall and in each segment (small cars, family cars, SUVs…). Sources: DVSA anonymised MOT test data.",
    "parameters": [],
    "responses": {
     "200": {
      "description": "data.mostReliable[]: 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: The sample-size bars used: overallMinTests, segmentMinTests. data.leastReliable[]: The 25 with the highest. data.bySegment[]: key, segment, models, and the 10 most and least reliable with 20,000+ tests.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Envelope"
        }
       }
      }
     },
     "404": {
      "description": "No such make or model.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   }
  },
  "/national": {
   "get": {
    "operationId": "national",
    "summary": "National averages",
    "description": "The baseline every comparison uses: fail rate for all cars by age and fuel, the areas that fail most, the most common faults. Sources: DVSA anonymised MOT test data.",
    "parameters": [],
    "responses": {
     "200": {
      "description": "data.byAge[]: age, tests, failRate, medianMiles. data.byFuel: First-time fail rate by fuel, %.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Envelope"
        }
       }
      }
     },
     "404": {
      "description": "No such make or model.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     }
    }
   }
  },
  "/vehicles/{reg}": {
   "get": {
    "operationId": "vehicle",
    "summary": "Vehicle by registration",
    "description": "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. Sources: DVSA MOT history API, DVSA anonymised MOT test data.",
    "security": [
     {
      "apiKey": []
     }
    ],
    "parameters": [
     {
      "name": "reg",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "UK registration, spaces optional, e.g. AB12CDE"
     }
    ],
    "responses": {
     "200": {
      "description": "data.make, data.model, data.colour, data.fuel, data.engineCc: As on the MOT record. data.firstRegistered, data.manufactured, data.plateYear: Dates (YYYY-MM-DD) and the plate's year. data.mot: status (valid, expired, due-soon, not-due, unknown), expiry, daysLeft. data.modelId, data.modelUrl: Our model id and its /models URL (null if the model has too few tests). fullHistory: Our full history check (finance, stolen, write-off) for this car: price from, and its order page.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Envelope"
        }
       }
      }
     },
     "401": {
      "description": "No key, or the key isn't active."
     },
     "402": {
      "description": "The key's monthly lookups are used up."
     },
     "404": {
      "description": "No MOT record for that registration.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "429": {
      "description": "Too many requests in 10 seconds."
     },
     "503": {
      "description": "Today's capacity is used, or the MOT history service is paused."
     }
    }
   }
  },
  "/vehicles/{reg}/mot": {
   "get": {
    "operationId": "vehicle-mot",
    "summary": "MOT history",
    "description": "Every MOT test: date, result, mileage, expiry, and each defect and advisory with its type (dangerous, major, minor, advisory). Sources: DVSA MOT history API.",
    "security": [
     {
      "apiKey": []
     }
    ],
    "parameters": [
     {
      "name": "reg",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "UK registration, spaces optional, e.g. AB12CDE"
     }
    ],
    "responses": {
     "200": {
      "description": "data.tests[]: date, result (pass or fail), miles, expiry, defects[] (type, text). data.passes, data.fails: Counts across the record.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Envelope"
        }
       }
      }
     },
     "401": {
      "description": "No key, or the key isn't active."
     },
     "402": {
      "description": "The key's monthly lookups are used up."
     },
     "404": {
      "description": "No MOT record for that registration.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "429": {
      "description": "Too many requests in 10 seconds."
     },
     "503": {
      "description": "Today's capacity is used, or the MOT history service is paused."
     }
    }
   }
  },
  "/vehicles/{reg}/mileage": {
   "get": {
    "operationId": "vehicle-mileage",
    "summary": "Mileage record",
    "description": "Every odometer reading in miles, the yearly average, and warnings for rollbacks, gaps and unreadable readings. Sources: DVSA MOT history API.",
    "security": [
     {
      "apiKey": []
     }
    ],
    "parameters": [
     {
      "name": "reg",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "UK registration, spaces optional, e.g. AB12CDE"
     }
    ],
    "responses": {
     "200": {
      "description": "data.readings[]: Each MOT's date and miles. data.perYear: Average miles a year. data.verdict, data.summary, data.flags[]: ok, amber or red, a one-line summary, and each issue found.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Envelope"
        }
       }
      }
     },
     "401": {
      "description": "No key, or the key isn't active."
     },
     "402": {
      "description": "The key's monthly lookups are used up."
     },
     "404": {
      "description": "No MOT record for that registration.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "429": {
      "description": "Too many requests in 10 seconds."
     },
     "503": {
      "description": "Today's capacity is used, or the MOT history service is paused."
     }
    }
   }
  },
  "/vehicles/{reg}/check": {
   "get": {
    "operationId": "vehicle-check",
    "summary": "Full free check",
    "description": "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. Sources: 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).",
    "security": [
     {
      "apiKey": []
     }
    ],
    "parameters": [
     {
      "name": "reg",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "UK registration, spaces optional, e.g. AB12CDE"
     }
    ],
    "responses": {
     "200": {
      "description": "data.vehicle, data.mot, data.mileage: As in the three endpoints above. data.ulez, data.tax: Our verdict and yearly tax, worked out from published rules, with the reasoning. data.recalls, data.reliability, data.flags[]: Recalls on cars built when it was, its model's fail rate for its year, and the warnings a buyer should see.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Envelope"
        }
       }
      }
     },
     "401": {
      "description": "No key, or the key isn't active."
     },
     "402": {
      "description": "The key's monthly lookups are used up."
     },
     "404": {
      "description": "No MOT record for that registration.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "429": {
      "description": "Too many requests in 10 seconds."
     },
     "503": {
      "description": "Today's capacity is used, or the MOT history service is paused."
     }
    }
   }
  },
  "/tax/ved": {
   "get": {
    "operationId": "tax",
    "summary": "Road tax calculator",
    "description": "Yearly vehicle tax (VED) from first registration date, fuel and, when you have them, CO2, engine size and list price. Sources: Vehicle tax rates (GOV.UK).",
    "security": [
     {
      "apiKey": []
     }
    ],
    "parameters": [
     {
      "name": "firstRegistered",
      "in": "query",
      "required": true,
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "fuel",
      "in": "query",
      "required": true,
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "co2",
      "in": "query",
      "required": false,
      "schema": {
       "type": "number"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "data.yearly, data.band, data.regime, data.supplement, data.explain: The yearly cost, band and rules applied, and why.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Envelope"
        }
       }
      }
     },
     "401": {
      "description": "No key, or the key isn't active."
     },
     "402": {
      "description": "The key's monthly lookups are used up."
     },
     "404": {
      "description": "No MOT record for that registration.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "429": {
      "description": "Too many requests in 10 seconds."
     },
     "503": {
      "description": "Today's capacity is used, or the MOT history service is paused."
     }
    }
   }
  },
  "/zones": {
   "get": {
    "operationId": "zones",
    "summary": "ULEZ and clean air zones",
    "description": "Whether a car meets London's ULEZ and the UK's clean air zone standards, from its fuel and first registration date. Sources: Clean air zone and ULEZ rules (TfL and GOV.UK).",
    "security": [
     {
      "apiKey": []
     }
    ],
    "parameters": [
     {
      "name": "firstRegistered",
      "in": "query",
      "required": true,
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "fuel",
      "in": "query",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "data.status, data.headline, data.why: compliant, likely, check, unlikely or exempt, with the reasoning.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Envelope"
        }
       }
      }
     },
     "401": {
      "description": "No key, or the key isn't active."
     },
     "402": {
      "description": "The key's monthly lookups are used up."
     },
     "404": {
      "description": "No MOT record for that registration.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "429": {
      "description": "Too many requests in 10 seconds."
     },
     "503": {
      "description": "Today's capacity is used, or the MOT history service is paused."
     }
    }
   }
  },
  "/usage": {
   "get": {
    "operationId": "usage",
    "summary": "Your usage",
    "description": "Your key's plan, lookups used this month, what's left and when it resets. Sources: .",
    "security": [
     {
      "apiKey": []
     }
    ],
    "parameters": [],
    "responses": {
     "200": {
      "description": "data.plan, data.used, data.limit, data.remaining, data.periodStart: Free to call: it uses no lookups.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Envelope"
        }
       }
      }
     },
     "401": {
      "description": "No key, or the key isn't active."
     },
     "402": {
      "description": "The key's monthly lookups are used up."
     },
     "404": {
      "description": "No MOT record for that registration.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Error"
        }
       }
      }
     },
     "429": {
      "description": "Too many requests in 10 seconds."
     },
     "503": {
      "description": "Today's capacity is used, or the MOT history service is paused."
     }
    }
   }
  }
 },
 "components": {
  "securitySchemes": {
   "apiKey": {
    "type": "apiKey",
    "in": "header",
    "name": "X-Api-Key",
    "description": "Free by email: https://getfreecarcheck.co.uk/developers#key"
   }
  },
  "schemas": {
   "Envelope": {
    "type": "object",
    "required": [
     "data",
     "meta"
    ],
    "properties": {
     "data": {
      "type": [
       "object",
       "null"
      ]
     },
     "meta": {
      "type": "object",
      "properties": {
       "sources": {
        "type": "array",
        "items": {
         "type": "object",
         "properties": {
          "name": {
           "type": "string"
          },
          "publisher": {
           "type": "string"
          },
          "url": {
           "type": "string"
          },
          "licence": {
           "type": "string"
          },
          "asOf": {
           "type": [
            "string",
            "null"
           ]
          },
          "derived": {
           "type": "boolean"
          }
         }
        }
       },
       "licence": {
        "type": "object"
       },
       "licenceLine": {
        "type": "string"
       },
       "attribution": {
        "type": "string"
       },
       "page": {
        "type": "string",
        "description": "The page a person should be sent to."
       },
       "citation": {
        "type": "string"
       },
       "docs": {
        "type": "string"
       },
       "built": {
        "type": "string"
       },
       "version": {
        "type": "string"
       }
      }
     }
    }
   },
   "Error": {
    "type": "object",
    "properties": {
     "error": {
      "type": "string"
     },
     "docs": {
      "type": "string"
     }
    }
   }
  }
 }
}