openapi: 3.1.0
info:
  title: NHTSA Crash Data API
  description: >-
    The NHTSA Crash Data API provides public access to U.S. National Highway Traffic
    Safety Administration crash datasets including the Fatality Analysis Reporting
    System (FARS) and the Crash Report Sampling System (CRSS). The API exposes case
    lists, case details, and aggregated crash queries by location, vehicle, and
    occupant via REST endpoints that return JSON, XML, or CSV.
  version: '1.0'
  contact:
    name: NHTSA
    url: https://www.nhtsa.gov/contact
  license:
    name: U.S. Government Public Domain
    url: https://www.usa.gov/government-works
externalDocs:
  description: NHTSA Crash API Documentation
  url: https://crashviewer.nhtsa.dot.gov/CrashAPI
servers:
  - url: https://crashviewer.nhtsa.dot.gov/CrashAPI
    description: Production
tags:
  - name: FARS
    description: Fatality Analysis Reporting System datasets and queries
  - name: Cases
    description: Case list and case detail lookups
  - name: Crashes
    description: Crash queries by location, vehicle, and occupant
paths:
  /FARSData/GetFARSData:
    get:
      operationId: getFARSData
      summary: Get FARS dataset
      description: >-
        Returns FARS dataset records for the specified case year and dataset name.
      tags:
        - FARS
      parameters:
        - name: dataset
          in: query
          required: true
          description: FARS dataset name (e.g., Accident, Vehicle, Person).
          schema:
            type: string
        - name: caseYear
          in: query
          required: true
          description: Case year (YYYY).
          schema:
            type: integer
        - name: format
          in: query
          required: false
          description: Response format.
          schema:
            type: string
            enum: [json, xml, csv]
            default: json
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CrashApiResponse'
            application/xml: {}
            text/csv: {}
  /crashes/GetCaseList:
    get:
      operationId: getCaseList
      summary: Get case list
      description: >-
        Returns a list of crash cases filtered by state, year range, and vehicle count.
      tags:
        - Cases
      parameters:
        - name: states
          in: query
          required: true
          description: State FIPS code(s), comma separated.
          schema:
            type: string
        - name: fromCaseYear
          in: query
          required: true
          description: Beginning case year.
          schema:
            type: integer
        - name: toCaseYear
          in: query
          required: true
          description: Ending case year.
          schema:
            type: integer
        - name: minNumOfVehicles
          in: query
          required: false
          description: Minimum number of vehicles involved.
          schema:
            type: integer
        - name: maxNumOfVehicles
          in: query
          required: false
          description: Maximum number of vehicles involved.
          schema:
            type: integer
        - name: format
          in: query
          required: false
          schema:
            type: string
            enum: [json, xml, csv]
            default: json
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CrashApiResponse'
  /crashes/GetCaseDetails:
    get:
      operationId: getCaseDetails
      summary: Get case details
      description: >-
        Returns full case details for a specific state case number and year.
      tags:
        - Cases
      parameters:
        - name: stateCase
          in: query
          required: true
          description: State case number.
          schema:
            type: string
        - name: caseYear
          in: query
          required: true
          schema:
            type: integer
        - name: state
          in: query
          required: true
          description: State FIPS code.
          schema:
            type: integer
        - name: format
          in: query
          required: false
          schema:
            type: string
            enum: [json, xml, csv]
            default: json
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CrashApiResponse'
  /crashes/GetCrashesByLocation:
    get:
      operationId: getCrashesByLocation
      summary: Get crashes by location
      description: >-
        Returns crashes filtered by state, year range, and county.
      tags:
        - Crashes
      parameters:
        - name: fromCaseYear
          in: query
          required: true
          schema:
            type: integer
        - name: toCaseYear
          in: query
          required: true
          schema:
            type: integer
        - name: state
          in: query
          required: true
          description: State FIPS code.
          schema:
            type: integer
        - name: county
          in: query
          required: false
          description: County FIPS code.
          schema:
            type: integer
        - name: format
          in: query
          required: false
          schema:
            type: string
            enum: [json, xml, csv]
            default: json
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CrashApiResponse'
  /crashes/GetCrashesByVehicle:
    get:
      operationId: getCrashesByVehicle
      summary: Get crashes by vehicle
      description: >-
        Returns crashes filtered by vehicle make, model, and body type for a given year range.
      tags:
        - Crashes
      parameters:
        - name: fromCaseYear
          in: query
          required: true
          schema:
            type: integer
        - name: toCaseYear
          in: query
          required: true
          schema:
            type: integer
        - name: state
          in: query
          required: true
          schema:
            type: integer
        - name: vPicMake
          in: query
          required: false
          schema:
            type: string
        - name: vPicModel
          in: query
          required: false
          schema:
            type: string
        - name: vPicBodyClass
          in: query
          required: false
          schema:
            type: string
        - name: format
          in: query
          required: false
          schema:
            type: string
            enum: [json, xml, csv]
            default: json
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CrashApiResponse'
  /crashes/GetCrashesByOccupant:
    get:
      operationId: getCrashesByOccupant
      summary: Get crashes by occupant
      description: >-
        Returns crashes filtered by occupant age, sex, and seat position for a given year range.
      tags:
        - Crashes
      parameters:
        - name: fromCaseYear
          in: query
          required: true
          schema:
            type: integer
        - name: toCaseYear
          in: query
          required: true
          schema:
            type: integer
        - name: state
          in: query
          required: true
          schema:
            type: integer
        - name: minAge
          in: query
          required: false
          schema:
            type: integer
        - name: maxAge
          in: query
          required: false
          schema:
            type: integer
        - name: sex
          in: query
          required: false
          schema:
            type: integer
        - name: seatPos
          in: query
          required: false
          schema:
            type: integer
        - name: format
          in: query
          required: false
          schema:
            type: string
            enum: [json, xml, csv]
            default: json
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CrashApiResponse'
components:
  schemas:
    CrashApiResponse:
      type: object
      properties:
        Count:
          type: integer
          description: Number of records returned.
        Message:
          type: string
        Results:
          type: array
          items:
            type: object
            additionalProperties: true