User Guide¶
Transport Carbon Calculator¶
Restricted | © Siemens 2025
Contents¶
About Transport Carbon Calculator (TCC)¶
The Transport Carbon Calculator (TCC) web service calculates transport emissions for single-leg relations between two locations, in conformance with the Global Logistics Emissions Council (GLEC) framework. TCC enables worldwide carbon equivalent emission calculations with minimal input requirements.
It provides two methodology options:
- Direct methodology - based on actual fuel consumption.
- Default methodology - based on emission factors.
TCC supports all commonly used transport channels: rail, road, sea, and air. Additionally, it calculates emissions produced at logistics sites, such as during transshipment processes. Users can select various equipment types for each transport channel, allowing for a more precise description of the transport and, consequently, a more accurate emission calculation. The option to choose between different fuel types further enhances the quality and accuracy of the calculation process.
Transport Carbon Calculator offers:
- Leg-based calculation of carbon equivalent emissions
- Fast and easy integration of GLEC methodology
- Direct or default calculation options
- Support for various equipment inputs (fuel, vehicle, etc.)
- Coverage of multiple transport channels (rail, road, sea, air, logistics sites)
- Worldwide coverage
- Integrated geocoding and georouting capabilities
GLEC Framework¶
The CO2 equivalents (CO2e) calculation module used by the service is accredited by Smart Freight Centre for being conform with the GLEC methodology as well as ISO 14083, ensuring the accuracy and reliability of the calculations. For more information about the GLEC Framework see Smart Freight Center.
Input and Output Contracts¶
A general costing service is called from the TcPCM wrapper process. The primary objective of this service is to provide the necessary functionality for the TcPCM use case. The long-term goal is to enable the costing service to be independently publishable.
Default values for equipment and fuel type¶
transportMode | validFrom | validTo | equipment | fuelType |
---|---|---|---|---|
road | 01.01.1900 | 31.12.2023 | Large Truck | Diesel |
air | 01.01.1900 | 31.12.2023 | freighter | Kerosene |
rail | 01.01.1900 | 31.12.2023 | ||
logisticsite | 01.01.1900 | 31.12.2023 | transhipment_mixed | |
sea | 01.01.1900 | 31.12.2023 | 20ft | HFO |
road | 01.01.2024 | 31.12.2024 | Large Truck | Diesel |
air | 01.01.2024 | 31.12.2024 | freighter | Kerosene |
rail | 01.01.2024 | 31.12.2024 | ||
logisticsite | 01.01.2024 | 31.12.2024 | transhipment_mixed | |
sea | 01.01.2024 | 31.12.2024 | 20ft | HFO |
road | 01.01.2025 | 31.12.2999 | Large Truck | Diesel |
air | 01.01.2025 | 31.12.2999 | freighter | Kerosene |
rail | 01.01.2025 | 31.12.2999 | ||
logisticsite | 01.01.2025 | 31.12.2999 | transhipment_mixed | |
sea | 01.01.2025 | 31.12.2999 | 20ft | HFO |
Input¶
Table "legs"¶
Name | Type | Values | Mandatory | Explanation |
---|---|---|---|---|
equipment | str | choices see below | no | Equipment, choices depend on fuelType and transportMode |
fuelType | str | choices see below | no | Fuel used. Choices depend on equipment and transportMode |
fuelConsumptionUnit | str | choices see below | no | Unit of the fuelConsumption (choices: "kwh/100km" (for electric), "l/100km" (for diesel, lpg, b5-diesel, kerosene), "kg/100km" (for diesel, lpg, b5-diesel, lng, cng, kerosene, mdo, hfo) |
shipmentDate | date | Any date in format "yyyy-mm-dd". Example: "2030-12-24" | no | Shipment date. If not date is given, current date will be used |
transportMode | str | ["Road", "Sea", "Air", "Rail", "logisticsite"] | yes | Used transport mode (choices: "logisticsite", "road", "air", "sea", "rail") |
shipmentId | str | yes | The identifier for the shipment. Case sensitive | |
legId | str | yes | The identifier for the transport legs. Case sensitive | |
senderLocationId | str | yes | Id of the sender location. Link to locations table | |
recipientLocationId | str | yes | Id of the recipient location. Link to locations table | |
distanceKm | float | no | Distance of the transport leg. Must be given in km. If not given, will be calculated | |
weightKg | float | yes | Gross transport weight including packaging. Must be given in kg | |
volumeCbm | float | no | Gross volume including packaging. Must be given in cbm | |
loadingMeterM | float | no | Gross loading meter including packaging. Must be given in meter | |
fuelConsumption | float | no | Consumption. If given, is used to calculate the CO2e. If given fuelType must be given. Unit of measurement depends on chosen fuelType |
Allowed Values for Different Columns in the Table "Legs"¶
Road¶
Equipment for Transport Mode Road¶
Valid From | Valid To | Equipment | Fuel Type |
---|---|---|---|
01.01.1900 | 31.12.2023 | Sprinter | Diesel |
01.01.1900 | 31.12.2023 | Small Truck | Diesel |
01.01.1900 | 31.12.2023 | Medium Truck | Diesel |
01.01.1900 | 31.12.2023 | Large Truck | Diesel |
01.01.2024 | 31.12.2024 | Sprinter | Diesel |
01.01.2024 | 31.12.2024 | Small Truck | Diesel |
01.01.2024 | 31.12.2024 | Medium Truck | Diesel |
01.01.2024 | 31.12.2024 | Large Truck | Diesel |
01.01.2025 | 31.12.2999 | Sprinter | Diesel |
01.01.2025 | 31.12.2999 | Small Truck | Diesel |
01.01.2025 | 31.12.2999 | Medium Truck | Diesel |
01.01.2025 | 31.12.2999 | Large Truck | Diesel |
01.01.2025 | 31.12.2999 | Sprinter | Electric |
01.01.2025 | 31.12.2999 | Small Truck | Electric |
01.01.2025 | 31.12.2999 | Medium Truck | Electric |
01.01.2025 | 31.12.2999 | Large Truck | Electric |
01.01.2025 | 31.12.2999 | Sprinter | CNG |
01.01.2025 | 31.12.2999 | Small Truck | CNG |
01.01.2025 | 31.12.2999 | Medium Truck | CNG |
01.01.2025 | 31.12.2999 | Large Truck | CNG |
01.01.2025 | 31.12.2999 | Large Truck | LNG |
Fuel Consumption Unit for Transport Mode Road¶
- Kwh / 100 km (for fuelType Electric)
- L / 100 km (for fuelType Diesel, LPG, B5-diesel)
- Kg / 100 km (for fuelType Diesel, LPG, B-diesel, LNG, CNG)
Fuel Type for Transport Mode Road¶
- Diesel
- LPG
- B5-diesel
- Electric
- LNG
- CNG
Rail¶
Equipment for Transport Mode Rail¶
Valid From | Valid To | Equipment | Fuel Type |
---|---|---|---|
01.01.1900 | 31.12.2025 | Diesel | Diesel |
01.01.1900 | 31.12.2025 | Light Diesel | Diesel |
01.01.1900 | 31.12.2025 | Average Diesel | Diesel |
01.01.1900 | 31.12.2025 | Extralarge Diesel | Diesel |
01.01.1900 | 31.12.2025 | Heavy Diesel | Diesel |
01.01.1900 | 31.12.2025 | Car Diesel | Diesel |
01.01.1900 | 31.12.2025 | Chemistry Diesel | Diesel |
01.01.1900 | 31.12.2025 | Container Diesel | Diesel |
01.01.1900 | 31.12.2025 | Coalandsteel Diesel | Diesel |
01.01.1900 | 31.12.2025 | Buildingmaterials Diesel | Diesel |
01.01.1900 | 31.12.2025 | Manufacturedproducts Diesel | Diesel |
01.01.1900 | 31.12.2025 | Cereals Diesel | Diesel |
01.01.1900 | 31.12.2025 | Highspeed Diesel | Diesel |
01.01.1900 | 31.12.2025 | Doublestackcontainer Diesel | Diesel |
01.01.1900 | 31.12.2025 | Rollingroad Diesel | Diesel |
01.01.1900 | 31.12.2025 | Electric | Electric |
01.01.1900 | 31.12.2025 | Light Electric | Electric |
01.01.1900 | 31.12.2025 | Average Electric | Electric |
01.01.1900 | 31.12.2025 | Extralarge Electric | Electric |
01.01.1900 | 31.12.2025 | Heavy Electric | Electric |
Fuel Consumption Unit for Transport Mode Rail¶
- NA
Fuel Type for Transport Mode Rail¶
- NA
Air¶
Equipment for Transport Mode Air¶
Valid From | Valid To | Equipment |
---|---|---|
01.01.1900 | 31.12.2023 | Unknown |
01.01.1900 | 31.12.2023 | Belly Freight |
01.01.1900 | 31.12.2023 | Freighter |
01.01.2024 | 31.12.2024 | Unknown |
01.01.2024 | 31.12.2024 | Belly Freight |
01.01.2024 | 31.12.2024 | Freighter |
01.01.2025 | 31.12.2999 | Unknown |
01.01.2025 | 31.12.2999 | Belly Freight |
01.01.2025 | 31.12.2999 | Freighter |
Fuel Consumption Unit for Transport Mode Air¶
- L / 100 km
- Kg / 100 km
Fuel Type for Transport Mode Air¶
- Kerosene
Sea¶
Equipment for Transport Mode Sea¶
Valid From | Valid To | Equipment |
---|---|---|
01.01.1900 | 31.12.2023 | 20ft_Reefer |
01.01.1900 | 31.12.2023 | 20ft |
01.01.1900 | 31.12.2023 | 40ft_Reefer |
01.01.1900 | 31.12.2023 | 40ft |
01.01.1900 | 31.12.2023 | 40ftHC_Reefer |
01.01.1900 | 31.12.2023 | 40ftHC |
01.01.2024 | 31.12.2024 | 20ft_Reefer |
01.01.2024 | 31.12.2024 | 20ft |
01.01.2024 | 31.12.2024 | 40ft_Reefer |
01.01.2024 | 31.12.2024 | 40ft |
01.01.2024 | 31.12.2024 | 40ftHC_Reefer |
01.01.2024 | 31.12.2024 | 40ftHC |
01.01.2025 | 31.12.2999 | 20ft_Reefer |
01.01.2025 | 31.12.2999 | 20ft |
01.01.2025 | 31.12.2999 | 40ft_Reefer |
01.01.2025 | 31.12.2999 | 40ft |
01.01.2025 | 31.12.2999 | 40ftHC_Reefer |
01.01.2025 | 31.12.2999 | 40ftHC |
Fuel Consumption Unit for Transport Mode Sea¶
- Kg / 100 km
Fuel Type for Transport Mode Sea¶
- MDO
- HFO
Logisticsite¶
Equipment for Transport Mode Logisticsite¶
Valid From | Valid To | Equipment |
---|---|---|
01.01.1900 | 31.12.2023 | Transhipment Ambient |
01.01.1900 | 31.12.2023 | Transhipment Mixed |
01.01.1900 | 31.12.2023 | Storage Transhipment Ambient |
01.01.1900 | 31.12.2023 | Storage Transhipment Mixed |
01.01.1900 | 31.12.2023 | Warehouse Ambient |
01.01.1900 | 31.12.2023 | Warehouse Mixed |
01.01.1900 | 31.12.2023 | Container Terminal Ambient |
01.01.1900 | 31.12.2023 | Container Terminal Mixed |
01.01.1900 | 31.12.2023 | Liquid Bulk Terminal Ambient |
01.01.1900 | 31.12.2023 | Liquid Bulk Terminal Mixed |
01.01.2024 | 31.12.2024 | Transhipment Ambient |
01.01.2024 | 31.12.2024 | Transhipment Mixed |
01.01.2024 | 31.12.2024 | Storage Transhipment Ambient |
01.01.2024 | 31.12.2024 | Storage Transhipment Mixed |
01.01.2024 | 31.12.2024 | Warehouse Ambient |
01.01.2024 | 31.12.2024 | Warehouse Mixed |
01.01.2024 | 31.12.2024 | Container Terminal Ambient |
01.01.2024 | 31.12.2024 | Container Terminal Mixed |
01.01.2024 | 31.12.2024 | Liquid Bulk Terminal Ambient |
01.01.2024 | 31.12.2024 | Liquid Bulk Terminal Mixed |
01.01.2025 | 31.12.2999 | Transhipment Ambient |
01.01.2025 | 31.12.2999 | Transhipment Mixed |
01.01.2025 | 31.12.2999 | Storage Transhipment Ambient |
01.01.2025 | 31.12.2999 | Storage Transhipment Mixed |
01.01.2025 | 31.12.2999 | Warehouse Ambient |
01.01.2025 | 31.12.2999 | Warehouse Mixed |
01.01.2025 | 31.12.2999 | Container Terminal Ambient |
01.01.2025 | 31.12.2999 | Container Terminal Mixed |
01.01.2025 | 31.12.2999 | Liquid Bulk Terminal Ambient |
01.01.2025 | 31.12.2999 | Liquid Bulk Terminal Mixed |
Fuel Consumption Unit for Transport Mode Logisticsite¶
- NA
Fuel Type for Transport Mode Logisticsite¶
- NA
Table "Locations"¶
Name | Type | Mandatory | Explanation |
---|---|---|---|
id | str | yes | The unique identifier for the location. |
country | str | no/yes | The country of the location in ISO 3166-1 alpha-2 format, e.g. “DE” for Germany. Either country+postalCode+city is given or latitude+longitude. Parsing case insensitive. |
postalCode | str | no/yes | The postcode of the location. Either country+postalCode+city is given or latitude+longitude. |
city | str | no/yes | The city name of the location. Either country+postalCode+city is given or latitude+longitude. |
street | str | no | The street name of the location. |
housenumber | str | no | The housenumber of the location. |
latitude | float | no/yes | The latitude of the location. In decimal format. Either country+postalCode+city is given or latitude+longitude. |
longitude | float | no/yes | The longitude of the location. In decimal format. Either country+postalCode+city is given or latitude+longitude. |
Table "Parameters"¶
Name | Type | Mandatory | Explanation |
---|---|---|---|
key | str | no | Name of the parameter. |
value | str | no | Value of the parameter. |
postalCode | str | no/yes | The postcode of the location. Either country+postalCode+city is given or latitude+longitude. |
city | str | no/yes | The city name of the location. Either country+postalCode+city is given or latitude+longitude. |
street | str | no | The street name of the location. |
housenumber | str | no | The housenumber of the location. |
latitude | float | no/yes | The latitude of the location. In decimal format. Either country+postalCode+city is given or latitude+longitude. |
longitude | float | no/yes | The longitude of the location. In decimal format. Either country+postalCode+city is given or latitude+longitude. |
Output¶
Table "resultsLegs"¶
Key | Value | Description |
---|---|---|
shipmentId | str | The identifier for the shipment. |
legId | str | The identifier for the transport legs. |
transportMode | str | Transport mode used for this leg. |
co2eKg | float | Calculated Well-to-Wheel CO2e emissions in kg. |
wttCo2eKg | float | Calculated Well-to-Tank CO2e emissions in kg. |
ttwCo2eKg | float | Calculated Tank-to-Wheel CO2e emissions in kg. |
errorSeverity | str | Highest severity error type (Error, Warning, Hint, None) |
Table "resultLocations"¶
Key | Value | Description |
---|---|---|
id | str | The unique identifier for the location. Is created from shipment id, country code, and postal code. Ids for the transshipment locations are IATA or UN/LOCODES. |
latitude | float | The latitude of the location. |
longitude | float | The longitude of the location. |
errorSeverity | str | Highest severity error type (Error, Warning, Hint, None) |
Table "resultMessages"¶
Key | Value | Description |
---|---|---|
table | str | Name of the table to which the entry refers. |
causer | str | Depending on the Table, this field contains the shipment, leg, or location id. |
message | str | Message that explains the issue. |
severity | str | Severity of the error (Error, Warning, or Hint) |
code | str | Error code - see below |
Table "resultErrors"¶
If output errors occur in the result, a detailed message is given. There are three different error types:
- Hint: Hint for the user, which might be interesting, but with no effect on the results.
- Warning: Result could be calculated, but a workaround has been used.
- Error: Result could not be calculated.
The tables resultShipments, resultLegs, resultLocations only show the type, while the respective error message is listed in the resultErrors table. A data row can produce multiple errors. The affected table only shows the most severe error type, while all error types and messages are listed in the resultErrors table.
Output Errors for Table "resultLegs"¶
Type | Code | Message |
---|---|---|
Error | resultLegs_noShipmentId | "No shipmentId is given. Leg will not be processed further." |
Error | resultLegs_noLegId | "No legId is given. Leg will not be processed further." |
Error | resultLegs_legIdNotUnique | "The leg " + legId + " of the shipment (" + shipmentId + ") is not unique. Leg will not be processed further." |
Error | resultLegs_noSenderId | "For the leg " + legId + " of the shipment (" + shipmentId + ") no senderId is given. Leg will not be processed further." |
Error | resultLegs_noRecipientId | "For the leg " + legId + " of the shipment (" + shipmentId + ") no recipientId is given. Leg will not be processed further." |
Error | resultLegs_noDate | "For the leg " + legId + " of the shipment (" + shipmentId + ") no date is given. Leg will not be further proceeded." |
Error | resultLegs_dateTooLate | "For the leg " + legId + " of the shipment (" + shipmentId + ") the date is more than 15 years in the future. This is not covered. Leg will not be further proceeded." |
Warning | resultLegs_dateTooEarly | "For the leg " + legId + " of the shipment (" + shipmentId + ") the date is before the 01.01.2022. This is not covered. The 01.01.2022 will be used as leg data." |
Error | resultLegs_noWeightKg | "For the leg " + legId + " of the shipment (" + shipmentId + ") either no weightKg is given or weightKg <= 0 kg. Leg will not be processed further." |
Hint | resultLegs_weightKgTooHeavy | "For the leg " + legId + " of the shipment (" + shipmentId + ") the weightKg > 25000 kg." |
Hint | resultLegs_weightKgTooLight | "For the leg " + legId + " of the shipment (" + shipmentId + ") the weightKg < 1 kg." |
Hint | resultLegs_noDistanceKm | "For the leg " + legId + " of the shipment (" + shipmentId + ") no distanceKm is given. Distance will be calculated." |
Hint | resultLegs_distanceKm<=0 | "For the leg " + legId + " of the shipment (" + shipmentId + ") the distanceKm <= 0 km. Distance will be recalculated." |
Error | resultLegs_senderIdGeoInformationMissing | "For the leg " + legId + " of the shipment (" + shipmentId + ") the sender geocoding information is missing. The leg will not be further processed." |
Error | resultLegs_recipientIdGeoInformationMissing | "For the leg " + legId + " of the shipment (" + shipmentId + ") the recipient geocoding information is missing. The leg will not be further processed." |
Error | resultLegs_noKnownTransportMode | "For the leg " + legId + " of the shipment (" + shipmentId + ") no known transport mode is given (choices are 'air', 'sea', 'road', 'inland water', 'rail', 'logisticsite'). The leg will not be further processed." |
Error | resultLegs_noFuelTypeButConsumption | "For the leg " + legId + " of the shipment (" + shipmentId + ") a consumption has been defined, but not a fuelType. The leg will not be further processed." |
Warning | resultLegs_noKnownFuelType | "For the leg " + legId + " of the shipment (" + shipmentId + ") no known fuel type has been selected. The default will be used. Choices are: "+Choices_FuelType_noConsumption if fuelType not in ["", None] and fuelType not in Choices_FuelType_noConsumption and not fuelConsumption else "For the leg " + legId + " of the shipment (" + shipmentId + ") no known fuel type has been selected. The default will be used. Choices are: "+Choices_FuelType_Consumption if fuelType not in Choices_FuelType_Consumption and fuelConsumption else |
Warning | resultLegs_wrongEquipmentRoad | "For the leg " + legId + " of the shipment (" + shipmentId + ") the equipment ("+equipment+") is not valid for transportMode (" + transportMode +"). Choices road: "+Choices_Road |
Warning | resultLegs_wrongEquipmentRail | "For the leg " + legId + " of the shipment (" + shipmentId + ") the equipment ("+equipment+") is not valid for transportMode (" + transportMode +"). Choices rail: "+Choices_Rail |
Warning | resultLegs_wrongEquipmentInlandWater | "For the leg " + legId + " of the shipment (" + shipmentId + ") the equipment ("+equipment+") is not valid for transportMode (" + transportMode +"). Choices inlandwaterways: "+Choices_InlandWaterways |
Warning | resultLegs_wrongEquipmentSea | "For the leg " + legId + " of the shipment (" + shipmentId + ") the equipment ("+equipment+") is not valid for transportMode (" + transportMode +"). Choices sea: "+Choices_Sea |
Warning | resultLegs_wrongEquipmentAir | "For the leg " + legId + " of the shipment (" + shipmentId + ") the equipment ("+equipment+") is not valid for transportMode (" + transportMode +"). Choices are: "+Choices_Air |
Warning | resultLegs_wrongEquipmentLogisticSite | "For the leg " + legId + " of the shipment (" + shipmentId + ") the equipment ("+equipment+") is not valid for transportMode (" + transportMode +"). Choices are: "+Choices_LogisticSites |
Warning | resultsLegs_noKnownFuelConsumptionUnit | "For the leg " + legId + " of the shipment (" + shipmentId + ") a unknown fuelConsumptionUnit has been given, while a fuelConsumption is given. The default unit will be used. Choices are: "+Choices_FuelConsumptionUnit |
Warning | resultLegs_noConsumptionButUnit | "For the leg " + legId + " of the shipment (" + shipmentId + ") a fuelConsumptionUnit has been given, while a fuelConsumption is not given. The unit will be ignored." |
Hint | resultLegs_noDirectConsumptionForRail | "For the leg " + legId + " of the shipment (" + shipmentId + ") a consumption has been defined, but the transport mode 'rail' is not supported for direct emission calculation. The default emission calculation will be used." |
Error | resultLegs_senderIdRecipientIdNoRegionFound | "For the leg "+ legId + " of the shipment (" + shipmentId + ") the sender country "+Sender_country+" and the recipient country "+Recipient_country+" could not be assigned to any region. Please check the country codes." |
Error | resultLegs_senderIdNoRegionFound | "For the leg "+ legId + " of the shipment (" + shipmentId + ") the sender country "+Sender_country+ " could not be assigned to any region. Please check the country code." |
Error | resultLegs_senderIdNoRegionFound | "For the leg "+legId+ " of the shipment (" + shipmentId + ") the recipient country "+Recipient_country+" could not be assigned to any region. Please check the country code." |
Error | resultLegs_senderGeocodingFailed | "For the leg "+legId+" of the shipment (" + shipmentId + ") the sender could not be geocoded. The leg will not be further processed." |
Error | resultLegs_recipientGeocodingFailed | "For the leg "+legId+" of the shipment (" + shipmentId + ") the recipient could not be geocoded. The leg will not be further processed." |
Error | resultLegs_senderRecipientGeocodingFailed | "For the leg "+legId+" of the shipment (" + shipmentId + ") the sender and recipient could not be geocoded. The leg will not be further processed." |
Error | resultLegs_noDistanceCalculated | "For leg "+legId+" of the shipment (" + shipmentId + ") no distance could be calculated." |
Error | resultLegs_co2eNotCalculated | "For leg "+legId+" of the shipment (" + shipmentId + ") the CO2e emission calculation has failed." |
Warning | resultLegs_riskIndexNotCalculated | "The risk index for the leg "+legId+" of the shipment (" + shipmentId + ") could not be calculated." |
Error | resultLegs_routingFailed | "No routing was possible because origin and destination location are within different sub-networks: [...]" "[...] Could not find transferpoints [...]" |
Error | resultLegs_costsNotCalculated | "Transport costs for the leg " + legId + " of the shipment (" + shipmentId + ") could not be calculated. Please check the input." |
Output Errors for Table "ResultLocations"¶
Type | Code | Message |
---|---|---|
Hint | resultLocations_locationNotUsed | "Location is not used in the shipments table. Therefore, it is not further processed." |
Error | resultLocations_geocodingNotPossible | "For the location " + id + " address information is missing or false. Legs containing this location will not be further processed." |
Warning | resultLocations_notUniqueId | "The location " + id + " appears more than once with different addresses in the data. Please correct. Different addresses should have different ids. In the further calculation a random address will be selected." |
Error | resultLocations_geocodingFailed | "The location "+id+" could not be geocoded." |
Error | resultLocations_regionNotFound | "For the location "+id+" the country "+country+" could not be assigned to any region. Please check the country code." |