# collection and delivery calculation

calculate a collection and delivery round ("milkrun") from json input

Endpoint: POST /etw-rest/calculateCollectionAndDelivery
Version: 2025r4.1.4
Security: oAuth2AuthorizationCode

## Request fields (application/json):

  - `accounting` (object)

  - `accounting.cooledTransport` (object)
    If cooledTransport is set to true, all legs of the tour will be considered as cooled transport.

  - `accounting.cooledTransport.value` (boolean, required)
    Example: true

  - `transportChainElements` (array, required)
    The shipmentIds of the loads/unloads of the first transportChainElement will be ommitted because the emissionPercentage for them will always be 0 by definition.
    Example: [{"location":{"locationType":"ZIP_CODE","country":"DE","code":20539},"load":[{"cargo":{"unit":"TONS","amount":20}}]},{"location":{"locationType":"ZIP_CODE","country":"DE","code":30167},"unload":[{"cargo":{"unit":"TONS","amount":15},"freightUnitIdentifier":"terminalhannoverCustomerA","listEmissionsInResponse":true},{"cargo":{"unit":"TONS","amount":5},"freightUnitIdentifier":"terminalhannoverCustomerB","listEmissionsInResponse":true}]}]

  - `transportChainElements.location` (object)

  - `transportChainElements.load` (array)

  - `transportChainElements.load.cargo` (object, required)
    Example: {"unit":"TONS","amount":42}

  - `transportChainElements.load.freightUnitIdentifier` (string)
    Only Informational. Will also occur in Response. Use this to identify/tag/descripe your Loads/Unloads 
FreightUnitIdentifier is optional but it is strongly recommended to use the value to identify your Loads/Unloads in the response.

  - `transportChainElements.load.listEmissionsInResponse` (boolean)
    If set to false the emissions for this load/unload will not be shown in the response

  - `transportChainElements.unload` (array)

  - `transportChainElements.carriageParameters` (object)

  - `transportChainElements.carriageParameters.transportMode` (string, required)
    Example: "ROAD"

  - `transportChainElements.carriageParameters.loadFactor` (object)
    transported weight [t] / Maximum Payload of transport  unit [t], expressed as percentage

  - `transportChainElements.carriageParameters.loadFactor.unit` (string)
    Enum: "PERCENTAGE"

  - `transportChainElements.carriageParameters.virtualDistance` (object)
    disables the routing and overrides the distance used for calculation. For truck transports the emission calculation for a motorway is assumed

  - `transportChainElements.carriageParameters.distanceAdjustmentFactor` (object)
    Factor for operational derivations in percentage. Increases the overall distance. 
E.g.: distanceAdjustmentFactor of 5 increases the calculated distance from 100km to 105km 
For sea transports with clean cargo activated the distanceAdjustmentFactor is set to 15 by default as suggested by clean cargo. 
Providing a custom distanceAdjustmentFactor for clean cargo transports will override the default value and is

  - `transportChainElements.carriageParameters.emissionClass` (string)
    The emissionClass of the transport vehicle
    Enum: "EU_EURO_1", "EU_EURO_2", "EU_EURO_3", "EU_EURO_4", "EU_EURO_5", "EU_EURO_6", "EU_EURO_6AC", "EU_EURO_6DE", "US_EPA_1994", "US_EPA_1998", "US_EPA_2004", "US_EPA_2007", "US_EPA_2010", "JP_1994", "JP_1997", "JP_2003", "JP_2005", "JP_2009", "JP_2016", "US_MOVES_1999", "US_MOVES_2000", "US_MOVES_2002", "US_MOVES_2006", "US_MOVES_2009", "US_MOVES_2013", "US_MOVES_2016", "US_MOVES_2020", "US_MOVES_2023"

  - `transportChainElements.carriageParameters.truckType` (string)
    The truckType used for transportation (e.g. Class40 for truck with max. vehicle weight of 40 tons)
    Enum: "CLASS_CAR", "CLASS_N1_I", "CLASS_N1_II", "CLASS_N1_III", "CLASS_3_5", "CLASS_7_5", "CLASS_12", "CLASS_20", "CLASS_26", "CLASS_40", "CLASS_44", "CLASS_50", "CLASS_60", "CLASS_GT_60", "CLASS_16KLBS", "CLASS_26KLBS", "CLASS_44KLBS", "CLASS_60KLBS", "CLASS_80KLBS", "CLASS_100KLBS", "CLASS_130KLBS", "CLASS_GT_100KLBS", "CLASS_GT_130KLBS", "CLASS_14KLBS_RIGID", "CLASS_19_5KLBS_RIGID", "CLASS_33KLBS_RIGID", "CLASS_33KLBS_ARTICULATED", "CLASS_80KLBS_RIGID", "CLASS_80KLBS_ARTICULATED", "CLASS_80KLBS_ARTICULATED_GLIDER"

  - `transportChainElements.carriageParameters.emptyTripFactor` (object)

  - `transportChainElements.carriageParameters.emptyTripFactor.value` (number)
    By default the empty run factor will be defined by the type of truck load (for road calculation) or the train type (for rail calculations). 
  
