Calculate transport emissions
Calculates greenhouse gas emissions for one or more transport operations. The endpoint supports the four core transport modes - AIR, RAIL, ROAD, and WATER - as well as a combination mode, WEIGHTED_MODES, which allows multiple underlying modes to be prorated into a single combined operation. Each transport operation in the request represents one leg of the cargo movement, and you may submit a single operation or a sequence of operations within the same request.
Authorizations
API key for authenticating requests. Include this header in all calls.
Body
Defines the transported goods for which emissions are calculated. Cargo parameters affect vehicle choice, load factors, and resulting emission estimates throughout the transport chain. Only the weight property is mandatory. Other properties will be defaulted if they are not provided. However, the more detail provided, the more accurate the results will be.
A unique identifier for the emissions calculation, such as a shipment ID. The ID is returned in the response. When options.storeResult is true, the calculation result is stored against this ID and can later be retrieved using GET /emissions/{id}.
Requests that provide an already stored ID will apply replace semantics where the new result replaces the previously stored result for that ID.
Used to customize emissions calculations and to control which details are included in the response.
Locations resolve either to a transport facility (airport, harbor, or rail yard) or to a general geographic area such as a building, street, postcode, or city. For larger areas, centroids are used to represent the approximate position.
Identification and geocoding
- Airports and harbors can be identified directly by code (
iataCodefor airports,unLoCodefor harbors). - Otherwise, the location is geocoded based on the available address components,
and if the
typeis notPLACE, the closest transport facility of the indicated type is selected.
Geocoding priority
When multiple data sources are provided, they are evaluated in the following order of preference:
- Geographic coordinates (latitude and longitude)
- IATA code (for non-airport locations)
- Structured address components
- UN/LOCODE (for non-harbor locations)
- Unstructured address text
Geocoding accuracy depends on the quality and completeness of the input. Structured addresses almost always yield better results and are tolerant of minor data-entry errors, such as postcodes appearing in street fields. For both structured and unstructured inputs, the most probable match is selected based on lexicographical similarity to known locations.
Operational behavior
When a transport facility is specified directly, it will be used regardless of any transport vehicle specified. The system does not enforce suitability constraints. For example, a large aircraft such as a Boeing 747-8F may be routed to Gibraltar International (LXGB) despite its short runways. If the airport were not explicitly chosen, the system would instead select a nearby suitable airport such as Málaga-Costa del Sol (AGP).
Similarly, a container vessel may be routed to Plymouth (GBPLY) even though the port lacks container handling facilities. If the port were not specified explicitly, a capable alternative such as Southampton (GBSOU) would be selected automatically.
- Coordinates
- IATA code
- UN/LOCODE
- Unstructured address
- Structured address
- Street & city
- Street & postcode
- Postcode
- City
Locations resolve either to a transport facility (airport, harbor, or rail yard) or to a general geographic area such as a building, street, postcode, or city. For larger areas, centroids are used to represent the approximate position.
Identification and geocoding
- Airports and harbors can be identified directly by code (
iataCodefor airports,unLoCodefor harbors). - Otherwise, the location is geocoded based on the available address components,
and if the
typeis notPLACE, the closest transport facility of the indicated type is selected.
Geocoding priority
When multiple data sources are provided, they are evaluated in the following order of preference:
- Geographic coordinates (latitude and longitude)
- IATA code (for non-airport locations)
- Structured address components
- UN/LOCODE (for non-harbor locations)
- Unstructured address text
Geocoding accuracy depends on the quality and completeness of the input. Structured addresses almost always yield better results and are tolerant of minor data-entry errors, such as postcodes appearing in street fields. For both structured and unstructured inputs, the most probable match is selected based on lexicographical similarity to known locations.
Operational behavior
When a transport facility is specified directly, it will be used regardless of any transport vehicle specified. The system does not enforce suitability constraints. For example, a large aircraft such as a Boeing 747-8F may be routed to Gibraltar International (LXGB) despite its short runways. If the airport were not explicitly chosen, the system would instead select a nearby suitable airport such as Málaga-Costa del Sol (AGP).
Similarly, a container vessel may be routed to Plymouth (GBPLY) even though the port lacks container handling facilities. If the port were not specified explicitly, a capable alternative such as Southampton (GBSOU) would be selected automatically.
- Coordinates
- IATA code
- UN/LOCODE
- Unstructured address
- Structured address
- Street & city
- Street & postcode
- Postcode
- City
Represents the sequence of transport and hub operations that define a complete multimodal logistics chain.
Structure
The transportChain is an ordered array of elements describing how cargo moves between points.
- Each transport element represents a specific operation and has a
typevalue ofAIR,RAIL,ROAD,WATER, orWEIGHTED_MODES. - Each hub element has a
typeofHUBand represents the connecting location between consecutive transport segments.
Behavior
- If this array is not provided or is empty, fallback transport modes are attempted instead. The system will cycle through the fallback modes in order, applying default parameters for each until one succeeds or all fail.
- Hubs must appear between each pair of transport operations to define the connecting locations between them.
- Hubs may also appear as the first and/or last elements in the array. This allows a logistics hub to act as the origin or destination
in place of the top-level
originanddestinationproperties, enabling emissions to be attributed to those locations.
- Unknown transport
- Air transport
- Rail transport
- Road transport
- Water transport
- Weighted modes transport
- Hub operation
Additional information related to the emissions calculation. The object may contain any properties. The following recognized properties, when provided, will be displayed as sections in the emissions certificate generated for the calculation:
- reportingParty
- reportingTo
- consignor
- consignee
- transportProvider
- transaction
- cargo
Any additional custom properties included within these recognized objects will also be displayed in the corresponding section of the emissions certificate.
Response
Emissions calculation successfully performed
The origin location for the transport chain.
The destination location for the transport chain.
The total distance in kilometers across all transport operations in the request.
The total transport activity for all transport operations in the request. Measured in tonne kilometers.
The combined emission intensity rates across all the transport operations.
The total emissions for all the transport operations.
The combined emission intensity rates across all the logistics hubs.
The total emissions for all the logistics hubs.
The combined emission intensity rates across the entire transport chain.
The total emissions for the entire transport chain.
Array of emissions calculation results for the transport operations defined in the request’s transport chain, along with any automatically inserted logistics hub operation results. The results appear in the same order as in the request, with any inserted hub operations results placed where they occurred in the transport chain.
- Transport chain result
- Hub operation result
Number of credits consumed to generate the emissions calculation results, deducted from the user’s account as part of processing the request.
Returns the unique identifier supplied for the emissions calculation request. This is the same value provided in the request's id field.
The top-level context object supplied in the request's context. Any properties provided by the caller are preserved and returned in this object.
URL for the PDF certificate associated with the emissions calculation. This field is included when the calculation result is stored by setting options.storeResult to true and providing an id.