API Reference
Intermodal Freight

Intermodal Freight ADD-ONADD-ON

Climatiq allows you to use emission factors from the Global Logistics Emissions Council(GLEC) (opens in a new tab) to calculate the carbon emissions for shipping freight around the world using multiple modes of transport such as by sea, air, road or rail.

Estimate

POST Calculate total estimated emissions produced by shipping an amount of cargo by the specified route. This endpoint still has a few limitations. More information here.

It is also recommended that you check out the guide, which provides an introduction to using the endpoint and details some of the flexibility it offers.

https://beta4.api.climatiq.io/freight/intermodal

Request

The following parameters can be defined as JSON-encoded object in the body.

Required
cargo Unit type Weight
The weight of the cargo being shipped
required
route [Route Leg or Location]
An array of route parts that compose the route this cargo is taking. A route must start and end with a location, and have legs between each location. Sometimes you may omit some locations and rely on automatic routing.
required
curl --request POST \
--url https://beta4.api.climatiq.io/freight/intermodal \
--header 'Authorization: Bearer API_KEY' \
--data '{
"route": [
{ "location": { "query": "Hamburg" } },
{
"transport_mode": "road",
"leg_details": {
"vehicle_type": "van",
"vehicle_weight": "lte_3.5t"
}
},
{ "location": { "query": "Berlin" } }
],
"cargo": {
"weight": 10,
"weight_unit": "t"
}
}'

Response

A response consists of the following attributes.

Response attributes
co2e number
The carbon dioxide equivalent emitted for the entire trip.
co2e_unit string
The unit in which the CO2e field is expressed. Is always kg
distance_km number
The distance in kilometers that the cargo has been shipped along the specified route.
route [ResponseLocation or ResponseLeg]
An array that specifies the route the cargo took. This array will always consist of alternating response locations and response legs. It will always start and end with a location. Even if you have omitted any locations, they will not be omitted in the response.
notices [Notice]
An array of notices that is relevant for understanding the result. This could be if Climatiq cannot accurately calculate the distance for a certain route, but still performed a less-accurate calculation.
{
"co2e": 1946.8196000000003,
"co2e_unit": "kg",
"distance_km": 286.297,
"route": [
{
"type": "location",
"name": "Hamburg, Germany",
"latitude": 53.55562,
"longitude": 9.98745,
"confidence_score": 1
},
{
"type": "leg",
"co2e": 1946.8196000000003,
"co2e_unit": "kg",
"transport_mode": "road",
"distance_km": 286.297,
"estimates": [
{
"co2e": 1946.8196000000003,
"co2e_unit": "kg",
"co2e_calculation_method": "ar4",
"co2e_calculation_origin": "source",
"emission_factor": {
"name": "Van =< 3.5 t",
"activity_id": "freight_vehicle-vehicle_type_van-fuel_source_na-vehicle_weight_lte_3.5t-distance_uplift_included",
"id": "221b2e08-6bf6-4c21-8357-4ca3bfa135ca",
"access_type": "public",
"source": "GLEC",
"source_dataset": "Default Fuel Efficiency and CO2e Intensity Factors",
"year": 2019,
"region": "EU_S_AMERICA",
"category": "Road Freight",
"source_lca_activity": "well_to_wheel",
"data_quality_flags": []
},
"constituent_gases": {
"co2e_total": 1946.8196000000003,
"co2e_other": null,
"co2": null,
"ch4": null,
"n2o": null
},
"activity_data": {
"activity_value": 2862.9700000000003,
"activity_unit": "tonne-km"
},
"audit_trail": "enabled"
}
]
},
{
"type": "location",
"name": "Berlin, Germany",
"latitude": 52.51604,
"longitude": 13.37691,
"confidence_score": 1
}
],
"notices": []
}

Route Leg

Each route in the request has one or more legs. A leg is a transition between two locations. A leg contains the following properties.

Request leg attributesRequired
tranport_mode string
How the goods are transported. Allowed values are air, sea, road, rail
required
leg_details object
The details of the leg such as fuel and vessel type. Valid values here vary between transport_mode. Allowed values are RoadDetails, SeaDetails, AirDetails or RailDetails.
optional
distance_km number
If you have an actual distance for this leg in kilometers you can input the distance here. Climatiq will then use this distance instead of the planned distance it would normally calculate.
optional

Road

A leg with the "transport_mode": "road", can specify further details about the journey by including this object under leg_details.

Different vehicle_types have different requirements and options. As an example, for some vehicle types, the parameter fuel_source might be optional, and for some it might not be.

