Carbonara CO2 Factors API

openapi: 3.2.0
info:
  title: Sootcase Factors API
  version: 0.1.0
  description: Freight emissions calculator following the GLEC Framework / ISO 14083 approach. Emissions are in kg CO2e. TTW = tank-to-wheel, WTW = well-to-wheel.
  license:
    name: PolyForm Noncommercial 1.0.0
    identifier: PolyForm-Noncommercial-1.0.0
servers:
- url: https://sootcase.org
  description: 'Free test service; send your API key as ''Authorization: Bearer <key>'' (get one at https://sootcase.org)'
- url: http://localhost:8080
  description: sootcase serve
tags:
- name: Factors
paths:
  /v1/factors:
    get:
      summary: The loaded emission factor dataset
      responses:
        '200':
          description: Factor dataset
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Dataset'
      tags:
      - Factors
      operationId: getV1Factors
      x-operation-id-source: derived
components:
  schemas:
    Dataset:
      type: object
      properties:
        name:
          type: string
        note:
          type: string
        legs:
          type: array
          items:
            $ref: '#/components/schemas/Factor'
        hubs:
          type: array
          items:
            $ref: '#/components/schemas/HubFactor'
        fuels:
          type: array
          items:
            $ref: '#/components/schemas/FuelFactor'
        grids:
          type: array
          description: Electricity carbon intensity per country
          items:
            type: object
            properties:
              country:
                type: string
              year:
                type: integer
              g_per_kwh:
                type: number
              source:
                type: string
        grid_note:
          type: string
        container_loads:
          type: object
          additionalProperties:
            type: number
          description: Profile name to net cargo tonnes per TEU
        dafs:
          type: array
          description: 'Distance adjustment factors: to_km = from_km * multiplier + add_km'
          items:
            type: object
            properties:
              mode:
                $ref: '#/components/schemas/Mode'
              from:
                $ref: '#/components/schemas/DistanceType'
              to:
                $ref: '#/components/schemas/DistanceType'
              multiplier:
                type: number
              add_km:
                type: number
              source:
                type: string
        distance_adjustments:
          type: array
          description: 'Great-circle to actual distance, per mode: gcd * multiplier + add_km'
          items:
            type: object
            properties:
              mode:
                $ref: '#/components/schemas/Mode'
              multiplier:
                type: number
              add_km:
                type: number
              source:
                type: string
        vehicle_aliases:
          type: array
          description: Short vehicle types (hgv_artic, container_ship, ...) and what they mean, regional ones by the regions of the leg's ends
          items:
            type: object
        fuel_aliases:
          type: object
          additionalProperties:
            type: string
          description: Short fuel names and the fuel ids they mean
        fuel_regions:
          type: object
          description: Fuel aliases that mean a region's fuel when both ends of the leg are in it
        cargo_types:
          type: array
          items:
            type: object
          description: GLEC cargo or load categories (cargo_type)
        cargo_variants:
          type: object
          description: Per vehicle type, the vehicle type GLEC gives for each cargo type
        hub_cargo_variants:
          type: object
          description: Per hub type, the hub type for each cargo type
        load_models:
          type: array
          items:
            type: object
          description: Load-dependent emissions per vehicle class (load_tonnes
          load_factor): null
        regions:
          type: array
          items:
            type: object
          description: The regions and sea zones regional aliases choose by
    FuelFactor:
      type: object
      properties:
        fuel:
          type: string
        biogenic_co2_kg_per_unit:
          type: number
          description: Biogenic CO2 per unit, outside the TTW/WTT factors
        unit:
          type: string
        ttw_kg_per_unit:
          type: number
        wtt_kg_per_unit:
          type: number
        source:
          type: string
        year:
          type: integer
    DistanceType:
      type: string
      enum:
      - sfd
      - gcd
      - actual
      description: Shortest feasible, great-circle, or actually travelled distance (GLEC / ISO 14083)
    HubFactor:
      type: object
      properties:
        hub_type:
          type: string
        wtw_g_per_tonne:
          type: number
        wtw_g_per_container:
          type: number
          description: Set instead of wtw_g_per_tonne for per-container hub types
        source:
          type: string
        year:
          type: integer
        data_type:
          type: string
          description: primary for hub factors built from the operator's own energy use; else left out
    Mode:
      type: string
      enum:
      - road
      - rail
      - sea
      - air
      - inland_waterway
    Factor:
      type: object
      properties:
        mode:
          $ref: '#/components/schemas/Mode'
        vehicle_type:
          type: string
        ttw_g_per_tkm:
          type: number
        wtt_g_per_tkm:
          type: number
        source:
          type: string
        year:
          type: integer
        distance_basis:
          $ref: '#/components/schemas/DistanceType'
        data_type:
          type: string
          description: primary for factors built from the operator's own measurements (transport operation categories); else left out