RecommendResult

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/carbonara-co2-org/json-schema/carbonara-co2-org-recommend-result-schema.json",
  "title": "RecommendResult",
  "x-generated": "2026-11-03",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/carbonara-co2-org-openapi.yaml#/components/schemas/RecommendResult",
  "type": "object",
  "properties": {
    "label": {
      "type": "string"
    },
    "settings": {
      "$ref": "#/$defs/RecommendSettings"
    },
    "skipped": {
      "type": "object",
      "additionalProperties": {
        "type": "string"
      }
    },
    "now": {
      "$ref": "#/$defs/ScenarioTotals"
    },
    "best": {
      "$ref": "#/$defs/ScenarioTotals"
    },
    "saved_kg": {
      "type": "number"
    },
    "saved_pct": {
      "type": "number"
    },
    "kinds": {
      "type": "array",
      "items": {
        "type": "object"
      },
      "description": "Per kind: shipments, saved_kg, best_for and its GLEC reduction area"
    },
    "areas": {
      "type": "array",
      "items": {
        "type": "object"
      },
      "description": "GLEC v3.3's five reduction areas (id, name, kinds tried in each)"
    },
    "lanes": {
      "type": "array",
      "items": {
        "type": "object"
      }
    },
    "sources": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "limitations": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "failed": {
      "type": "integer"
    },
    "shipments": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "shipment_id": {
            "type": "string"
          },
          "lane": {
            "type": "string"
          },
          "weight_kg": {
            "type": "number"
          },
          "now": {
            "$ref": "#/$defs/RecommendRoute"
          },
          "legs": {
            "type": "array",
            "items": {
              "type": "object"
            },
            "description": "The shipment's own legs"
          },
          "options": {
            "type": "array",
            "items": {
              "allOf": [
                {
                  "$ref": "#/$defs/RecommendRoute"
                },
                {
                  "type": "object",
                  "properties": {
                    "kind": {
                      "type": "string"
                    },
                    "summary": {
                      "type": "string"
                    },
                    "saved_kg": {
                      "type": "number"
                    },
                    "saved_pct": {
                      "type": "number"
                    },
                    "extra_km_pct": {
                      "type": "number"
                    },
                    "legs": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    }
                  }
                }
              ]
            }
          },
          "notes": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "error": {
            "type": "string"
          },
          "retryable": {
            "type": "boolean",
            "description": "The error is temporary (a routing service that didn't answer): try again later"
          }
        }
      }
    }
  },
  "$defs": {
    "RecommendRoute": {
      "type": "object",
      "properties": {
        "ttw_kg": {
          "type": "number"
        },
        "wtt_kg": {
          "type": "number"
        },
        "wtw_kg": {
          "type": "number"
        },
        "biogenic_co2_kg": {
          "type": "number"
        },
        "distance_km": {
          "type": "number"
        },
        "transfers": {
          "type": "integer",
          "description": "Changes of mode along the route"
        },
        "modes": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "steps": {
          "type": "array",
          "items": {
            "type": "object"
          }
        },
        "terminals": {
          "type": "array",
          "description": "Alternatives only: the terminal handlings the alternative adds to now (GLEC v3.3 intermodal terminal, per container; included in the totals). Same fields as a result's hubs.",
          "items": {
            "type": "object"
          }
        }
      }
    },
    "RecommendSettings": {
      "type": "object",
      "properties": {
        "kinds": {
          "type": "array",
          "items": {
            "type": "string",
            "enum": [
              "road_to_rail",
              "road_to_waterway",
              "road_to_short_sea",
              "air_to_sea",
              "air_to_rail",
              "other_port",
              "fuller_loads",
              "larger_truck",
              "electric_truck",
              "bio_lng_truck"
            ]
          },
          "description": "Kinds to try; empty means all (fuller_loads only with a load)"
        },
        "min_road_km": {
          "type": "number",
          "description": "Road legs longer than this are tried on rail, waterway and short sea (default 300)"
        },
        "min_main_km": {
          "type": "number",
          "description": "The rail, waterway or sea part must be longer than this in a straight line (default 100)"
        },
        "max_port_road_km": {
          "type": "number",
          "description": "Road to and from a waterway or sea port within this of it in a straight line (default 150)"
        },
        "terminal": {
          "type": "string",
          "enum": [
            "nearest",
            "best_trip"
          ]
        },
        "rail_vehicle": {
          "type": "string",
          "description": "default freight_train"
        },
        "waterway_vehicle": {
          "type": "string",
          "description": "default container_barge"
        },
        "short_sea_vehicle": {
          "type": "string",
          "description": "default roro"
        },
        "sea_vehicle": {
          "type": "string",
          "description": "default container_ship (air to sea)"
        },
        "port_radius_km": {
          "type": "number",
          "description": "Other ports within this of the port used now (default 800)"
        },
        "max_ports": {
          "type": "integer",
          "description": "Other ports to try per port (default 4)"
        },
        "load_tonnes": {
          "type": "number"
        },
        "load_factor": {
          "type": "number"
        },
        "empty_trip_factor": {
          "type": "number"
        },
        "load_vehicle": {
          "type": "string"
        },
        "source": {
          "type": "string",
          "description": "Where the load values come from"
        }
      }
    },
    "ScenarioTotals": {
      "type": "object",
      "properties": {
        "ttw_kg": {
          "type": "number"
        },
        "biogenic_co2_kg": {
          "type": "number",
          "description": "Biogenic CO2, reported separately and not included in the totals (GLEC v3.3 p. 64)"
        },
        "wtt_kg": {
          "type": "number"
        },
        "wtw_kg": {
          "type": "number"
        }
      }
    }
  }
}