see schema for trainType  
 
| Truck load | Empty run factor |
|------------|------------------|
| FTL        | 20%              |
| LTL        | 15%              |
    Example: 75

  - `transportChainElements.carriageParameters.coolingType` (object)

  - `transportChainElements.carriageParameters.coolingType.value` (string, required)
    | Option   | Description (compatibility)                                           |
|----------|-------------------------------------------------------|
| AUTO     | Automatically selection (Default) |
|---|---|
| COOLED_BOX     | CLASS_N1_III, CLASS_7_5, CLASS_12, CLASS_20, CLASS_26, CLASS_40, CLASS_44  |
|                |CLASS_14KLBS_RIGID, CLASS_19_5KLBS_RIGID, CLASS_33KLBS_RIGID, CLASS_33KLBS_ARTICULATED, CLASS_80KLBS_RIGID, CLASS_80KLBS_ARTICULATED, CLASS_80KLBS_ARTICULATED_GLIDER|
|---|---|
| REEFER_UNREGULATED |  CLASS_44, CLASS_50, CLASS_60, CLASS_GT_60 |
|---|---|
| REEFER_REGULATED |  CLASS_44, CLASS_50, CLASS_60, CLASS_GT_60 |
    Enum: "AUTO", "COOLED_BOX", "REEFER_UNREGULATED", "REEFER_REGULATED"

  - `transportChainElements.carriageParameters.ferryRouting` (string)
    Option | Description |
---| ---|
PREFERRED | Ferry lines will be preferred |
NORMAL | Normal ferry consideration (default) |
OBSTRUCT |  Ferry lines will be avoided |
    Enum: "PREFERRED", "NORMAL", "OBSTRUCT"

  - `transportChainElements.carriageParameters.truckLoad` (object)
    provide instead of loadFactor. Depending on value and parameters loadFactor will be calculated automatically 
| Options| Description |
| FTL  |Full Truck Load |
| LTL |Less than truck load|
| FCL |Full container load|
| AUTO | Automatic determination of FTL or LTL truck load |
To calculate LCL please calculate a part container on the base of the t/TEU or t/FEU (e.g. 50% of the container are 0.5 TEU).

  - `transportChainElements.carriageParameters.truckLoad.value` (string, required)
    FTL (full truck load): shipment fills complete truck. LoadFactor is calculated as freight weight / Maximum Payload. If LoadFactor is greater than 100% LTL is assumed. 
LTL (less then truck load): combining multiple shipments from different customers into a single truck. loadFactorLTL is assumed as loadFactor." 
FCL (full container load) 
AUTO: Automatic determination of FTL or LTL truck load
    Enum: "FTL", "LTL", "FCL", "AUTO"

  - `transportChainElements.carriageParameters.truckLoad.parameters` (object)
    parameters to further specify the truck Load

  - `transportChainElements.carriageParameters.truckLoad.parameters.loadFactorLTL` (integer)
    Applied load factor for LTL truck load.

  - `transportChainElements.carriageParameters.truckLoad.parameters.autoThresholdLoadFactor` (integer)
    If the Auto calculation would determine a load factor below the threshold or above 100 percent, a LTL truck load will be applied with the corresponding load factor. By default 50% will be applied.

  - `transportChainElements.carriageParameters.truckWeight` (object)
    Input: Specify either vehicleEmptyWeight directly or truckBodyType which then calculates the EmptyWeight automatically. 
