api-ninjas-com Cars API

openapi: 3.2.0
info:
  title: Ninjas Cars API
  description: 'Combined OpenAPI specification for every API Ninjas endpoint. Requests go to https://api.api-ninjas.com with an `X-Api-Key` header; get a free key at https://api-ninjas.com/register. Human-readable docs: https://api-ninjas.com/api. Index for LLMs: https://api-ninjas.com/llms.txt.'
  version: 1.0.0
  contact:
    name: API Ninjas
    url: https://api-ninjas.com
  license:
    name: Proprietary
servers:
- url: https://api.api-ninjas.com
  description: API Ninjas Production
security:
- ApiKeyAuth: []
tags:
- name: Cars
  description: Specifications for cars from over 400 automakers. Look-ups are by name -- make=bmw&model=3-series -- and every car carries a handle you can store. /v2/cars answers a whole question in one call and always returns full specifications; /v2/carfacets builds dependent dropdowns without one request per level.
paths:
  /v2/cars:
    get:
      summary: Find cars, or fetch known cars by id. Always returns full specifications.
      description: The main endpoint. Search the whole catalogue by any combination of filters, or fetch cars you already know with id/ids. Every car is returned with its complete specification sheet attached, so no second call is needed. Each row also carries its own make, model, generation, body and engine context. At least one filter, or an id, is required. The total number of matches is returned in the X-Total-Count response header. Requires a paid plan (Premium).
      parameters:
      - name: id
        in: query
        required: false
        schema:
          type: string
        description: 'A car handle from a previous search, e.g. car_e71ff3416a. Safe to store: it is derived from the car''s identity and survives data refreshes.'
      - name: ids
        in: query
        required: false
        schema:
          type: string
        description: Comma-separated car handles, at most 50. Request order is preserved and a handle matching nothing is returned as null.
      - name: make
        in: query
        required: false
        schema:
          type: string
        description: Manufacturer, as a word. Case and punctuation are ignored, so bmw, BMW and Bmw all resolve.
      - name: model
        in: query
        required: false
        schema:
          type: string
        description: Model, as a word. '3 Series', '3-series' and '3series' all resolve.
      - name: generation
        in: query
        required: false
        schema:
          type: string
        description: Generation, as a word, e.g. e90 or 'E90/E91/E92/E93'. Optional -- nothing requires going through a generation.
      - name: chassis_code
        in: query
        required: false
        schema:
          type: string
        description: Filter to one chassis code, e.g. E91. Matches anything whose chassis_codes contains it.
      - name: body
        in: query
        required: false
        schema:
          type: string
          enum:
          - Sedan
          - Coupe
          - Convertible
          - Wagon
          - Hatchback
          - Liftback
          - SUV
          - MPV
          - Van
          - Pickup
        description: Body style. One of Sedan, Coupe, Convertible, Wagon, Hatchback, Liftback, SUV, MPV, Van, Pickup.
      - name: doors
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 6
        description: Number of doors.
      - name: badge
        in: query
        required: false
        schema:
          type: string
        description: Model designation, e.g. 320d. Spacing and case are ignored.
      - name: fuel
        in: query
        required: false
        schema:
          type: string
          enum:
          - gasoline
          - diesel
          - electric
          - hybrid
          - plugin_hybrid
          - lpg
          - cng
          - hydrogen
          - ethanol
        description: Fuel type.
      - name: transmission
        in: query
        required: false
        schema:
          type: string
          enum:
          - manual
          - automatic
          - cvt
          - dual_clutch
          - automated_manual
          - single_speed
        description: Transmission type.
      - name: drive
        in: query
        required: false
        schema:
          type: string
          enum:
          - fwd
          - rwd
          - awd
          - 4wd
        description: Driven wheels.
      - name: cylinders
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 20
        description: Number of cylinders.
      - name: engine_code
        in: query
        required: false
        schema:
          type: string
        description: Manufacturer engine code.
      - name: min_power_hp
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
        description: Minimum engine power in horsepower.
      - name: max_power_hp
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
        description: Maximum engine power in horsepower.
      - name: min_year
        in: query
        required: false
        schema:
          type: integer
        description: Cars still in production in or after this year.
      - name: max_year
        in: query
        required: false
        schema:
          type: integer
        description: Cars in production in or before this year.
      - name: year
        in: query
        required: false
        schema:
          type: integer
        description: Cars in production in this year. A filter, not a starting point.
      - name: sort
        in: query
        required: false
        schema:
          type: string
          enum:
          - power_hp
          - -power_hp
          - year
          - -year
          - name
          - make
        description: Sort order.
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 10
        description: How many results to return, between 1 and 100. Default 10 -- each car carries a full specification sheet of roughly 2 KB. A value outside the range is rejected rather than silently clamped.
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          default: 0
        description: Number of results to skip, for pagination. Default 0.
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Car'
        '400':
          $ref: '#/components/responses/CarsOpenapi_BadRequest'
        '401':
          $ref: '#/components/responses/CarsOpenapi_Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
      tags:
      - Cars
      operationId: getV2Cars
      x-operation-id-source: derived
  /v2/carfacets:
    get:
      summary: Available values and counts for each dimension, given a selection
      description: Builds every dependent dropdown in one request instead of one request per level. Facets narrow with whatever is already selected. Available on every plan, including Free.
      parameters:
      - name: facets
        in: query
        required: false
        schema:
          type: string
        description: 'Comma-separated dimensions to count, at most 6. One of: make, model, generation, chassis_code, body, doors, fuel, transmission, drive, cylinders, year, badge.'
      - name: make
        in: query
        required: false
        schema:
          type: string
        description: Manufacturer, as a word. Case and punctuation are ignored, so bmw, BMW and Bmw all resolve.
      - name: model
        in: query
        required: false
        schema:
          type: string
        description: Model, as a word. '3 Series', '3-series' and '3series' all resolve.
      - name: generation
        in: query
        required: false
        schema:
          type: string
        description: Generation, as a word.
      - name: body
        in: query
        required: false
        schema:
          type: string
          enum:
          - Sedan
          - Coupe
          - Convertible
          - Wagon
          - Hatchback
          - Liftback
          - SUV
          - MPV
          - Van
          - Pickup
        description: Body style.
      - name: doors
        in: query
        required: false
        schema:
          type: integer
        description: Number of doors.
      - name: fuel
        in: query
        required: false
        schema:
          type: string
          enum:
          - gasoline
          - diesel
          - electric
          - hybrid
          - plugin_hybrid
          - lpg
          - cng
          - hydrogen
          - ethanol
        description: Fuel type.
      - name: transmission
        in: query
        required: false
        schema:
          type: string
          enum:
          - manual
          - automatic
          - cvt
          - dual_clutch
          - automated_manual
          - single_speed
        description: Transmission type.
      - name: drive
        in: query
        required: false
        schema:
          type: string
          enum:
          - fwd
          - rwd
          - awd
          - 4wd
        description: Driven wheels.
      - name: cylinders
        in: query
        required: false
        schema:
          type: integer
        description: Number of cylinders.
      - name: year
        in: query
        required: false
        schema:
          type: integer
        description: Cars in production in this year.
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                properties:
                  make:
                    type: array
                    items:
                      $ref: '#/components/schemas/FacetValue'
                    description: Available manufacturers and how many cars in the current selection each has. Returned when make is requested in facets.
                  body:
                    type: array
                    items:
                      $ref: '#/components/schemas/FacetValue'
                    description: Available body styles and how many cars in the current selection each has. Returned when body is requested in facets.
                additionalProperties:
                  type: array
                  items:
                    $ref: '#/components/schemas/FacetValue'
                description: One entry per requested facet.
        '400':
          $ref: '#/components/responses/CarsOpenapi_BadRequest'
        '401':
          $ref: '#/components/responses/CarsOpenapi_Unauthorized'
        '500':
          $ref: '#/components/responses/ServerError'
      tags:
      - Cars
      operationId: getV2Carfacets
      x-operation-id-source: derived
  /v2/carmakes:
    get:
      summary: List manufacturers. Premium only
      description: Lists car manufacturers available in the catalogue. Use it to populate a make selector before calling /carmodels. Requires a paid plan (Premium).
      parameters:
      - name: search
        in: query
        required: false
        schema:
          type: string
        description: Case-insensitive substring match on the manufacturer name.
      - name: year
        in: query
        required: false
        schema:
          type: integer
        description: Only manufacturers with a car in production in this year.
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 30
        description: How many results to return, between 1 and 100. Default 30. A value outside that range is rejected rather than silently clamped.
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          default: 0
        description: Number of results to skip, for pagination. Default 0.
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Make'
        '400':
          $ref: '#/components/responses/CarsOpenapi_BadRequest'
        '401':
          $ref: '#/components/responses/CarsOpenapi_Unauthorized'
        '500':
          $ref: '#/components/responses/ServerError'
      tags:
      - Cars
      operationId: getV2Carmakes
      x-operation-id-source: derived
  /v2/carmodels:
    get:
      summary: List models for a manufacturer. Premium only
      description: Lists the models belonging to a given manufacturer. Pair with /carmakes upstream and /cargenerations downstream. Requires a paid plan (Premium).
      parameters:
      - name: make
        in: query
        required: false
        schema:
          type: string
        description: Manufacturer, as a word. Case and punctuation are ignored, so bmw, BMW and Bmw all resolve.
      - name: search
        in: query
        required: false
        schema:
          type: string
        description: Case-insensitive substring match on the model name.
      - name: year
        in: query
        required: false
        schema:
          type: integer
        description: Only models with a car in production in this year.
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 30
        description: How many results to return, between 1 and 100. Default 30. A value outside that range is rejected rather than silently clamped.
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          default: 0
        description: Number of results to skip, for pagination. Default 0.
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Model'
        '400':
          $ref: '#/components/responses/CarsOpenapi_BadRequest'
        '401':
          $ref: '#/components/responses/CarsOpenapi_Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
      tags:
      - Cars
      operationId: getV2Carmodels
      x-operation-id-source: derived
  /v2/cargenerations:
    get:
      summary: List generations of a model, by chassis code where one exists.
      description: 'The level most vehicle APIs do not expose. Optional: nothing downstream requires it. Generations with no cars are returned with car_count 0 so gaps are visible. Requires a Business or Professional plan, or any annual plan.'
      parameters:
      - name: make
        in: query
        required: false
        schema:
          type: string
        description: Manufacturer, as a word. Case and punctuation are ignored, so bmw, BMW and Bmw all resolve.
      - name: model
        in: query
        required: false
        schema:
          type: string
        description: Model, as a word. '3 Series', '3-series' and '3series' all resolve.
      - name: chassis_code
        in: query
        required: false
        schema:
          type: string
        description: Filter to one chassis code, e.g. E91. Matches anything whose chassis_codes contains it.
      - name: year
        in: query
        required: false
        schema:
          type: integer
        description: Only generations in production in this year.
      - name: has_cars
        in: query
        required: false
        schema:
          type: boolean
        description: Set true to omit generations that have no cars.
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 30
        description: How many results to return, between 1 and 100. Default 30. A value outside that range is rejected rather than silently clamped.
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          default: 0
        description: Number of results to skip, for pagination. Default 0.
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Generation'
        '400':
          $ref: '#/components/responses/CarsOpenapi_BadRequest'
        '401':
          $ref: '#/components/responses/CarsOpenapi_Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
      tags:
      - Cars
      operationId: getV2Cargenerations
      x-operation-id-source: derived