AttributesRequiredDefault
vehicle_type string
The type of vehicle that is used for the transportation. The values have a few abbreviations such as hgv meaning heavy goods vehicle (opens in a new tab) and mgv meaning medium goods vehicle (opens in a new tab). articulated and rigid refers to truck types (opens in a new tab). refrigerated refers to whether or not the cargo is refrigerated.
All valid values are:
auto_carrier, dray, expedited, flatbed, general, heavy_bulk, hgv_articulated, hgv_articulated_hpdi, hgv_articulated_hpdi_refrigerated, hgv_articulated_refrigerated, hgv_articulated_si_engine, hgv_articulated_si_engine_refrigerated, hgv_rigid, hgv_rigid_refrigerated, mgv_refrigerated, hgv_refrigerated, ltl_or_dry_van, mixed, moving, package, refrigerated, specialized, tanker, tl_or_dry_van, van, van_refrigerated, hgv, mgv, urban_truck, urban_truck_refrigerated
requiredNorth America: general,
Rest of World: hgv
vehicle_weight string
The carrying capacity of the vehicle, as a string specifying the range. E.g. gt_60t_lt_72t means a carrying capacity greater than 60tons and less than 72tons. Valid values vary depending on the vehicle type, but all valid values are:
gt_20t, gt_34t_lt_40t, gt_40t_lt_44t, gt_44t_lt_60t, gt_60t_lt_72t, lt_34t, lt_40t, gt_12t_lt_20t, gt_20t_lt_26t, gt_3.5t_lt_7.5t, gt_7.5t_lt_12t, gt_26t_lt_32t, gt_7.5t_lt_20t, lte_3.5t, lt_3.5t
optionalNorth America: NA,
Rest of World: gt_20t
fuel_source string
The fuel source that the vehicle is running on. Valid values vary depending on the vehicle type, but all valid values are:
diesel_5_percent_biodiesel_blend, bio_lng_or_diesel, cng_or_diesel, lng_or_diesel, bio_lng, cng, lng, lpg, petrol
optionalAverage
load_type string
The type of load the vehicle carries. Valid values vary depending on the vehicle type, but all valid values are:
heavy, container, light
optionalAverage

Sea

A leg with the "transport_mode": "sea", can specify further details about the journey by including this object under leg_details.

AttributesRequiredDefault
vessel_type string
The type of vessel that is used for the transportation. All valid values are:
container, container_reefer_refrigerated, bulk_carrier, bulk_carrier_ignition_ship, bulk_carrier_medium_speed_ship, bulk_carrier_slow_speed_ship, general_cargo, oil_tanker, oil_tanker_ignition_ship, oil_tanker_medium_speed_ship, oil_tanker_slow_speed_ship, ro_pax, ro_ro
requiredcontainer
tonnage string
The tonnage the ship can carry, as a string specifying the range E.g. gt_10dwkt_lt_20dwkt means more than 10 deadweight kilotons (opens in a new tab), and less than 20 deadweight kilotons. This cannot be set for vessel types container and container_reefer_refrigerated. For other vessel types the valid values vary depending on the vessel type, but all valid values are:
gt_100dwkt, gt_10dwkt_lt_100dwkt, lt_10dwkt, gt_10dwkt_lt_20dwkt, gt_200dwkt, gt_5dwkt_lt_60dwkt, gt_60dwkt_lt_200dwkt, lt_5dwkt
optionalNA
fuel_source string
The type of fuel that the ship uses. Cannot be set for vessel types container and container_reefer_refrigerated. For other vessel types the valid values vary depending on the vessel type, but all valid values are:
hfo, mgo, lng
optionalNA
load_type string
The type of load that the ship is carrying. Cannot be set for vessel types container and container_reefer_refrigerated. For other vessel types the valid values vary depending on the vessel type, but all valid values are:
heavy, trailer_only, truck_plus_trailer
optionalNA

Air

A leg with the "transport_mode": "air", can specify further details about the journey by including this object under leg_details.

AttributesRequiredDefault
aircraft_type string
The aircraft type used to carry the shipment. Use freighter if it is a dedicated cargo plane, or belly_freight if it is transported in the belly of a passenger plane.
optionalaverage
methodology string
The methodology used to calculate the emissions. Valid values are en16258 or iata_rp1678. Climatiq defaults to en16258 as we consider that the most valid of the two methods.
optionalen16258
radiative_forcing_index number
The radiative forcing index to multiply the emissions by (see info box below). If you do not want a radiative forcing index to be applied, you may specify 1
optional2
Air travel and radiative forcing