If both values are provided the vehicleEmptyWeight will be taken into account and the truckBodyType will be ignored.

  - `transportChainElements.carriageParameters.truckWeight.truckBodyType` (object)
    If Body Type is selected vehicleEmptyWeight is calculated automatically. You can not specify truckBodyType and vehicleEmptyWeight.

  - `transportChainElements.carriageParameters.truckWeight.vehicleEmptyWeight` (object)
    If Body Type is selected vehicleEmptyWeight is calculated automatically. You cannot specify truckBodyType and vehicleEmptyWeight.

  - `transportChainElements.carriageParameters.containerCount` (object)

  - `transportChainElements.carriageParameters.containerCount.value` (integer, required)
    Number of transported containers on a truck.

  - `transportChainElements.carriageParameters.userSpecificEmissions` (object)

  - `transportChainElements.carriageParameters.userSpecificEmissions.operational` (array)

  - `transportChainElements.carriageParameters.userSpecificEmissions.operational.country` (string)
    ISO 3166-1 ALPHA-2 code of the country

  - `transportChainElements.carriageParameters.userSpecificEmissions.operational.fuelType` (string)
    Enum: "DIESEL", "LNG", "CNG", "ELECTRICITY"

  - `transportChainElements.carriageParameters.userSpecificEmissions.provisionPlusOperational` (array)

  - `transportChainElements.carriageParameters.userSpecificEmissions.provisionPlusOperational.emissionType` (string, required)
    Enum: "CO2_EQUIVALENTS", "NITROGEN_OXIDES", "NON_METHAN_HYDRO_CARBONS", "SULFUR_DIOXIDES", "PARTICLES"

  - `transportChainElements.carriageParameters.userSpecificEmissions.totalEmissionReduction` (array)

  - `transportChainElements.carriageParameters.energyComposition` (object)

  - `transportChainElements.carriageParameters.energyComposition.shares` (array, required)

  - `settings` (object)

  - `settings.showRoute` (boolean)
    Defines whether the transport emission for each leg shall be shown in the response in addition to the total emissions.

  - `settings.createKml` (boolean)
    If true, the response will include a Url to a KML file. The KML file will contain the route of the transport chain elements. 
The route can then be displayed for example in google earth. The shown routing is simplified, while for the calculation the proper routing has been used.

  - `settings.closedTour` (boolean)
    first specified location is start and end point of a closed round trip (default). An empty trip between the last location and the starting location is added automatically 
: last specified location is end point of the trip.
    Example: true

  - `settings.useLocationAliasTable` (boolean)
    Defines whether a previously uploaded alias table for locations should be used

## Response 200 fields (application/vnd.ecotransit.app.v2025r2+json):

  - `emissionsPerFreightUnit` (array)
    Note that the emissions for the load/undload elements of the first transportChainElement
from the request are not shown in the response because they are always 0 by definition!

  - `emissionsPerFreightUnit.freightUnitIdentifier` (string)
    identifier as specified in the original request

  - `emissionsPerFreightUnit.emissionPercentage` (number)
    Percentage of the calculated total emission of the whole round trip. 0.75 means 75 % of the total emissions.

  - `emissionsPerFreightUnit.linearDistance` (object)
    straight line distance between two locations as the crow flies

  - `emissionsPerFreightUnit.linearDistance.unit` (string, required)
    Enum: "KILOMETER"

  - `emissionsPerFreightUnit.linearDistance.value` (number, required)

  - `emissionsPerFreightUnit.location` (string)
    short description of the location where the freight unit was loaded/unloaded

  - `emissionsPerFreightUnit.load` (object)

  - `emissionsPerFreightUnit.load.cargo` (object, required)
    Example: {"unit":"TONS","amount":42}

  - `emissionsPerFreightUnit.load.freightUnitIdentifier` (string)
    Only Informational. Will also occur in Response. Use this to identify/tag/descripe your Loads/Unloads 
