This endpoint returns CO2e emissions (i.e CO2 equivalent emissions) in grams (g) for a voyage from a city to another by road.
Origin and destination
The source and destination can be given either by locode or coordinates.
You must provide either fromLocode or fromCoordinates and either toLocode or toCoordinates.
The emissions are calculated using the real road network distance and based on the region but you can use the parameter distance (in meters) to pass your own distance (the origin and destination remain mandatory because the co2 computation is region dependent).
Supported regions are Europe, North America, Ocenia South America, Africa and Asia. Note that the origin and the destination should be in the same region.
Cargo specifications
Container specifications (nContainers, nContainers), weight and loadCharacteristics define the cargo specifications.
The following container types are supported by our API :
20GP or 22G1 (20ft, General purpose (Standard)) [Default]
40GP or 42G1 (40ft, General purpose (Standard)),
40HC or 45G1 (40ft High cube, General Purpose),
22R1 (20ft, Reefer),
40NOR or 42R1 (40ft, Reefer),
40REHC or 45R1 (40ft High cube, Reefer)
Here are some use cases :
FCL
use the parameters nContainers and containerSizeTypeCode. If a weight is passed, it will be ignored and an estimate weight will be taken into account for CO2e calculation.
The type of cargo in that case is set to CONTAINER.
You can pass a truckSize and a fuelType. Not all combinations are usable : in order to limit the errors and return co2e emissions in most cases, we adapt truckSize and fuel parameters passed.
The parameters actually used are listed in the properties object of the response.
LCL
use the parameters weight and set the loadCharacteristics (type of cargo) parameter to CONTAINER. An appropriate truckSize will be chosen for you (except you pass one). You can pass an appropriate containerSizeTypeCode. (For reefer, you can choose 22R1)
You can pass a truckSize and a fuelType. Not all combinations are usable : in order to limit the errors and return co2e emissions in most cases, we adapt truckSize and fuel parameters passed.
The parameters actually used are listed in the properties object of the response.
Default
If no weight is specified and no loadCharacteristics is set, the API returns the amount of CO2e for 1 metric ton of goods in the worst scenario (smallest truck) (loadCharacteristics = AVERAGE_MIXED or DEFAULT )
If the weight is specified, you must also provide the size of the truck (gross vehicle weight in tons) except for North America and Oceania where the truck size is not taken into account.
Truck specifications
The fuel type (among diesel, cng, lng or petrol for vans (<3.5t)) can be given for more accurate CO2e values. Note that the diesel type is 5% biodiesel and only diesel is available for North America.
For Europe, South America, Africa and Asia regions, you can pass a truck size (gross vehicle weight - GVW) for more accurate results.
Carrier specifications (North America)
We can compute CO2e for a given truck carrier (identified by its SCAC). This is only available in North America (from/to should be in this region) and the computation uses SmartWay carrier data (Dray (CONTAINER) and Mix (AVERAGE_MIXED)).
You can use the parameter carrierScac (which is a carrier alpha code identifier) to select the carrier.
Note that in that case we only support DIESEL and the truck size cannot be changed. If the SCAC passed is not valid or we don't have enough data to compute CO2e, the computation will be based on GLEC defaults. In that case, the carrierScac property in the field properties of the response is set to null.
Response
The response contains WTW (well-to-wheels) CO2e emissions in g for the amount of goods carried and detailed emissions : WTT (well-to-tank) and TTW (tank-to-wheels). It also contains the intensity factor (kg of CO2e per ton.kilometer) which is calculated from the WTW CO2e emissions, the distance and the weight (in properties).
The field parameters contains the parameters that were passed in the query and the default values that were used. Depending on the combination of parameters you enter, the default values for other parameters may vary. For example, the default truckSize for average mixed goods is 3t while it is 33t for container.
The field properties contains information about the data that was used for the calculation, for example the distance, some characteristics about the truck, the hypothesis made for load factor, etc. The property dataType precise if the data used to calculate the CO2 emissions is default data (representarive of average operating practices) or modeled data (taking into account vehicle information).
Methodology references
The emissions are calculated using the GLEC framework or SmartWay Carrier data.
You can find detailed information about the calculation and the hypothesis in our Guide section.