components:
  responses:
    CarsOpenapi_Unauthorized:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CarsOpenapi_Error'
    NotFound:
      description: Nothing matched.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CarsOpenapi_Error'
    ServerError:
      description: Internal server error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CarsOpenapi_Error'
    CarsOpenapi_BadRequest:
      description: Invalid parameter. The message names the parameter and lists the valid values.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CarsOpenapi_Error'
  schemas:
    FacetValue:
      type: object
      properties:
        value:
          description: One available value for this dimension.
        count:
          type: integer
          description: How many cars in the current selection have it.
    CarsOpenapi_Error:
      type: object
      properties:
        error:
          type: string
    Car:
      type: object
      properties:
        id:
          type: string
          description: 'Handle for this exact car, e.g. car_e71ff3416a. Pass back as ?id= to re-fetch it. Safe to store: it is derived from the car''s identity and survives data refreshes.'
        make:
          type: string
          description: Manufacturer name, e.g. BMW.
        model:
          type: string
          description: Model name, e.g. 3 Series.
        generation:
          type:
          - string
          - 'null'
          description: Generation this car belongs to, e.g. E90/E91/E92/E93. Names the whole code family, because a code cannot be mapped to one body.
        chassis_codes:
          type: array
          items:
            type: string
          description: 'Every chassis code the car''s generation covers, e.g. [E90, E91, E92, E93]. A property of the generation: the source does not map a code to a body, so a car claims none of them individually. Empty for generations with no published code.'
        year_begin:
          type:
          - integer
          - 'null'
          description: First production year.
        year_end:
          type:
          - integer
          - 'null'
          description: Last production year.
        body:
          type:
          - string
          - 'null'
          description: One of Sedan, Coupe, Convertible, Wagon, Hatchback, Liftback, SUV, MPV, Van, Pickup.
        doors:
          type:
          - integer
          - 'null'
          description: Number of doors, where known.
        body_name:
          type:
          - string
          - 'null'
          description: Manufacturer's own name for the body, e.g. Touring, Avant.
        trim_line:
          type:
          - string
          - 'null'
          description: Performance or equipment line, e.g. AMG, GTI.
        market:
          type:
          - string
          - 'null'
          description: Regional variant, where the car is market-specific.
        name:
          type: string
          description: Full name as published, e.g. 320d AT (177 hp).
        badge:
          type:
          - string
          - 'null'
          description: Model designation on its own, e.g. 320d. Not unique within a generation.
        edition:
          type:
          - string
          - 'null'
          description: Marketing edition, e.g. EfficientDynamics Edition.
        engine:
          type:
          - string
          - 'null'
          description: Short engine summary, e.g. 2.0 turbo diesel.
        power_hp:
          type:
          - integer
          - 'null'
          description: Engine power in horsepower.
        power_kw:
          type:
          - integer
          - 'null'
          description: Engine power in kilowatts.
        displacement_l:
          type:
          - number
          - 'null'
          description: Engine displacement in litres.
        cylinders:
          type:
          - integer
          - 'null'
          description: Number of cylinders.
        transmission:
          type:
          - string
          - 'null'
          description: One of manual, automatic, cvt, dual_clutch, automated_manual, single_speed.
        gearbox:
          type:
          - string
          - 'null'
          description: Manufacturer's name for the gearbox, e.g. Steptronic.
        gears:
          type:
          - integer
          - 'null'
          description: Number of gears.
        drive:
          type:
          - string
          - 'null'
          description: One of fwd, rwd, awd, 4wd.
        fuel:
          type:
          - string
          - 'null'
          description: One of gasoline, diesel, electric, hybrid, plugin_hybrid, lpg, cng, hydrogen, ethanol.
        engine_code:
          type:
          - string
          - 'null'
          description: Manufacturer engine code, e.g. OM646.962.
        spec_count:
          type:
          - integer
          - 'null'
          description: Number of specification fields present in specs.
        specs:
          type: object
          additionalProperties:
            type: object
            properties:
              value:
                description: Numeric where the source value is a clean number, otherwise the original text.
              unit:
                type: string
                description: Unit of measurement, where the source records one.
          description: 'Full specification sheet, always present. Values keep their unit as a separate field, e.g. {"value": 1995, "unit": "cm3"}.'
    Generation:
      type: object
      properties:
        make:
          type: string
        model:
          type: string
        name:
          type: string
          description: Display name, e.g. E90/E91/E92/E93 facelift.
        slug:
          type: string
          description: URL-safe form, and the value to pass as generation.
        chassis_codes:
          type: array
          items:
            type: string
          description: 'Every chassis code this generation covers. BMW''s 2004-2010 3 Series is E90 (saloon), E91 (Touring), E92 (coupe) and E93 (convertible) -- one generation, four codes. Empty for generations with no published code. There is no singular chassis_code field: it would only ever be the first entry here, which for a multi-body generation is one body''s code standing in for the whole generation.'
        ordinal:
          type:
          - integer
          - 'null'
          description: Generation number where the manufacturer counts rather than codes.
        facelift:
          type: boolean
        market:
          type:
          - string
          - 'null'
        year_begin:
          type:
          - integer
          - 'null'
        year_end:
          type:
          - integer
          - 'null'
        car_count:
          type: integer
          description: A generation with 0 is still returned, so gaps in coverage are visible. Pass has_cars=true to omit them.
    Model:
      type: object
      properties:
        make:
          type: string
        name:
          type: string
          description: Model name, e.g. 3 Series.
        slug:
          type: string
          description: URL-safe form, and the value to pass as model.
        year_begin:
          type:
          - integer
          - 'null'
        year_end:
          type:
          - integer
          - 'null'
        generation_count:
          type: integer
        car_count:
          type: integer
    Make:
      type: object
      properties:
        name:
          type: string
          description: Manufacturer name, e.g. BMW.
        slug:
          type: string
          description: URL-safe form, and the value to pass as make.
        model_count:
          type: integer
        car_count:
          type: integer
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-Api-Key
externalDocs:
  description: API Ninjas documentation
  url: https://api-ninjas.com/api