FreightUnitIdentifier is optional but it is strongly recommended to use the value to identify your Loads/Unloads in the response.

  - `emissionsPerFreightUnit.load.listEmissionsInResponse` (boolean)
    If set to false the emissions for this load/unload will not be shown in the response

  - `emissionsPerFreightUnit.unload` (object)

  - `emissionsPerFreightUnit.emissions` (object)

  - `emissionsPerFreightUnit.emissions.primaryEnergy` (object, required)

  - `emissionsPerFreightUnit.emissions.primaryEnergy.energyProvision` (number, required)
    Upstream energy consumption and upstream emissions (= energy provision, production and distribution)

  - `emissionsPerFreightUnit.emissions.primaryEnergy.operational` (number, required)
    Final energy consumption and vehicle emissions (tank to wheel ttw)

  - `emissionsPerFreightUnit.emissions.primaryEnergy.total` (number, required)
    Total energy consumption and total emissions - Sum of operation and upstream figures (well to wheel wtw)

  - `emissionsPerFreightUnit.emissions.carbonDioxide` (object, required)

  - `emissionsPerFreightUnit.emissions.nitrogenOxides` (object, required)

  - `emissionsPerFreightUnit.emissions.sulfurDioxides` (object, required)

  - `emissionsPerFreightUnit.emissions.nonMethaneHydroCarbons` (object)

  - `emissionsPerFreightUnit.emissions.particles` (object)

  - `emissionsPerFreightUnit.emissions.co2Equivalents` (object, required)

  - `emissionsPerFreightUnit.emissions.distance` (object, required)

  - `emissionsPerFreightUnit.emissions.distance.total` (number, required)

  - `emissionsPerFreightUnit.emissions.transportActivity` (object)

  - `emissionsPerFreightUnit.emissions.co2EquivalentsIntensity` (object)

  - `emissionsPerFreightUnit.emissions.externalCosts` (object, required)

  - `emissionsPerFreightUnit.emissions.externalCosts.emissionCosts` (object, required)

  - `emissionsPerFreightUnit.emissions.externalCosts.emissionCosts.nitrogenOxidesExtCosts` (object, required)

  - `emissionsPerFreightUnit.emissions.externalCosts.emissionCosts.sulfurDioxidesExtCosts` (object, required)

  - `emissionsPerFreightUnit.emissions.externalCosts.emissionCosts.nonMethanHydroCarbonsExtCosts` (object, required)

  - `emissionsPerFreightUnit.emissions.externalCosts.emissionCosts.particlesExtCosts` (object, required)

  - `emissionsPerFreightUnit.emissions.externalCosts.emissionCosts.co2EquivalentsExtCosts` (object, required)

  - `emissionsPerFreightUnit.emissions.externalCosts.accidentCosts` (object, required)

  - `emissionsPerFreightUnit.emissions.externalCosts.noiseCosts` (object, required)

  - `emissionsPerFreightUnit.emissions.externalCosts.totalCosts` (object, required)

  - `emissionsPerFreightUnit.emissions.dieselFuelConsumption` (object)
    displays consumption of vehicle in liter per 100 km.   will soon be fully replaced by energyCarrier output

  - `transportOperationCategory` (array)
    List of transport chain elements (TCE) showing the emissions for each leg for the whole freight

  - `transportOperationCategory.information` (object, required)

  - `transportOperationCategory.information.numberOfTransportChainElement` (string, required)
    indicating the number of the transport chain element (tce), if there is more than one
    Example: "tce 1 of 3"

  - `transportOperationCategory.information.cargo` (string, required)
    cargo transportet in this leg
    Example: "Cargo 20.0 ton"

  - `transportOperationCategory.route` (object, required)

  - `transportOperationCategory.route.origin` (object, required)
    in the Response location is always a wgs84Coordinate

  - `transportOperationCategory.route.origin.notifications` (array)

  - `transportOperationCategory.route.origin.notifications.key` (string, required)

  - `transportOperationCategory.route.origin.notifications.level` (string)
    Enum: "INFO", "WARNING"

  - `transportOperationCategory.route.origin.notifications.category` (string)
    Enum: "LOCATION", "PARAMETER", "INTERNAL", "ROUTING", "ERROR_HANDLING", "CONFIGURATION"

  - `transportOperationCategory.route.origin.notifications.message` (string, required)
    Example: "Flight number(s) LH123 are related to origin location airport:MUC."

  - `transportOperationCategory.route.origin.notifications.action` (string)

  - `transportOperationCategory.route.origin.notifications.values` (object)
    map with values to make message more machine readable
    Example: {"flightNumber":"LH123","originLocation":"MUC"}

  - `transportOperationCategory.route.origin.wgs84Coordinate` (object, required)

  - `transportOperationCategory.route.origin.wgs84Coordinate.latitude` (number, required)
    Example: 52.38723

  - `transportOperationCategory.route.origin.wgs84Coordinate.longitude` (number, required)
    Example: 9.74021

  - `transportOperationCategory.route.origin.name` (string)

  - `transportOperationCategory.route.origin.codeType` (string)
    Enum: "ZIP_CODE", "UN_LOCODE", "IATA_CODE", "UIC_CODE", "NAME"

  - `transportOperationCategory.route.origin.countryCode` (string)
    ISO 3166-1 ALPHA-2 code of the country

  - `transportOperationCategory.route.origin.code` (string)

  - `transportOperationCategory.route.origin.transportModeChange` (string)
    Enum: "ROAD", "RAIL", "SEA", "AIR", "INLANDWATERS", "LOGISTIC_HUB"

  - `transportOperationCategory.route.origin.carriageChange` (string)
    Enum: "PRE_CARRIAGE", "MAIN_CARRIAGE", "POST_CARRIAGE"

  - `transportOperationCategory.route.origin.railTractionTypeChange` (string)
    Enum: "DIESEL", "ELECTRICAL", "DIESEL_AS_ELECTRIC"

  - `transportOperationCategory.route.destination` (object, required)
    in the Response location is always a wgs84Coordinate

  - `transportOperationCategory.userSpecificEmissions` (object)

  - `transportOperationCategory.carriageParameters` (any, required)

  - `transportOperationCategory.energyCarriers` (array, required)

  - `transportOperationCategory.energyCarriers.energyType` (string)
    Enum: "GASOLINE", "BIO_ETHANOL", "DIESEL", "BIO_DIESEL", "HVO", "CNG", "BIO_CNG", "LNG", "BIO_LNG", "KEROSENE", "ELECTRICITY", "HYDROGEN", "PHEV", "HFO", "MDO", "ULSFO", "BLENDS", "LPG"

  - `transportOperationCategory.energyCarriers.productionType` (string)
    Enum: "FOSSIL", "COUNTRY_MIX", "MIX", "RAPESEED_OIL", "SOY_OIL", "UCO", "MAIZE", "MANURE", "BIOWASTE", "GREY_HYDROGEN", "GREEN_HYDROGEN", "YELLOW_HYDROGEN"

  - `transportOperationCategory.energyCarriers.consumption` (array)
    displays consumption in multiple units

  - `transportOperationCategory.energyCarriers.consumption.unit` (string)
    liter, kg, kWh, or megajoule
    Enum: "LITER", "KILOGRAMS", "KILOWATT_HOUR", "MEGAJOULE"

  - `kmlFile` (string)
    specifies the URL of the KML file that displays the route taken by the truck

