Cars API

Frequently Asked Questions

• Can I use the Cars API for commercial purposes?

  Yes, but you must have a premium subscription. Commercial use of the Cars API is not permitted on the free tier. See our pricing page to choose a plan that fits your needs.

• How do I get an API key and start using the Cars API?

  Sign up for a free account to instantly get your API key, then pass it in the X-Api-Key header on every request. The documentation above includes ready-to-run examples in cURL, Python, JavaScript, Node.js, and more.

• What happens if I exceed my quota for the month?

  Your API requests will simply be denied once you hit your monthly quota — you will never be charged more than the plan you signed up for. To increase your quota, you can upgrade your plan any time on our pricing page.

• What happens if a request to the Cars API fails?

  The API responds with a standard HTTP status code and a JSON error message describing the problem. See our error codes reference for the full list of codes and how to resolve each one, or contact support if you need help.

• How do I build make, model, generation and engine dropdowns?

  Two ways. For a classic cascade, call /v2/carmakes, then /v2/carmodels with a make, then /v2/cargenerations for the generation or chassis code (for example E90 on a BMW 3 Series). Faster is /v2/carfacets, which returns the available values and counts for every dimension in a single request and narrows them as the user chooses - so a dependent dropdown does not need one call per level. Everything is looked up by name: make=bmw&model=3-series, with case and punctuation ignored. /v2/carmakes, /v2/carmodels and /v2/carfacets are available on the free tier.

• How do I search for cars without walking the hierarchy?

  Use /v2/cars, which searches the whole catalogue with any combination of filters and needs no generation, model or id first. For example /v2/cars?body=Wagon&fuel=diesel&min_power_hp=150&max_power_hp=200&min_year=2010 returns every diesel wagon between 150 and 200 hp still in production from 2010. Filters include make, model, generation, chassis_code, body, doors, badge, fuel, transmission, drive, cylinders, engine_code, power and year ranges, plus sort, limit and offset. The total number of matches is returned in the X-Total-Count response header.

• Why does one badge such as 320d return several cars?

  Because a model designation is not unique within a generation. In the BMW E90 alone, 320d covers both 163 hp and 177 hp engines in manual and automatic, across four body styles. /v2/cars therefore returns each car separately, with badge, power_hp, transmission, drive, fuel, body and displacement_l as separate fields, so every result is distinguishable on sight. Use /v2/carfacets?facets=badge to get one row per designation with a count when you want a compact dropdown.

• Why is chassis_codes an array rather than a single code?

  Because a generation genuinely covers several codes. BMW uses E90 for the saloon, E91 for the Touring, E92 for the coupe and E93 for the convertible, and the source data does not record which code belongs to which body - Mercedes ships three codes across seven bodies, and Volkswagen's Mk5 and A5 are two names for one generation rather than two bodies. Rather than guess, the whole set is attached to the generation and no individual car claims one code. Filtering by chassis_code=E91 still works: it matches any generation whose set contains that code.

• Do I need a second call to get a car's specifications?

  No. /v2/cars returns the full specification sheet with every car, whether you searched for it or fetched it by id - dozens of attributes covering engine power, torque, fuel consumption, dimensions, curb weight and seating capacity. Values keep their unit as a separate field, for example {"value": 1995, "unit": "cm3"}, so they can be compared and sorted without parsing strings. Because each car carries a sheet of roughly 2 KB, the default limit is 10; raise it up to 100 when you need more. Pass ids to fetch up to 50 known cars at once - request order is preserved and a handle matching nothing comes back as null.

• Are the car ids stable enough to store in my own database?

  Yes. Each car carries an id such as car_e71ff3416a, derived deterministically from the vehicle's own identity rather than from row order, so it survives our periodic data refreshes. Storing that id against a customer's vehicle is the intended pattern. An id only changes if the underlying car's identity genuinely changes, so treat a 404 from /v2/cars?id= as a prompt to re-resolve from make, model and generation. No other identifiers are needed anywhere in the API - every other lookup takes a plain name.

• Can I select a car by its chassis or development code, such as E90 or W204?

  Yes, where the manufacturer publishes one. /v2/cargenerations returns chassis_codes for each generation, and both /v2/cargenerations and /v2/cars accept chassis_code as a filter. Coverage varies sharply by brand: above 70% for BMW, Mercedes-Benz and Audi, around 45-57% for Toyota and Nissan, and close to zero for several volume brands. Where no code exists, chassis_code is null and the ordinal field carries the generation number instead.

• What are some use cases for the Cars API?

  It powers automotive marketplaces, parts-fitment and vehicle-selection dropdowns, comparison tools, fleet and insurance apps, and research projects needing specs across tens of thousands of models from over four hundred automakers. For EV-specific data see the Electric Vehicle API, or the Motorcycles API for two-wheelers.