openapi: 3.1.0
info:
  title: BJS NCVS NIBRS API
  description: The National Crime Victimization Survey (NCVS) API exposes selected NCVS datasets via the Socrata Open Data API (SODA). Each dataset is identified by a four-character resource code and may be requested as JSON or CSV.
  version: '1.0'
  contact:
    name: Bureau of Justice Statistics
    url: https://bjs.ojp.gov/
servers:
- url: https://api.ojp.gov/bjsdataset/v1
  description: BJS dataset API base URL
tags:
- name: NIBRS
  description: NIBRS national-estimates datasets.
paths:
  /resource/{datasetId}.json:
    get:
      operationId: getNibrsDatasetJson
      summary: Get NIBRS dataset as JSON
      description: Returns NIBRS national-estimates rows in JSON format.
      tags:
      - NIBRS
      parameters:
      - name: datasetId
        in: path
        required: true
        schema:
          type: string
          pattern: ^[a-z0-9]{4}-[a-z0-9]{4}$
      - name: $select
        in: query
        schema:
          type: string
      - name: $where
        in: query
        schema:
          type: string
      - name: $order
        in: query
        schema:
          type: string
      - name: $group
        in: query
        schema:
          type: string
      - name: $limit
        in: query
        schema:
          type: integer
          default: 1000
      - name: $offset
        in: query
        schema:
          type: integer
          default: 0
      responses:
        '200':
          description: Array of dataset rows
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  additionalProperties: true
  /resource/{datasetId}.csv:
    get:
      operationId: getNibrsDatasetCsv
      summary: Get NIBRS dataset as CSV
      tags:
      - NIBRS
      parameters:
      - name: datasetId
        in: path
        required: true
        schema:
          type: string
          pattern: ^[a-z0-9]{4}-[a-z0-9]{4}$
      responses:
        '200':
          description: CSV-formatted rows
          content:
            text/csv:
              schema:
                type: string
components:
  securitySchemes:
    appToken:
      type: apiKey
      in: header
      name: X-App-Token
      description: Optional Socrata application token for higher rate limits.