Valgo v1 API

openapi: 3.1.0
info:
  title: Human Crash Baselines Compute v1 API
  description: Compute human crash-rate baselines over filterable crash and exposure data. The versioned, API-key-authenticated public surface lives under `/v1`; call `GET /v1/filters` to discover every filter and valid value. Send your key via the `X-API-Key` header.
  version: 0.1.3
tags:
- name: v1
paths:
  /v1/filters:
    get:
      tags:
      - v1
      summary: V1 Filters
      description: 'Discover every filter dimension, its valid options, and the default for

        each compute mode (geofence / route / depot).'
      operationId: v1_filters_v1_filters_get
      parameters:
      - name: X-API-Key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Key
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FiltersResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/regions:
    get:
      tags:
      - v1
      summary: V1 Regions
      description: Counties available on this server and which compute modes each supports.
      operationId: v1_regions_v1_regions_get
      parameters:
      - name: X-API-Key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Key
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegionsResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/manifest:
    get:
      tags:
      - v1
      summary: V1 Manifest
      description: Dataset metadata (schema version, row counts, checksums, availability).
      operationId: v1_manifest_v1_manifest_get
      parameters:
      - name: X-API-Key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Key
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response V1 Manifest V1 Manifest Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/compute:
    post:
      tags:
      - v1
      summary: V1 Compute
      description: 'Geofence (S2-cell) crash rate for the given filters: county-wide N, D,

        rate + 95% CI, optional operator-weighted rate, and a per-cell breakdown.

        Pass `summary_only: true` to drop the per-cell breakdown.'
      operationId: v1_compute_v1_compute_post
      parameters:
      - name: X-API-Key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Key
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/V1ComputeRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ComputeResult'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/compute/batch:
    post:
      tags:
      - v1
      summary: V1 Compute Batch
      description: 'Geofence crash rate for many (county, selections) combinations in one

        request — built for comparing counties side by side. Returns a per-item list

        of {county, result|null, error|null} (same order as the request), so a

        single failing county is reported inline instead of failing the whole call.

        Defaults to summary-only (no per-cell breakdown).'
      operationId: v1_compute_batch_v1_compute_batch_post
      parameters:
      - name: X-API-Key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Key
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/V1BatchRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchComputeResult'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/compute/route:
    post:
      tags:
      - v1
      summary: V1 Compute Route
      description: 'Crash rate aggregated over a sequence of interstate (route, milepost)

        segments. Counties with ROUTE mode (travis, interstates).'
      operationId: v1_compute_route_v1_compute_route_post
      parameters:
      - name: X-API-Key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Key
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/V1RouteRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RouteComputeResult'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/compute/depot-route:
    post:
      tags:
      - v1
      summary: V1 Compute Depot Route
      description: 'Full depot-to-depot trip rate (access + interstate + access legs).

        Counties with DEPOT mode (travis, interstates).'
      operationId: v1_compute_depot_route_v1_compute_depot_route_post
      parameters:
      - name: X-API-Key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Key
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/V1DepotRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DepotComputeResult'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    OperatorWeighting:
      type: string
      enum:
      - county_wide
      - robotaxi
      title: OperatorWeighting
    GeofenceSelections:
      properties:
        outcome:
          $ref: '#/components/schemas/Outcome'
          default: police_reported
        severity:
          type: integer
          maximum: 7.0
          minimum: 1.0
          title: Severity
          default: 1
        ego_vehicle:
          anyOf:
          - items:
              $ref: '#/components/schemas/VehicleClass'
            type: array
          - $ref: '#/components/schemas/VehicleClass'
          title: Ego Vehicle
          default:
          - cars
          - light_trucks
          - heavy_trucks
          - motorcycles
          - buses
        unresolved_nfs:
          $ref: '#/components/schemas/Tier3Mode'
          default: marginal
        in_transport:
          $ref: '#/components/schemas/InTransport'
          default: in_transport
        road_type:
          anyOf:
          - items:
              $ref: '#/components/schemas/RoadGroup'
            type: array
          - $ref: '#/components/schemas/RoadGroup'
          title: Road Type
          default:
          - collector_local
          - arterial
          - other_freeway
          - interstate
        operator_weighting:
          $ref: '#/components/schemas/OperatorWeighting'
          default: county_wide
        multiplier_vmt:
          $ref: '#/components/schemas/MultiplierVmt'
          default: calibrated
        operator_weight:
          anyOf:
          - type: number
            exclusiveMinimum: 0.0
          - type: 'null'
          title: Operator Weight
        denominator_vmt:
          $ref: '#/components/schemas/DenominatorVmt'
          default: calibrated
        tiling:
          $ref: '#/components/schemas/Tiling'
          default: s2
        under_reporting:
          $ref: '#/components/schemas/UnderReporting'
          default: none
        weather:
          anyOf:
          - items:
              $ref: '#/components/schemas/WeatherFilter'
            type: array
          - $ref: '#/components/schemas/WeatherFilter'
          title: Weather
          default:
          - dry
          - rain
          - fog
        light_condition:
          anyOf:
          - items:
              $ref: '#/components/schemas/LightFilter'
            type: array
          - $ref: '#/components/schemas/LightFilter'
          title: Light Condition
          default: any
        crash_year:
          anyOf:
          - items:
              type: integer
            type: array
          - type: integer
          title: Crash Year
          default:
          - 2022
      additionalProperties: false
      type: object
      title: GeofenceSelections
      description: Filters for POST /v1/compute (S2-cell / geofence mode).
    CiMethod:
      type: string
      enum:
      - fay_feuer
      - empirical_bayes
      title: CiMethod
    PerCellResult:
      properties:
        s2_cell:
          type: string
          title: S2 Cell
        count:
          type: number
          title: Count
        vmt:
          type: number
          title: Vmt
        mult_contrib:
          type: number
          title: Mult Contrib
          default: 0.0
      additionalProperties: true
      type: object
      required:
      - s2_cell
      - count
      - vmt
      title: PerCellResult
    RouteComputeResult:
      properties:
        N:
          type: number
          title: N
        trip_miles:
          type: number
          title: Trip Miles
        rate:
          type: number
          title: Rate
        rate_low:
          anyOf:
          - type: number
          - type: 'null'
          title: Rate Low
        rate_high:
          anyOf:
          - type: number
          - type: 'null'
          title: Rate High
        variance:
          anyOf:
          - type: number
          - type: 'null'
          title: Variance
        segments:
          items:
            $ref: '#/components/schemas/PerSegmentResult'
          type: array
          title: Segments
        exposure_sources:
          items:
            type: string
          type: array
          title: Exposure Sources
        crash_sources:
          items:
            type: string
          type: array
          title: Crash Sources
      additionalProperties: true
      type: object
      required:
      - N
      - trip_miles
      - rate
      title: RouteComputeResult
    DenominatorVmt:
      type: string
      enum:
      - calibrated
      - hpms
      title: DenominatorVmt
    PerSegmentResult:
      properties:
        route:
          type: string
          title: Route
        milepost:
          type: integer
          title: Milepost
        count:
          type: number
          title: Count
        vmt:
          type: number
          title: Vmt
        length_mi:
          type: number
          title: Length Mi
      additionalProperties: true
      type: object
      required:
      - route
      - milepost
      - count
      - vmt
      - length_mi
      title: PerSegmentResult
    LightFilter:
      type: string
      enum:
      - any
      - daylight
      - dawn_dusk
      - dark
      title: LightFilter
    DepotPin:
      properties:
        lat:
          type: number
          title: Lat
        lon:
          type: number
          title: Lon
      type: object
      required:
      - lat
      - lon
      title: DepotPin
    InTransport:
      type: string
      enum:
      - in_transport
      - include_all
      title: InTransport
    V1DepotRequest:
      properties:
        county:
          type: string
          title: County
          default: travis
        depot_a:
          $ref: '#/components/schemas/DepotPin'
        depot_b:
          $ref: '#/components/schemas/DepotPin'
        selections:
          $ref: '#/components/schemas/DepotSelections'
      type: object
      required:
      - depot_a
      - depot_b
      title: V1DepotRequest
    Tiling:
      type: string
      enum:
      - s2
      - h3
      title: Tiling
    RouteSelections:
      properties:
        outcome:
          $ref: '#/components/schemas/Outcome'
          default: police_reported
        severity:
          type: integer
          maximum: 7.0
          minimum: 1.0
          title: Severity
          default: 1
        ego_vehicle:
          anyOf:
          - items:
              $ref: '#/components/schemas/VehicleClass'
            type: array
          - $ref: '#/components/schemas/VehicleClass'
          title: Ego Vehicle
          default:
          - combination
        unresolved_nfs:
          $ref: '#/components/schemas/Tier3Mode'
          default: marginal
        in_transport:
          $ref: '#/components/schemas/InTransport'
          default: in_transport
        weather:
          anyOf:
          - items:
              $ref: '#/components/schemas/WeatherFilter'
            type: array
          - $ref: '#/components/schemas/WeatherFilter'
          title: Weather
          default:
          - dry
          - rain
          - fog
        light_condition:
          anyOf:
          - items:
              $ref: '#/components/schemas/LightFilter'
            type: array
          - $ref: '#/components/schemas/LightFilter'
          title: Light Condition
          default: any
        driver_impairment:
          $ref: '#/components/schemas/DriverImpairment'
          default: any
        under_reporting:
          $ref: '#/components/schemas/UnderReporting'
          default: none
        ci_method:
          $ref: '#/components/schemas/CiMethod'
          default: fay_feuer
      additionalProperties: false
      type: object
      title: RouteSelections
      description: Filters for POST /v1/compute/route (interstate-segment mode).
    RegionsResponse:
      properties:
        regions:
          items:
            $ref: '#/components/schemas/RegionInfo'
          type: array
          title: Regions
        default_county:
          type: string
          title: Default County
          default: travis
      type: object
      required:
      - regions
      title: RegionsResponse
    V1ComputeRequest:
      properties:
        county:
          type: string
          title: County
          default: travis
        selections:
          $ref: '#/components/schemas/GeofenceSelections'
        summary_only:
          type: boolean
          title: Summary Only
          description: Drop the per-cell `cells` breakdown (returned as []), keeping just the county-wide scalars. Cuts the bulk of the response for callers that don't need the map heatmap.
          default: false
      type: object
      title: V1ComputeRequest
    Outcome:
      type: string
      enum:
      - police_reported
      - observed_any_injury
      - airbag
      - ego_airbag
      - ka
      - fatal
      title: Outcome
    V1RouteRequest:
      properties:
        county:
          type: string
          title: County
          default: travis
        segment_ids:
          items:
            prefixItems:
            - type: string
            - type: integer
            type: array
            maxItems: 2
            minItems: 2
          type: array
          title: Segment Ids
          description: Ordered [route, milepost] pairs, e.g. [["I-35", 250], ["I-35", 251]].
        selections:
          $ref: '#/components/schemas/RouteSelections'
      type: object
      required:
      - segment_ids
      title: V1RouteRequest
    V1BatchItem:
      properties:
        county:
          type: string
          title: County
          default: travis
        selections:
          $ref: '#/components/schemas/GeofenceSelections'
      type: object
      title: V1BatchItem
    VehicleClass:
      type: string
      enum:
      - cars
      - light_trucks
      - heavy_trucks
      - motorcycles
      - buses
      - other
      title: VehicleClass
    BatchComputeResult:
      properties:
        results:
          items:
            $ref: '#/components/schemas/BatchItemResult'
          type: array
          title: Results
      type: object
      title: BatchComputeResult
      description: Per-item results, in the same order as the request's `items`.
    ComputeResult:
      properties:
        N:
          type: number
          title: N
        D_miles:
          type: number
          title: D Miles
        D_billions:
          type: number
          title: D Billions
        rate:
          type: number
          title: Rate
        rate_low:
          anyOf:
          - type: number
          - type: 'null'
          title: Rate Low
        rate_high:
          anyOf:
          - type: number
          - type: 'null'
          title: Rate High
        rate_non_dyn:
          type: number
          title: Rate Non Dyn
        rate_dyn:
          anyOf:
          - type: number
          - type: 'null'
          title: Rate Dyn
        multiplier:
          anyOf:
          - type: number
          - type: 'null'
          title: Multiplier
        cells:
          items:
            $ref: '#/components/schemas/PerCellResult'
          type: array
          title: Cells
      additionalProperties: true
      type: object
      required:
      - N
      - D_miles
      - D_billions
      - rate
      - rate_non_dyn
      title: ComputeResult
    V1BatchRequest:
      properties:
        items:
          items:
            $ref: '#/components/schemas/V1BatchItem'
          type: array
          title: Items
          description: One (county, selections) combination per entry. Selections are per-item because a value valid in one county can be invalid in another, so the batch can't share a single selection set.
        summary_only:
          type: boolean
          title: Summary Only
          description: Batch defaults to summary-only (no per-cell breakdown), as it exists for multi-county comparison. Set false to include `cells`.
          default: true
      type: object
      title: V1BatchRequest
    UnderReporting:
      type: string
      enum:
      - none
      - adjusted
      title: UnderReporting
    Tier3Mode:
      type: string
      enum:
      - marginal
      - none
      - all
      title: Tier3Mode
    DriverImpairment:
      type: string
      enum:
      - any
      - exclude_impaired
      - impaired_only
      title: DriverImpairment
    FiltersResponse:
      properties:
        modes:
          additionalProperties:
            items:
              $ref: '#/components/schemas/FilterDef'
            type: array
          type: object
          title: Modes
      type: object
      required:
      - modes
      title: FiltersResponse
    RoadGroup:
      type: string
      enum:
      - interstate
      - other_freeway
      - arterial
      - collector_local
      title: RoadGroup
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    FilterDef:
      properties:
        id:
          type: string
          title: Id
        label:
          type: string
          title: Label
        affects:
          type: string
          title: Affects
        multiselect:
          type: boolean
          title: Multiselect
        description:
          type: string
          title: Description
        options:
          items:
            $ref: '#/components/schemas/FilterOption'
          type: array
          title: Options
        default:
          title: Default
      additionalProperties: true
      type: object
      required:
      - id
      - label
      - affects
      - multiselect
      - description
      - options
      title: FilterDef
    MultiplierVmt:
      type: string
      enum:
      - calibrated
      - hpms
      title: MultiplierVmt
    DepotSelections:
      properties:
        outcome:
          $ref: '#/components/schemas/Outcome'
          default: police_reported
        severity:
          type: integer
          maximum: 7.0
          minimum: 1.0
          title: Severity
          default: 1
        ego_vehicle:
          anyOf:
          - items:
              $ref: '#/components/schemas/VehicleClass'
            type: array
          - $ref: '#/components/schemas/VehicleClass'
          title: Ego Vehicle
          default:
          - combination
        unresolved_nfs:
          $ref: '#/components/schemas/Tier3Mode'
          default: marginal
        in_transport:
          $ref: '#/components/schemas/InTransport'
          default: in_transport
        weather:
          anyOf:
          - items:
              $ref: '#/components/schemas/WeatherFilter'
            type: array
          - $ref: '#/components/schemas/WeatherFilter'
          title: Weather
          default:
          - dry
          - rain
          - fog
        light_condition:
          anyOf:
          - items:
              $ref: '#/components/schemas/LightFilter'
            type: array
          - $ref: '#/components/schemas/LightFilter'
          title: Light Condition
          default: any
        driver_impairment:
          $ref: '#/components/schemas/DriverImpairment'
          default: any
        under_reporting:
          $ref: '#/components/schemas/UnderReporting'
          default: none
        ci_method:
          $ref: '#/components/schemas/CiMethod'
          default: empirical_bayes
      additionalProperties: false
      type: object
      title: DepotSelections
      description: Filters for POST /v1/compute/depot-route (depot-to-depot trip).
    RegionInfo:
      properties:
        county:
          type: string
          title: County
        modes:
          items:
            type: string
          type: array
          title: Modes
      type: object
      required:
      - county
      - modes
      title: RegionInfo
    BatchItemResult:
      properties:
        county:
          type: string
          title: County
        result:
          anyOf:
          - $ref: '#/components/schemas/ComputeResult'
          - type: 'null'
        error:
          anyOf:
          - type: string
          - type: 'null'
          title: Error
      additionalProperties: true
      type: object
      required:
      - county
      title: BatchItemResult
      description: 'One entry of a batch compute response. Exactly one of `result` / `error`

        is set: `result` on success, `error` (a message) when that county''s compute

        failed (so one bad county doesn''t sink the whole batch).'
    DepotComputeResult:
      properties: {}
      additionalProperties: true
      type: object
      title: DepotComputeResult
      description: 'Three-leg depot-to-depot trip. Shape mirrors engine.compute_depot_route;

        left loose because it carries leg sub-objects + geometry for rendering.'
    FilterOption:
      properties:
        id:
          type: string
          title: Id
        label:
          type: string
          title: Label
      type: object
      required:
      - id
      - label
      title: FilterOption
    WeatherFilter:
      type: string
      enum:
      - any
      - dry
      - rain
      - fog
      - winter_storm
      title: WeatherFilter