Carbonara CO2 Calculate API

openapi: 3.2.0
info:
  title: Sootcase Calculate 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: Calculate
paths:
  /v1/calculate:
    post:
      summary: Calculate emissions for one shipment
      parameters:
      - name: add_road_legs
        in: query
        schema:
          type: boolean
          default: true
        description: false adds no road legs for shipments that don't set add_road_legs themselves.
      - name: explain
        in: query
        schema:
          type: boolean
          default: false
        description: 'Add "explanation": the calculation step by step (cargo mass, each leg''s distance, transport activity, intensity and emissions, hubs, total), with the numbers used and the GLEC Framework v3.3 pages and ISO 14083:2023 clauses each step follows, so that it can be checked by hand.

          '
      - name: path
        in: query
        schema:
          type: string
          enum:
          - 'false'
          - 'true'
          - simplified
          - detailed
          - full
          default: 'false'
        description: 'Add each leg''s route as GeoJSON [lon, lat] points (legs[].path), for a map: true or simplified (the router''s simplified line, a few dozen points), detailed (the full line thinned to at most 1,000 points) or full (every point; a long road route can have tens of thousands). Distances are the same at every level. Two points mean a straight line (distance given or estimated).'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Shipment'
      responses:
        '200':
          description: Result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Result'
        '400':
          $ref: '#/components/responses/Error'
        '413':
          $ref: '#/components/responses/Error'
        '422':
          $ref: '#/components/responses/Error'
        '500':
          $ref: '#/components/responses/Error'
        '503':
          $ref: '#/components/responses/Busy'
          description: 'Busy, or a routing service didn''t answer (also when tried again): try again after Retry-After'
        '504':
          $ref: '#/components/responses/Error'
      tags:
      - Calculate
      operationId: postV1Calculate
      x-operation-id-source: derived
  /v1/calculate/batch:
    post:
      summary: Calculate emissions for up to 10,000 shipments
      description: Failures are reported per shipment; the request itself still returns 200.
      parameters:
      - name: add_road_legs
        in: query
        schema:
          type: boolean
          default: true
        description: false adds no road legs for shipments that don't set add_road_legs themselves.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - shipments
              properties:
                shipments:
                  type: array
                  items:
                    $ref: '#/components/schemas/Shipment'
      responses:
        '200':
          description: Per-shipment results
          content:
            application/json:
              schema:
                type: object
                properties:
                  failed:
                    type: integer
                  retryable:
                    type: integer
                    description: Failures worth sending again
                  results:
                    type: array
                    items:
                      type: object
                      properties:
                        shipment_id:
                          type: string
                        result:
                          $ref: '#/components/schemas/Result'
                        error:
                          type: string
                        retryable:
                          type: boolean
                          description: 'The failure isn''t the input''s fault (a routing service didn''t answer, also when tried again): send it again'
        '400':
          $ref: '#/components/responses/Error'
        '413':
          $ref: '#/components/responses/Error'
        '500':
          $ref: '#/components/responses/Error'
        '503':
          $ref: '#/components/responses/Busy'
        '504':
          $ref: '#/components/responses/Error'
      tags:
      - Calculate
      operationId: postV1CalculateBatch
      x-operation-id-source: derived