GLEC default emission factors do not include a Radiative Forcing Index (RFI) (opens in a new tab). RFIs are applied to account for the increased impact on global heating made by greenhouse gases released directly into the upper atmosphere by aircraft. RFI values depend on things like altitude and trip length and are subject to uncertainty and disagreements. To perform the most accurate calculations, this endpoint currently applies an RFI of 2 to all flights, based on the latest available science (opens in a new tab). If a Radiative Forcing Index has been applied, a notice will be returned.

Rail

A leg with the "transport_mode": "rail"; you can specify further details about the journey by including this object under leg_details.

Rail Details AttributesRequiredDefault
fuel_type string
The fuel type that the train runs on. Valid values are
diesel, electricity; do not include if hybrid or unknown (an averaged factor will be applied)
optionalregional average or default
load_type string
The load that the train is carrying. Valid values are
building_materials, cars, cereals, chemicals, coal_steel, container, manufactured_products, trailer_only_on_train, truck_plus_trailer_on_train
optionalaverage
Rail freight outside of Europe

We have not yet implemented network distance calculations for rail outside of Europe; in the interim we fallback to using the great circle distance between the points.

The GLEC emission factors have a good coverage of Europe, with diesel and electric options and different load types represented. US has more basic factors , while for the rest of the world, in absence of applicable factors, under GLEC guidance we fall back to using a factor reflecting the European average.

Notices should be present in your response if your query has hit any of these limitations.

Location

A trip always has two or more locations.

Request Location AttributesRequired
location Location
Either a QueryLocation, an IataCodeLocation, an UNLocodeLocation or a CoordinateLocation
required
location_options Location Options
Extra options that a location can have. See section below.
optional

Query Location

Query Location AttributesRequired
query string
A free text query describing the location, such as "Berlin, Germany", or "10 Downing Street".
optional
country string
The two or three letter ISO-3166 country code (opens in a new tab) for a given location. If you want to find locations in China you must specify the correct country code.
optional
postal_code string
The postal (or zip) code for the given location. If used, country or query must also be specified.
optional

All the properties are optional, but you must specify at least a query or a country + postal_code. You may specify all three. Note that not all countries have support for postal codes, and the format might be different from country to country. See this table (opens in a new tab) for details on postal codes.

IATA Code Location

IataLocation AttributesRequired
iata string
An IATA airport code.
required

UN/LOCODE Location

UNLocode Location AttributesRequired
locode string
An UN/LOCODE (opens in a new tab) of the format DE-BER for Berlin. The Locode must contain both country and location.
required

Coordinate Location

Coordinate Location AttributesRequired
longitude number
The longitude of the coordinate.
required
latitude number
The latitude of the coordinate.
required
country_code number
The 2-letter country code for the country that this coordinate is located within.
required

Location Options

There are other options that are sometimes relevant to change, particularly if the location is travelled to or from is a fixed-transition point leg

Location Options AttributesRequiredDefault
tolerance_km number
If a location is adjacent to a fixed-transition point leg, Climatiq automatically makes small corrections to turn your provided location into the proper port, airport or railway station. If you want to increase this distance, you may change this parameter, to the maximum distance in km you want corrections to be made for. See Automatic Location Correction for more details.
optional10

Response Models

These are more in-depth explanations of the models returned by the intermodal freight endpoint.

ResponseLocation

The location in the route array of the response will contain the following properties

Response Location attributes
name string
A human-readable name of the location
latitude string or null
The latitude of the location. This is only returned if you have access to view coordinates. Please contact us if you need this enabled.
longitude string or null
The longitude of the location. This is only returned if you have access to view coordinates. Please contact us if you need this enabled.
confidence_score number
A confidence score between 0 and 1, determining how certain we are that the location matches your query. Only exists if the input location was a QueryLocation

ResponseLeg

The leg in the route array of the response will contain the following properties

Response Leg attributes
co2e number
The carbon dioxide equivalent emitted for this leg of the trip.
co2e_unit string
The unit in which the co2e field is expressed. Is always kg
transport_mode string
What transport mode this leg corresponds to. Will be "road", "air", "sea" or "rail"
distance_km number
The distance in kilometers for this leg of the trip.
estimates [Estimation]
An array of estimations performed to achieve the final co2e value for this leg. Depending on the LCA attributes of the relevant emission factors, this will generally be 1-2 emission factors. Climatiq will always prioritize giving you two emission factors for well_to_tank and tank_to_wheel if possible. For road routes where the truck takes a ferry, this might be more.

Notice

The notices array can contain objects like these:

Notice attributes
severity string
Either critical or info. critical is for messages that might lead to inaccurate calculations. You should check these to make sure the results are fit for your intended purpose. info is for information that will help you understand the calculation result better.
message string
An explanation of the notice.