## Response 400 fields (application/problem+json):

  - `type` (string, required)
    a URI reference that identifies the problem via an errorKey. URI is not resolvable at the moment, but might be in the future
    Enum: "LOCATION", "PARAMETER", "INTERNAL", "ROUTING", "ERROR_HANDLING", "CONFIGURATION"

  - `title` (string, required)
    a short, human-readable summary of the error
    Example: "Location not found"

  - `status` (integer, required)
    indicating the HTTP status code
    Example: 400

  - `detail` (string, required)
    human-readable explanation specific to this occurrence of the problem
    Example: "could not find Location for IATA code: ZZZ"

  - `instance` (string)
    URI reference that identifies the specific occurrence of the problem
    Example: "/calculateTransport"

  - `action` (string)
    proposed action to solve the problem
    Example: "Verify location existence or define another location."

  - `timestamp` (string)
    date and time (in UTC) when the error occurred (YYYY-MM-DD)
    Example: "2024-06-30T06:39:25Z"

## Response 401 fields (application/problem+json):

  - `type` (string, required)
    a URI reference that identifies the problem via an errorKey. URI is not resolvable at the moment, but might be in the future
    Enum: "LOCATION", "PARAMETER", "INTERNAL", "ROUTING", "ERROR_HANDLING", "CONFIGURATION"

  - `title` (string, required)
    a short, human-readable summary of the error
    Example: "Location not found"

  - `status` (integer, required)
    indicating the HTTP status code
    Example: 400

  - `detail` (string, required)
    human-readable explanation specific to this occurrence of the problem
    Example: "could not find Location for IATA code: ZZZ"

  - `instance` (string)
    URI reference that identifies the specific occurrence of the problem
    Example: "/calculateTransport"

  - `action` (string)
    proposed action to solve the problem
    Example: "Verify location existence or define another location."

  - `timestamp` (string)
    date and time (in UTC) when the error occurred (YYYY-MM-DD)
    Example: "2024-06-30T06:39:25Z"