components:
  schemas:
    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
    Location:
      type: object
      description: Coordinates, or a code instead of them.
      properties:
        name:
          type: string
        code:
          type: string
          description: UN/LOCODE (NLRTM) or IATA airport code (CPH), used when lat and lon are not given. Find codes with GET /v1/places.
          example: NLRTM
        lat:
          type: number
        lon:
          type: number
    Shipment:
      type: object
      required:
      - legs
      description: Give weight_kg, or teu with teu_net_tonnes or container_load; teu alone uses the dataset's "average" profile (GLEC, 10 t per TEU).
      properties:
        id:
          type: string
        weight_kg:
          type: number
          exclusiveMinimum: 0
        teu:
          type: number
          exclusiveMinimum: 0
        teu_net_tonnes:
          type: number
          description: Net cargo tonnes per TEU
        container_load:
          type: string
          description: Profile name from the dataset's container_loads
        cargo_type:
          type: string
          description: Optional GLEC cargo or load category from the dataset's cargo_types (container, temperature_controlled, light, heavy, European rail commodities); picks GLEC's value for it where the leg's vehicle has one
        legs:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/Leg'
        hubs:
          type: array
          items:
            $ref: '#/components/schemas/HubStop'
        add_road_legs:
          type: boolean
          default: true
          description: 'Add road legs where the trip doesn''t join up: across a gap of more than 5 km between one leg''s end and the next leg''s start, and to or from a port or rail terminal when a sea, rail or inland waterway leg starts or ends off its network (the leg is moved there). Added and moved legs are marked in the result. When false, gaps and inland sea ends are only warnings.

            '
    LegPart:
      type: object
      properties:
        kind:
          type: string
          enum:
          - ferry
          - electrified
        mode:
          $ref: '#/components/schemas/Mode'
        distance_km:
          type: number
        tonne_km:
          type: number
        ttw_kg:
          type: number
        wtt_kg:
          type: number
        wtw_kg:
          type: number
        method:
          type: string
        data_type:
          $ref: '#/components/schemas/DataType'
        factor:
          $ref: '#/components/schemas/Factor'
        daf:
          type: number
        daf_source:
          type: string
        energy_kwh_per_tkm:
          type: number
        country:
          type: string
    HubStop:
      type: object
      required:
      - hub_type
      properties:
        id:
          type: string
        hub_type:
          type: string
          example: transshipment
          description: 'GLEC v3.3 Table 3 hub types: transshipment, storage_transshipment, warehouse, liquid_bulk_terminal (add _mixed for ambient and temperature-controlled sites; per tonne), intermodal_terminal, intermodal_terminal_temperature_controlled (per container)'
        containers:
          type: number
          description: Containers handled, for per-container hub types (intermodal terminals)
    DataType:
      type: string
      enum:
      - primary
      - modelled
      - default
      description: 'primary: measured fuel; modelled: load or energy model from shipment inputs; default: published factor'
    DistanceType:
      type: string
      enum:
      - sfd
      - gcd
      - actual
      description: Shortest feasible, great-circle, or actually travelled distance (GLEC / ISO 14083)
    LegResult:
      type: object
      properties:
        leg_id:
          type: string
          description: The leg's id, or added-N for an added road leg
        biogenic_co2_kg:
          type: number
          description: Biogenic CO2, reported separately and not included in the totals (GLEC v3.3 p. 64)
        added:
          type: string
          enum:
          - gap
          - access
          description: 'Set on road legs the calculator added: gap (the legs didn''t join up) or access (to or from the port or terminal a leg was moved to)'
        note:
          type: string
          description: Why the leg was added
          or where its end was moved to: null
        factor_note:
          type: string
          description: Which factor the vehicle type meant at this leg's distance (e.g. container_ship short-sea or deep-sea)
        from:
          $ref: '#/components/schemas/Location'
          description: Where the leg was calculated from (moved for a leg moved to a port or terminal), when known
        to:
          $ref: '#/components/schemas/Location'
          description: Where the leg was calculated to
          when known: null
        mode:
          $ref: '#/components/schemas/Mode'
        vehicle_type:
          type: string
        distance_km:
          type: number
        distance_method:
          type: string
          description: Where the distance came from
          enum:
          - given
          - great_circle
          - great_circle_adjusted
          - osrm
          - osrm_rail
          - osrm_waterway
          - sea_network
        distance_type:
          $ref: '#/components/schemas/DistanceType'
        daf:
          type: number
          description: Distance adjustment factor applied to emissions, when the leg's distance type differed from the factor's basis
        daf_source:
          type: string
        tonne_km:
          type: number
        ttw_kg:
          type: number
        wtt_kg:
          type: number
        wtw_kg:
          type: number
        intensity_g_per_tkm:
          type: number
          description: WTW g CO2e per tonne-km for this leg
        method:
          type: string
          enum:
          - intensity
          - fuel
          - load_model
          - energy
        data_type:
          $ref: '#/components/schemas/DataType'
        energy_kwh_per_tkm:
          type: number
        country:
          type: string
        load_factor:
          type: number
          description: Load as a share of payload_t (from load_tonnes when that was given)
        load_tonnes:
          type: number
        empty_trip_factor:
          type: number
        payload_t:
          type: number
        factor:
          $ref: '#/components/schemas/Factor'
        fuel_factor:
          $ref: '#/components/schemas/FuelFactor'
        allocation_share:
          type: number
        route_parts_km:
          type: object
          additionalProperties:
            type: number
          description: 'Routed km by kind: ferry (road), electrified, not_electrified, electrification_unknown (rail)'
        path:
          type: array
          description: With ?path=true only. The leg's route as GeoJSON [lon, lat] points; two points mean a straight line.
          items:
            type: array
            items:
              type: number
            minItems: 2
            maxItems: 2
        parts:
          type: array
          description: Parts calculated separately and included in the leg's totals
          items:
            $ref: '#/components/schemas/LegPart'
        repositioning_km:
          type: number
          description: Empty km given for the leg (included in the empty trip factor)
    FuelUse:
      type: object
      required:
      - fuel
      - amount
      properties:
        fuel:
          type: string
          example: diesel
        amount:
          type: number
          description: In the fuel factor's unit
        vehicle_tonne_km:
          type: number
          description: Total tonne-km on the vehicle trip, for allocation. 0 or absent = whole trip.
        factor:
          type: object
          description: The fuel supplier's or your own emission factor, used instead of the dataset's (fuel is then just its name).
          required:
          - unit
          - wtw_kg_per_unit
          - source
          properties:
            unit:
              type: string
              example: l
            wtw_kg_per_unit:
              type: number
              exclusiveMinimum: 0
              description: Well-to-wheel kg CO2e per unit
            ttw_kg_per_unit:
              type: number
              minimum: 0
              description: Tank-to-wheel kg CO2e per unit
              part of WTW: null
            source:
              type: string
              description: Who gives the factor
              and for what: null
            biogenic_co2_kg_per_unit:
              type: number
              minimum: 0
              description: Reported apart
              not in WTW: null
    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
    Result:
      type: object
      properties:
        shipment_id:
          type: string
        biogenic_co2_kg:
          type: number
          description: Biogenic CO2, reported separately and not included in the totals (GLEC v3.3 p. 64)
        weight_kg:
          type: number
          description: Cargo weight used
        weight_basis:
          type: string
          enum:
          - weight
          - teu
        container_load:
          type: string
          description: Container load profile that set the tonnes per TEU
        legs:
          type: array
          items:
            $ref: '#/components/schemas/LegResult'
        hubs:
          type: array
          items:
            type: object
            properties:
              hub_id:
                type: string
              hub_type:
                type: string
              wtw_kg:
                type: number
              data_type:
                $ref: '#/components/schemas/DataType'
              source:
                type: string
        tonne_km:
          type: number
        ttw_kg:
          type: number
        wtw_kg:
          type: number
          description: Transport plus hubs
        intensity_g_per_tkm:
          type: number
          description: Transport WTW only
        wtt_kg:
          type: number
          description: Transport well-to-tank (hubs are WTW only)
        primary_data_share:
          type: number
          description: Share of WTW emissions from primary data (0-1)
        ghg_protocol:
          type: object
          description: 'WTW in GHG Protocol scopes. A company buying the transport reports all of it in scope 3 (category 4 or 9); the operator of the vehicles splits it into scope 1 (fuel burnt), scope 2 (electricity, including the upstream share its factor contains) and scope 3 category 3 (fuel production and delivery); hubs are WTW only.

            '
          properties:
            scope3_shipper_kg:
              type: number
            operator_scope1_kg:
              type: number
            operator_scope2_kg:
              type: number
            operator_scope3_cat3_kg:
              type: number
            hubs_kg:
              type: number
        dataset:
          type: string
        warnings:
          type: array
          items:
            type: string
          description: Things left as given that may make the result too low, e.g. a gap between legs not counted
    OwnFactor:
      type: object
      description: The carrier's or your own intensity for a leg (primary data, ISO 14083 7.2.3), used instead of a default value.
      required:
      - wtw_g_per_tkm
      - source
      properties:
        wtw_g_per_tkm:
          type: number
          exclusiveMinimum: 0
        ttw_g_per_tkm:
          type: number
          minimum: 0
          description: Part of WTW; the rest is WTT
        source:
          type: string
          description: Who measured it
          and for what (e.g. the carrier's TOC report and year): null
        distance_basis:
          type: string
          enum:
          - sfd
          - gcd
          - actual
          description: Distance type the intensity is per tonne-km of. Absent = the leg's own distance type, so no DAF.
    Leg:
      type: object
      required:
      - mode
      properties:
        id:
          type: string
        mode:
          $ref: '#/components/schemas/Mode'
        cargo_type:
          type: string
          description: Overrides the shipment's cargo_type for this leg
        vehicle_type:
          type: string
          example: hgv
          description: Must exist in the loaded dataset; list them with GET /v1/factors
        from:
          $ref: '#/components/schemas/Location'
        to:
          $ref: '#/components/schemas/Location'
        distance_km:
          type: number
          description: Overrides computed distance when > 0
        distance_type:
          $ref: '#/components/schemas/DistanceType'
        fuel:
          $ref: '#/components/schemas/FuelUse'
        load_factor:
          type: number
          exclusiveMinimum: 0
          maximum: 1
          description: 'Load as a share of the load model''s payload (DESNZ''s average full load, e.g. 17.9 t for an artic over 33 t), not of the truck''s rated payload; switches the leg to the dataset''s load model. Give this or load_tonnes. In GLEC and EcoTransIT a load factor is a share of the rated payload, so the same value means more tonnes there: to compare, or when the weight is known, give load_tonnes.

            '
        load_tonnes:
          type: number
          exclusiveMinimum: 0
          description: 'Tonnes on the truck (all cargo, average over the loaded km); switches the leg to the load model. Up to 1.6 × the model''s payload: above its payload the model is extended linearly.

            '
        empty_trip_factor:
          type: number
          minimum: 0
          description: Empty km per loaded km (needs load_factor or load_tonnes)
        repositioning_km:
          type: number
          minimum: 0
          description: 'Trucks: km driven empty for this trip (to the pickup, or back after delivery), shared over the truck''s load like empty running (added to the empty trip factor as km per actual loaded km). Without a load, the shipment is taken as the truck''s whole load.

            '
        energy_kwh_per_tkm:
          type: number
          exclusiveMinimum: 0
          description: Electricity per tonne-km; with country, switches the leg to the energy method
        country:
          type: string
          description: ISO 3166-1 alpha-3 country whose grid powers the leg, e.g. DNK
        own_factor:
          $ref: '#/components/schemas/OwnFactor'
  responses:
    Busy:
      description: Too many requests in progress; retry after the given seconds
      headers:
        Retry-After:
          schema:
            type: integer
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
    Error:
      description: Error
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string