iLEAP Technical Specifications (Version 0.2.1-20240716)

Living Document, 16 July 2024

This version:
https://sine-fdn.github.io/ileap-extension/
Latest published version:
https://sine-fdn.github.io/ileap-extension/TR/2024/ileap-extension-20240605/
Previous Versions:
Feedback:
GitHub
Inline In Spec
Editors:
Violetta Matzoros
Gabriela Rubio Domingo
Martin Pompéry
Raimundo Henriques

Abstract

This document outlines the semantics for logistics emissions data exchange as part of the SFC iLEAP Project. Its format is based on the Pathfinder Technical Specifications and supports the integration of Logistics Emissions Data Exchange into the Pathfinder Network. Implementing this specification enables stakeholders within the supply chain to exchange data on logistics emissions. This facilitates the tracking of logistics emissions and the computation of their contribution to product carbon footprints.

1. Introduction

The iLEAP Technical Specifications will be continuously refined as part of the ongoing iLEAP project. Significant changes may be introduced as the project progresses.

1.1. Out of Scope

This specifcation does not cover the following topics or aspects as they are covered elsewhere or declared as out of scope of this specification:

  1. Methodology for the calculation of logistics-related emissions which is specified in the [GLEC] Framework and [ISO14083].

  2. Black Carbon (Accounting).

  3. How to exactly capture necessary primary activity data for the calculation of HOCs or TOCs (i.e. through telematics systems, TMS, or others).

  4. Pilot decentralized data exchange following data space governance principles, as covered in the SFC Data Exchange Network project.

  5. How to establish contractual obligations between parties for the provision of data.

  6. How to perform data audits and verification.

  7. Market based approach for electricity emissions accounting.

  8. Book and claim methods to track the environmental attributes of low emission transport solutions separately from the physical delivery. This will be incorporated in later versions of these technical specifications.

  9. Variables for detailed GHG emissions modelling, as described in [ISO14083], Section 13.4.3 and Annex M. The current data model is considered a key enabler for primary data collection, where its main focus lays. The basic use of modelled and default data is supported, but detailed parameters for modelling are excluded from the current version.

  10. Modes of transport cable car and pipelines. These could be considered for future versions of these technical specifications.

  11. Refrigerant emissions, due to leakage of refrigerants used by vehicles and hubs, as described in [ISO14083], Annex I. This will be incorporated in later versions of these technical specifications.

1.2. Document Statuses

The iLEAP Technical Specifications adhere to the SemVer standard and are published according to a flow that clearly distinguishes work-in-progress from pre-releases and stable releases. These are indicated by the status tag below at the top of the document. Possible status tags are:

Living Document

Work-in-progress. The version number is typically extended with the date on which the most recent changes were made (e.g., 0.2.1-20240523). Accessible at https://sine-fdn.github.io/ileap-extension/.

Consultation Draft

Pre-release. Distributed for the purpose of obtaining community feedback. No further significant changes will be made until the release. Minor corrections may still be possible. Every Consultation Draft is assigned a stable, permanent, URL, e.g., https://sine-fdn.github.io/ileap-extension/TR/2024/ileap-extension-20240521/.

Release

Stable release. No further changes will be made to this version. Any additional changes will be included in subsequent versions. Every Release is assigned a stable, permanent, URL, e.g., https://sine-fdn.github.io/ileap-extension/TR/2024/ileap-extension-20240605/.

2. Definitions

2.1. ISO14083- and GLEC-Framework-related Definitions

Actual Distance

The actual route (with unit kilometer) taken for a consignment. [GLEC] Framework. See also [ISO14083] Section 3.1.27.1.

Consignment

A consignment refers to a quantifiable quantity of cargo that can be distinctly identified as a single unit. It is transported from a sender or consignor to a receiver or consignee, irrespective of the mode of transportation employed. See [ISO14083], Section 3.1.4.

Distance

See Transport Distance and Actual Distance

Great Circle Distance (GCD)

It is the shortest distance between two points by crow-line, including the curving of the earth. It is an approach used in air transport. [GLEC] Framework.

Hub Activity

The operations carried out at a hub, measured in the hub’s throughput. [GLEC] Framework.

Hub Operation Category (HOC )

A Hub Operation Category is a grouping of hub operations sharing similar characteristics. [GLEC] Framework.

Primary Data

Data based on direct measurements of energy consumption. Also see [GLEC] Framework.

Secondary Data

Any data that is not primary data. It applies to modelled and default data. [GLEC] Framework.

Shipment

A shipment refers to the goods in a commercial transaction between a seller and a buyer. It encompasses the consignments transported as part of this transaction via a transport chain from the consignor to the consignee. See [ISO14083], Section 3.1.20.

Shortest Feasible Distance (SFD)

It represents the shortest practical route between two places taking into account the real operating conditions. [GLEC] Framework.

Transport Activity

Transport activity for each consignment is calculated by multiplying the consignment’s mass by the TCE distance. It is measured with unit ton kilometer. See [ISO14083] Section 3.1.24 and the [GLEC] Framework.

Transport Chain (TC )

A Transport Chain as defined in the [GLEC] Framework. A TC consists of 1 or more Transport Chain Elements. A TC corresponds to a shipment.

Transport Chain Element (TCE)

A Transport Chain Element is one element of the transport chain. It can consist of a transport activity or a hub activity. [GLEC] Framework.

Transport Distance

Refers to the distance covered from the consignor to the consignee during the transportation of the freight. [GLEC] Framework. See also [ISO14083] 3.1.27.

Transport Operation Category (TOC )

A Transport Operation Category is a grouping of transport services sharing similar characteristics. [GLEC] Framework.

Transport Operator

Refers to the party that carries out the transport service. See [ISO14083], Section 3.1.30.

Transport Service Organizer

Refers to the party providing transport services, where some of the operations are subcontrated to a third party, usually a Transport Operator. See [ISO14083], Section 3.1.32.

Transport Service User

Refers to the party that purchases and or utilizes a transport service. It could be a shipper or a Transport Service Organizer. See [ISO14083], Section 3.1.33.

2.2. Auxillary Definitions

Access Token

See Pathfinder Tech Specs for the definition.

Consignment id

A digital identifier which uniquely identifies a Consignment.

Data Owner

See Pathfinder Tech Specs for the definition.

Data Recipient

See Pathfinder Tech Specs for the definition.

Data Transaction

see § 4 Data Transactions

Host System

See Pathfinder Tech Specs for the definition. Here, a host system additionally implements support for 1 or more data transactions (§ 4 Data Transactions).

Hub Operator

A party that is offering hub services, including warehousing and transshipment center services.

PCF

Product Carbon Footprint. See Pathfinder Tech Specs for further details

ShipmentFootprint

See § 6.1 ShipmentFootprint for the definition.

Shipment id

A digital identifier which uniquely identifies a Shipment.

Shipper

An entity which sends goods for transport; e.g. buying transport services from Transport Service Organizers or Transport Operators. See [GLEC] Framework.

Smart Freight Centre (SFC )

The Smart Freight Centre Organization.

Tool Provider

Provider of software, tools, services, or programs that support companies in calculating and reporting logistics GHG emissions conforming to these technical specifications.

3. Business Cases

Note: Non-normative section

This specification shall serve the general need of businesses for logistics GHG emissions accounting and reporting, conforming with the [GLEC] Framework and [ISO14083].

Given the nature of the logistics industry, and in order to reduce costs overall, this specification aims at enabling interoperability in the exchange of emissions data between different parties in the logistics value chain.

To achieve this objective, the specification is guided by a set of business cases which provide the framework for delineating subsequent data transactions and the iLEAP data model.

3.1. Quantification of (Avoided) Emissions

A Transport Service User requests its Transport Service Organizers or Transport Operators to provide it with the GHG emissions of Shipments. The transport service user is particularly interested in having access to accurate emission and emission intensity values based on the measurement of actual data ("primary data").

Accurate logistics emissions values also enable the Transport Service User to compare logistics emissions and the resulting reductions from operational measures.

Data Transactions #1 (§ 4.1 Data Transaction 1: TCE Data Exchange) and #2 (§ 4.2 Data Transaction 2: TOC Data Exchange) enable this business case.

3.2. Procurement of Carbon-Efficient Logistics Services

A Transport Service Organizer requests their Transport Operators to share GHG emission intensity information at the TOC or HOC level. Similarly, a Transport Service User requests intensity information from their Transport Service Organizers and Transport Operators.

By incorporating emission intensities in procurement processes, the parties are enabled to select services by carbon-efficiency advantages.

Data Transaction #2 § 4.2 Data Transaction 2: TOC Data Exchange enable this business case.

3.3. Simplified Emissions Calculation from Transport Activity Data

A Transport Operator, and possibly also Transport Service Organizer, is not yet able to calculate GHG emissions according to the GLEC Framework and [ISO14083].

In such a case, the Party may choose to collect Transport Activity Data, that is information related to a single shipment including mass or energy carriers used.

After collecting Transport Activity Data, the Party can then contract a third party, such as a Tool Provider, to calculate TOC and HOC level data from its Transport Activity Data.

This business case is particularly relevant for SMEs to reduce the barrier to entry for logistics emissions reporting.

The way this business case is realized through iLEAP, generally simplifies data collection efforts for the parties involved. For instance, each party needs to collect the activity data only once. Afterwards, the Party can make the activity data available to multiple parties (see § 4.3 Data Transaction 3: Transport Activity Data Exchange) or for different purposes, including business cases beyond emissions calculations.

Data Transaction #3 (§ 4.3 Data Transaction 3: Transport Activity Data Exchange) enables this business case.

3.4. Potential additional Business Cases

Disclosure of Logistics Emissions as part of PCFs

A Transport Service User is requested to disclose logistics emissions as part of a PCF. A Transport Service User can disclose this data as a data model extension (see § 7.2.1 ShipmentFootprint)

This is enabled through the usage of the Pathfinder Technical Specification and disclosing through so-called Data Model Extensions based on the iLEAP Data Model (§ 6 Data Model) . See the Pathfinder [DATA-MODEL-EXTENSIONS] specification.

Forecasting

A Transport Service User requests their service provider (Transport Service Organizer or Transport Operator) to share GHG emissions at the TOC or HOC level. This enables the Transport Service User to forecast emissions related to specific activities or services, before these take place.

Integration of Book & Claim

A Transport Service Organizer requests their service provider (Transport Operator) to share with them emissions attributes according to a book & claim scheme.

Note: This business case is currently out of scope. It might be supported in the future, as book & claim methodologies and related variables are considered in scope of these technical specifications.

4. Data Transactions

A data transaction is an abstraction for the exchange of data between two parties, serving one or more business cases (§ 3 Business Cases).

Its function is to facilitate interoperability between different parties by explaining the context and their intention(s).

Each transaction combines the iLEAP data model (§ 6 Data Model) with the Pathfinder Data Exchange Protocol (§ 7.2 Pathfinder Integration) to enable interoperability between host systems.

The following diagram shows how the three data transactions (defined below) are related:

Transactions diagram

Note: A Tool Provider can assume various roles on behalf of the Transport Service User, Transport Service Organizer or Transport Operator, as outlined in the data transactions below. They can serve as mediators in activities involving data collection, calculation, and reporting.

4.1. Data Transaction 1: TCE Data Exchange

This data transaction enables a Transport Service User (for example, a shipper) to receive Transport Chain Elements emissions related data (encoded as TCEs) from a Transport Operator or a Transport Service Organizer for a single shipment.

For this, the Transport Operator or the Transport Service Organizer MUST

  1. first calculate 1 or more TCEs emissions related data in accordance with the [GLEC] Framework and [ISO14083], and then

  2. make the resulting ShipmentFootprint available to the Transport Service User through the Pathfinder Network API (see § 7.2.1 ShipmentFootprint).

The Transport Service User CAN then derive the Transport Chain (TC) using the shipment id, by

  1. collecting the TCEs from all the Transport Operators and the Transport Service Organizers related to the shipment

  2. forming the TC from the collected TCEs

  3. calculating the logistics emissions of the shipment in accordance with the [GLEC] Framework and [ISO14083].

Note: For an example exchange, see § 5 End-to-End Example

4.2. Data Transaction 2: TOC Data Exchange

This data transaction enables a Transport Service Organizer to receive TOC emission intensity related data from a Transport Operator.

The provision of emission intensity data at the TOC level would enable the Transport Service Organizer to collect the necessary information to calculate emissions according to the GLEC Framework and [ISO14083]. It could also facilitate the inclusion of emission intensity in procurement processes, allowing for the provision of services that offer carbon-efficiency advantages (see Business Case 2).

For this, the Transport Operator or Transport Service Organizer MUST

  1. first calculate 1 or more TOCs in accordance with the [GLEC] Framework and [ISO14083], and then

  2. make the resulting TOCs available through the Pathfinder Network API (see § 7.2 Pathfinder Integration).

Note: The details on how to define and to calculate TOCs and HOCs are specified in [ISO14083] and guidance provided through the [GLEC] Framework. Details of the calculation method are out of scope of this specification.

4.3. Data Transaction 3: Transport Activity Data Exchange

This data transaction enables a Transport Service Organizer or a Transport Service User to receive Transport Activity Data from a Transport Operator.

For this, the Transport Operator MUST

  1. first collect Transport Activity Data belonging to a consignment identified by the consignment id

  2. calculate the TAD (see § 6.5 Transport Activity Data (TAD)) given the consignment id

  3. make the resulting TAD available through the Pathfinder Network API.

The Transport Service Organizer or Transport Service User CAN then retrieve the TADs using the consignment ids.

Note: This data transaction is considered necessary by logistics parties. Especially for SMEs, lacking the capabilities to report curated emissions data, the option to provide activity data to their customers should be given.

5. End-to-End Example

Note: Non-normative section

This section provides an end-to-end example of how the data transactions (§ 4 Data Transactions) enable logistics emissions transparency for a single shipment.

The following hypothetical parties are involved:

Transport Service User S

A Transport Service User which wants to calculate the logistics emissions of a shipment from Rotterdam to Prague. The shipper has a contract with the Transport Service Organizer Z.

S operates a host system which implements Transaction 1 (§ 4.1 Data Transaction 1: TCE Data Exchange) to collect TCEs. Based on the collected TCEs, S can calculate Transport Chains (TCs) and thereby calculate and gain logistics emissions transparency.

Transport Service Organizer Z

A Transport Service Organizer responsible for a shipment from Rotterdam to Prague.

The Transport Service Organizer contracts Transport Operator A and Transport Operator B to perform the transport.

This operator has a host system which implements Transaction 1 (§ 4.1 Data Transaction 1: TCE Data Exchange) as well as Transaction 2 (§ 4.2 Data Transaction 2: TOC Data Exchange).

Through this, the operator is able to eventually calculate TCEs and TOCs, so that they can provide data to Transport Service User S.

Transport Operator A

A Transport Operator which is responsible for the first leg of the shipment.

This Operator has a host system which is capable of calculating TCEs and TOCs data.

Through this, the operator can make Transport Chain Element-level data available to the Transport Service Organizer Z, which Z can fetch using Transaction 1 (§ 4.1 Data Transaction 1: TCE Data Exchange).

Transport Operator B

Another Transport Operator which is responsible for the second leg of the shipment.

This Transport Operator is capable of making TAD data avialable to the Transport Service Organizer Z.

5.1. Data Transactions Executed

Note: In this hypothetical example, hub operations are currently ommitted.

Note: In this hypothetical example, when we refer to a party executing a transaction, we implicitly refer to their host systems which execute the tasks and transactions on their behalf.

5.1.1. Data Collection by Transport Service Organizer Z

As the transport consists of 2 legs, Z needs to collect data from the 2 Transport Operators A and B.

For this, the Transport Service Organizer Z performs the following data transactions:

  1. Z executes § 4.1 Data Transaction 1: TCE Data Exchange with Transport Operator A to collect the TCEs for the first leg of the shipment.

  2. As Transport Operator B does not support § 4.1 Data Transaction 1: TCE Data Exchange, Z performs § 4.3 Data Transaction 3: Transport Activity Data Exchange with Transport Operator B to collect the TAD for the second leg of the shipment.

  3. Z then calculates the TCEs for the 2nd leg of the shipment based on the TAD data and modelled or default factors.

5.1.2. Data Collection by Transport Service User S

After Transport Service Organizer Z has performed its data collection, the Transport Service User S can calculate the logistics emissions of the shipment by

  1. collecting the TCEs from Z using the shipment id and § 4.1 Data Transaction 1: TCE Data Exchange, storing the resulting TCEs in e.g. its database.

  2. S can further verify the TCEs by collecting the TOCs from Z using § 4.2 Data Transaction 2: TOC Data Exchange

  3. To compute the logistics emissions, Z can form the TC from the collected TCEs by taking the TCEs of step 1 and by calculating the logistics emissions for this shipment by following the [GLEC] Framework and [ISO14083].

5.2. Example HTTP Calls

5.2.1. Data Collection by Transport Service Organizer Z

To collect the TCEs from Transport Operator A, Z performs the following HTTP call.

Note: The call to /footprints can return several footprints, 1 for each shipment. By filtering, e.g. by the shipment id, Z can retrieve the TCEs for the shipment of interest (not shown below).

The highlighted lines show the data exchanged according to the ShipmentFootprint data model.

Example HTTP Request (cURL) to collect TCE Data from Transport Operator A (please note that an actual API call would require authentication):
curl -X 'GET' \
'https://api.transport-operator-a.com/2/footprints'

Example response:

{    "id": "d9be4477-e351-45b3-acd9-e1da05e6f633",    "specVersion": "2.0.0",    "version": 0,    "created": "2022-05-22T21:47:32Z",    "status": "Active",    "companyName": "Super Duper Transport Co.",    "companyIds": [ "urn:epc:id:sgln:4063973.00000.8" ],    "productDescription": "Logistics emissions related to shipment with ID 1237890",    "productIds": [ "urn:pathfinder:product:customcode:vendor-assigned:1237890" ],    "productCategoryCpc": "83117",    "productNameCompany": "Shipment with ID 1237890",    "comment": "",    "pcf": {      "declaredUnit": "ton kilometer",      "unitaryProductAmount": "36.801",      "pCfExcludingBiogenic": "3.6801",      "fossilGhgEmissions": "3.6801",      "fossilCarbonContent": "0.0",      "biogenicCarbonContent": "0.0",      "characterizationFactors": "AR5",      "crossSectoralStandardsUsed": [ "GHG Protocol Product standard" ],      "productOrSectorSpecificRules": [],      "boundaryProcessesDescription": "SFC GLEC Framework-conforming (W2W CO2e emissions)",      "referencePeriodStart": "2021-01-01T00:00:00Z",      "referencePeriodEnd": "2022-01-01T00:00:00Z",      "secondaryEmissionFactorSources": [ { "name": "GLEC", "version": "3.0" } ],      "exemptedEmissionsPercent": 0.0,      "exemptedEmissionsDescription": "",      "packagingEmissionsIncluded": true,      "primaryDataShare": 100.0    },    "extensions": [      {        "specVersion": "2.0.0",        "dataSchema": "https://catalog.carbon-transparency.com/sfc-ileap/0.0.1/shipmentfootprint.json",        "data": {          "mass": "87",          "shipmentId": "1237890",          "tces": [            {              "tceId": "abcdef",              "prevTceIds": [],              "tocId": "truck-40t-euro5-de",              "shipmentId": "1237890",              "mass": "87",              "distance": {                "actual": "423"              },              "transportActivity": "36.801",              "co2eWTW": "3.6801",              "co2eTTW": "3.2801"            }          ]        }      }    ]  }

5.2.2. Data Collection by Transport Service User S

To collect the TCEs data related to the shipment from Transport Organizer Z, S performs the following HTTP call which yields 2 TCEs.

Note: The call to /footprints can return several footprints, 1 for each shipment. By filtering, e.g. by the shipment id, Z can retrieve the TCEs for the shipment of interest (not shown below).

The highlighted lines show 2 TCEs which Z has collected and calculated for S.

Example HTTP Request (cURL) to collect TCE Data (please note that an actual API call would require authentication):
curl -X 'GET' \
'https://api.transport-organizer.com/2/footprints'

Example response:

{    "id": "fb1faac2-7712-458a-a1db-bace3a44abb4",    "specVersion": "2.0.0",    "version": 0,    "created": "2022-05-22T21:47:32Z",    "status": "Active",    "companyName": "Transport Organizer Z",    "companyIds": [ "urn:epc:id:sgln:123456.00000.8" ],    "productDescription": "Logistics emissions related to shipment with ID 1237890",    "productIds": [ "urn:pathfinder:product:customcode:vendor-assigned:shipment:1237890" ],    "productCategoryCpc": "83117",    "productNameCompany": "Shipment with ID 1237890",    "comment": "",    "pcf": {      "declaredUnit": "ton kilometer",      "unitaryProductAmount": "64.728",      "pCfExcludingBiogenic": "8,42769",      "fossilGhgEmissions": "8,42769",      "fossilCarbonContent": "0.0",      "biogenicCarbonContent": "0.0",      "characterizationFactors": "AR5",      "crossSectoralStandardsUsed": [ "GHG Protocol Product standard" ],      "productOrSectorSpecificRules": [],      "boundaryProcessesDescription": "SFC GLEC Framework-conforming (W2W CO2e emissions)",      "referencePeriodStart": "2021-01-01T00:00:00Z",      "referencePeriodEnd": "2022-01-01T00:00:00Z",      "secondaryEmissionFactorSources": [ { "name": "GLEC", "version": "3.0" } ],      "exemptedEmissionsPercent": 0.0,      "exemptedEmissionsDescription": "",      "packagingEmissionsIncluded": true,      "primaryDataShare": 56.85    },    "extensions": [      {        "specVersion": "2.0.0",        "dataSchema": "https://catalog.carbon-transparency.com/sfc-ileap/0.0.1/shipmentfootprint.json",        "data": {          "mass": "87",          "shipmentId": "1237890",          "tces": [            {              "tceId": "abcdef",              "prevTceIds": [],              "tocId": "truck-40t-euro5-de",              "shipmentId": "1237890",              "mass": "87",              "distance": {                "actual": "423"              },              "transportActivity": "3.6801",              "co2eWTW": "3.6801",              "co2eTTW": "3.2801"            },            {              "tceId": "ghijkl",              "prevTceIds": [ "abcdef" ],              "tocId": "operator-z-truck-89sdff",              "shipmentId": "1237890",              "mass": "87",              "distance": {                "actual": "321"              },              "transportActivity": "27.927",              "co2eWTW": "4.74759",              "co2eTTW": "4.272831"            }          ]        }      }    ]  }

6. Data Model

The iLEAP data model of this chapter together with the data transactions (§ 4 Data Transactions) build on top of the ISO 14083 concepts of TOC, HOC, TCE, TC.

Additionally, the concept of transport activity data (TAD) is added to facilitate reporting in case of missing data or limited emissions calculation capabilities from e.g. Transport Operators.

Please, find more details on emissions calculation and the relantionship between the different concepts in the [GLEC] Framework and [ISO14083]).

The iLEAP Data Model is composed by five main data types: ShipmentFootprint, TCE, TOC, HOC, and TAD.

ShipmentFootprints and TOCs can be exchanged independently as extensions to the Pathfinder Data Model ([PACTDX]) (see [DATA-MODEL-EXTENSIONS]) in a ProductFootprint.

TADs can be exchanged through a dedicated endpoint. These should only be used by Transport Operators who cannot yet provide ShipmentFootprints, TOCs, nor HOCs.

6.1. ShipmentFootprint

ShipmentFootprint is a collection of 1 or more Transport Chain Elements (encoded as TCEs) for a single shipment and from a single entity (a Transport Operator or a Transport Service Organizer).

By collecting 1 or more TCEs for a shipment from Transport Operators and Transport Service Organizer, a Transport Service User can construct the ShipmentFootprint. The ShipmentFootprint corresponds to the logistics emissions related to a full Transport Chain (TC).

To calculate a ShipmentFootprint, the Transport Service User MUST

6.1.1. Data Attributes

A ShipmentFootprint has the following properties:

Property Type Req Specification
mass String M The mass of the good (SI Unit kilograms) and the packaging provided for transport by the Transport Service User, excluding any additional packaging or handling equipment used by the Transport Operator or Transport Service Organizer
volume String O The volume of the freight (SI Unit cubic metre (CBM)) and any packaging provided by the Transport Service User.
numberOfItems String O The number of units the shipment, including the goods transported and any packaging provided by the Transport Service User, is composed of.
typeOfItems String O The type of units the shipment, including the goods transported and any packaging provided by the Transport Service User, is composed of. For example, boxes, pallets, bottles, etc.
shipmentId String M The shipment id of the shipment related to this ShipmentFootprint
tces TCE[] M The non-empty array of TCEs relating to this shipment.
ShipmentFootprint properties

numberOfItems and typeOfItems are currently underspecified and need to be re-visited / revised soon.

6.2. Transport Chain Element ( TCE )

The Data Type TCE models information related to a single Transport Chain Element.

The data related to TCEs can be obtained from direct measurement (see Primary Data) or other measurements (see Secondary Data).

TCEs are typically calculated by Transport Operators and Transport Service Organizers. They are made available to Transport Service Users through the ShipmentFootprint data type and the Pathfinder Data Exchange Protocol. See § 6.1 ShipmentFootprint and § 7.2 Pathfinder Integration for details.

6.2.1. Ordering of TCEs

For reasons of transparency, traceability, auditability, and comprehensibility, the recipients of TCE data (Transport Service User or Transport Service Organizer) SHOULD also receive the information on the order in which the TCEs occurred during the transport of the shipment.

Order here means "happens-before" relationship between TCEs relative to other TCEs of the same ShipmentFootprint.

To facilitate this, the data model of TCEs includes the property prevTceIds.

If defined, prevTceIds MUST reference all the IDs (tceId) of the TCEs which happened immediately before the current TCE and ShipmentFootprint. If the property is defined and the array is empty, the current TCE MUST be the first TCE of the shipment in relation to the ShipmentFootprint.

A Transport Service User procured the shipment of 2 containers to Rotterdam through a Transport Service Organizer. The organizer then makes a ShipmentFootprint available to the Transport Service User, consisting of the following TCEs:

  1. two TCEs with IDs tce1234 and tce567 for the first leg of the shipment, which is the transport of the 2 containers from the warehouse to the port. For both TCEs, prevTceIds must equal [] (the empty array).

  2. one TCE with ID tce890 for the second leg of the shipment, which is the transport of the 2 containers from the port in Shanghai to the port of Rotterdam. For this TCE, prevTceIds must equal ["tce1234", "tce567"].

  3. And, last but not least, another TCE with ID tceABC for the hub operations at Rotterdam. For this TCE, prevTceIds must equal ["tce890"].

TCE happened-before relationship graph

6.2.2. Data Attributes

The Data Type TCE has the following properties:

Note: The properties tocId and hocId are mutually exclusive, but one of them MUST be defined.

Property Type Req Specification
tceId String M The id of the Transport Chain Element
prevTceIds String[] O If defined, the tceIds of Transport Chain Element preceding the current TCE. See § 6.2.1 Ordering of TCEs for more information.
tocId String If defined, the id of the TOC used for the calculation of this TCE.

Either tocId or hocId MUST be defined.

hocId String If defined, the id of the HOC used for the calculation of this TCE.

Either tocId or hocId MUST be defined.

shipmentId String M The shipment id of the shipment related to this TCE
consignmentId String O The consignment id of the consignment related to the shipment related to this TCE
mass : Decimal String M The freight mass (SI derived Unit kilograms) and the packaging provided for transport by the Transport Service user, excluding any additional packaging or handling equipment used by the Transport Operator or Transport Service Organizer, in accordance with the [GLEC] Framework.
packagingOrTrEqType PackagingOrTrEqType O Category of relevant packaging or transport equipment units utilized for the transport of the consignment. See data type PackagingOrTrEqType for further information.
packagingOrTrEqAmount Number O Number of packaging or transport equipment units utilized to transport the related consignment by the Transport Operator or Transport Service Organizer.
distance GLECDistance M The distance between the origin and the destination of the activity related to the TCE
origin Location O The origin of the activity related to the TCE
destination Location O The destination of the activity related to the TCE
transportActivity : Decimal String M The transport activity of the TCE (SI derived Unit ton kilometers)
If the transport distance is 700 kilometers and the mass is 230 kilograms, then the value of this property MUST be 161000 (700 kilometers * 230 kilograms).
departureAt String O Timestamp of departure. The value MUST be a date and time string conforming to ISO 8601 with timezone UTC.

Note: the original data model defined this as the "date of loading"

arrivalAt String O Timestamp of arrival. The value MUST be a date and time string conforming to ISO 8601 with timezone UTC.
flightNo String O Identification no of the IATA flight number.
voyageNo String O Identification no of a specific vessel conducting a specific route.
incoterms String O Incoterms are a set of internationally recognized rules defining the responsbilities of sellers and buyer in relation to the logistics activities between the parties. Unterstanding who pays for the shipment can help identify the Scope3 Category in which each party has to report their emissions.

If defined, the value of this property MUST be one of the following:

EXW

Ex Works

FCA

Free Carrier

CPT

Carriage Paid to

CIP

Carriage and Insurance Paid to

DAP

Delivered at Place

DPU

Delivered at Place Unloaded

DDP

Delivered Duty Paid

FAS

Free Alongside Ship

FOB

Free on Board

CFR

Cost and Freight

CIF

Cost, Insurance and Freight

co2eWTW : Decimal String M GHG emissions released to atmosphere during the process of producing, storing, processing and distributing an energy carrier for vehicle operation + GHG emissions released to atmosphere as a result of vehicle operation. The value MUST be calculated for the TCE with unit kgCO2e.
co2eTTW : Decimal String M GHG emissions released to atmosphere as a result of vehicle operation The value MUST be calculated for the TCE with unit kgCO2e.
noxTTW : Decimal String O Nitrogen oxide released to atmosphere as a result of vehicle operation. The value MUST be calculated for the TCE with unit kg.
soxTTW : Decimal String O Sulphur oxide released to atmosphere as a result of vehicle operation. The value MUST be calculated for the TCE with unit kg.
ch4TTW : Decimal String O Methane released to atmosphere as a result of vehicle operation. The value MUST be calculated for the TCE with unit kg.
pmTTW : Decimal String O Particulate matter (PM10 and PM2.5) released to atmosphere as a result of vehicle operation. The value MUST be calculated for the TCE with unit kg.
Properties of data type TCE

6.3. Transport Operation Category ( TOC )

The Data Type TOC contains transport operation category data.

The Transport Operator or Transport Service Organizer MUST calculate the TOC in accordance with the [GLEC] Framework.

The Transport Operator or Transport Service Organizer CAN then make the TOC available through the Pathfinder Network API as a ProductFootprint (see § 7.2.2 TOC).

Transport Operation Category data can be obtained from direct measurement (see primary data definition of [ISO14083]) or other measurements (see secondary data definition of [ISO14083]) such as modelled data or default value.

6.3.1. Data Attributes

The Data Type TOC has the following properties:

Property Type Req Specification
tocId String M Unique id of the TOC relative to the Host system.
isVerified Boolean M Indicates that the truthfulness of the GHG emissions value and related variables has been confirmed by a Validation and Verification Body (VVB), as declared in a Verification Statement. The VVB must follow a widely recognized standard for their GHG verification services (example: the ISO or ISAE standards). Verification should use [ISO14083] as audit criteria.
isAccredited Boolean M (=certified)Indicates that the calculation methodology has been evaluated as compliant with [ISO14083]:2023, as declared in an Accreditation (=Certification) certificate.
description String O Text description of the applicable TOC. Reflect on mode of transport, contract type, equipment type, vehicle type, freight temperature, LTL/FTL etc
mode : TransportMode String M
loadFactor : Decimal String O Ratio of the mass of the actual load to the maximum legally authorized load of a particular vehicle on a TOC level. It is applied to the loaded distance of the transport.

The value of this property must be between 0 (excluding) and 1 (including).

emptyDistanceFactor : Decimal String O Ratio of the section of the route of a vehicle during which no freight is transported over the total distance (loaded plus empty distance) of a vehicle on a TOC level

The value of this property must be between 0 (including) and 1 (excluding).

temperatureControl String O Temperature control status of the TOC.

If defined, the value of this property MUST be set to one of the following values:

  • ambient: for non-temperature controlled freight

  • refrigerated: for refrigerated freight

  • mixed: for TOCs comprising the handling of both ambient and refrigerated freight

truckLoadingSequence String O Only for road. If defined, the value MUST be one of the following:
LTL

For less than truck load, as defined in the [GLEC] Framework. The sequence of pick-up & drop-off is PU-PU-DO-DO

FTL

For full truck load, as defined in the [GLEC] Framework. The sequence of pick-up & drop-off is PU-DO-PU-DO

airShippingOption String O Only for air transport. Indicates if the movement of freight is combined with passanger transport (belly freight), or a dedicated aircraft for the movement of freight (freighter).

If defined, the value MUST be one of the following:

belly freight

For freight combined with passanger transport

freighter

For freight moved by a dedicated aircraft

flightLength String O Only for air transport. Indicates if the distance travelled is smaller or greater than 1500 km, as defined in the [GLEC] Framework.

If defined, the value MUST be one of the following:

short-haul

For distances smaller than 1500 km

long-haul

For distances greater than 1500 km

energyCarriers EnergyCarrier[] M The non-empty array of EnergyCarriers used to generate mechanical movement or heat and to generate chemical or physical processes, as defined in the [GLEC] Framework.
co2eIntensityWTW : Decimal String M The Coefficient relating specified transport activity with WTW GHG emissions with unit kgCO2e per co2eIntensityWTW as defined in the [GLEC] Framework
co2eIntensityTTW : Decimal String M The Coefficient relating specified transport activity with TTW GHG emissions with unit kgCO2e per co2eIntensityTTW as defined in the [GLEC] Framework
co2eIntensityThroughput String M Indicates the freight transport activity unit at the denominator of the co2eIntensityWTW and at the denominator of the co2eIntensityTTW. At the TOC level, the possible values are
TEUkm

for sea and inland waterways

tkm

for everything else

The enumeration of throughputs will be evolved in future revisions. Account for this when implementing the validation of this property.

glecDataQualityIndex : [0..4] Number O The data quality index as defined in the [GLEC] Framework

The value of this property must be between 0 (including) and 4 (including).

the exact calculation rules must be defined

Properties of data type TOC

6.4. Hub Operation Category ( HOC )

The Data Type HOC contains HOC data. It is referenced in a Transport Chain Element through the hocId property.

Please, note that variables pertaining to the HOC Data Type have not been validated and are subject to undergo major updates.

HOCs are the building blocks for the calculation of a Transport Chain Element with hub operations.

6.4.1. Data Attributes

The Data Type HOC has the following properties:
Property Type Req Specification
hocId String M The id of the HOC
description String O Text description of the applicable HOC. Reflect on hub type, contract type, equipment type, freight temperature, etc
isVerified Boolean M Indicates that the truthfulness of the GHG emissions value and related variables has been confirmed by a Validation and Verification Body (VVB), as declared in a Verification Statement. The VVB must follow a widely recognized standard for their GHG verification services (example: the ISO or ISAE standards). Verification should use [ISO14083] as audit criteria.
isAccredited Boolean M (=certified)Indicates that the calculation methodology has been evaluated as compliant with [ISO14083]:2023, as declared in an Accreditation (=Certification) certificate.
hubType HubType M Type of Hub
temperatureControl String O Temperature control status of the hub.

If defined, the value of this property MUST be set to one of the following values:

  • ambient: for HOCs comprising the handling of non-temperature controlled freight only

  • refrigerated: for HOCs comprising the handling of refrigerated freight only

  • mixed: for HOCs comprising the handling of both ambient and refrigerated freight

hubLocation Location O The address of the hub.
inboundTransportMode: TransportMode TransportMode O Indicates the transport mode upstream the hub for the hub operations the HOC is defined for.
outboundTransportMode: TransportMode TransportMode O Indicates the transport mode downstream the hub for the hub operations the HOC is defined for.
packagingOrTrEqType String O Category of relevant packaging or transport equipment units utilized for the transport of the consignment. See data type PackagingOrTrEqType for further information.
packagingOrTrEqAmount Number O Number of packaging or transport equipment units utilized to transport the related consignment by the Transport Operator or Transport Service Organizer.
energyCarriers EnergyCarrier[] M The non-empty array of EnergyCarriers used to generate mechanical movement or heat and to generate chemical or physical processes, as defined in the [GLEC] Framework.
co2eIntensityWTW : Decimal String M The Coefficient relating specified transport activity with WTW GHG emissions with unit kgCO2e per co2eIntensityThroughput as defined in the [GLEC] Framework
co2eIntensityTTW : Decimal String M The Coefficient relating specified transport activity with TTW GHG emissions with unit kgCO2e per co2eIntensityTTW as defined in the [GLEC] Framework
co2eIntensityThroughput String M Indicates the freight transport activity unit at the denominator of the co2eIntensityWTW and at the denominator of the co2eIntensityTTW. At the HOC level, the possible values are
TEU

leaving the hub for sea and inland waterways as outbound transport mode

tonnes

leaving the hub

The enumeration of throughputs will be evolved in future revisions. Account for this when implementing the validation of this property.

Properties of data type HOC

6.5. Transport Activity Data (TAD)

The Transport Activity Data  (TAD) data type contains activity data, referring to a single consignment, leg, and mode of transport, or to a single transshipment within a hub.

Each TAD CAN contain values for attributes which are categorial to the operations of a fleet or hub (such as load factor or mix of feedstock(s)). In this case, the values CAN be calculated from the actual data of more than one consignment (“representative” or “average data”).

Instead of exchanging the load factor for a single assignment, the load factor can be calculated from a multitude of consignments following the principles of TOC calculation.

The TAD data type is designed for entities (Transport Operators or Transport Service Organizers) that lack the capabilities to perform carbon emission calculations (see Business Case 3) or are contractually obliged to exchange activity data with another party.

It can also be used by the service providers (Transport Operator or Transport Service Organizer) to provide additional transparency to their business partners where relevant.

6.5.1. Data Attributes

Below table lists the properties defined for the TAD data type.

When exchanging it through the Action TransportActivityData, it MUST be encoded as a JSON object. See § 7.1 Action TransportActivityData for details.

Attribute Id Type Req Description
activityId String M The non-empty unique ID of this activity relative to the host system.
consignmentIds String[] M The non-empty array of unique IDs of the consignments related to the activity.
distance GLECDistance M The Distance between the origin and the destination of the activity
mass : Decimal String O Mass of freight (SI derived Unit kilograms)
loadFactor : Decimal String O Ratio of the mass of the actual load to the maximum legally authorized load of a particular vehicle on a TOC level. It is applied to the loaded distance of the transport.

The value of this property must be between 0 (excluding) and 1 (including).

emptyDistanceFactor : Decimal String O Ratio of the section of the route of a vehicle during which no freight is transported over the total distance (loaded plus empty distance) of a vehicle on a TOC level

The value of this property must be between 0 (including) and 1 (excluding).

origin Location M The origin of the activity related to the TCE
destination Location M The destination of the activity related to the TCE
departureAt String M Timestamp of departure. The value MUST be a date and time string conforming to ISO 8601 with timezone UTC. NOTE: the original data model defined this as the "date of loading"
arrivalAt String M Timestamp of arrival. The value MUST be a date and time string conforming to ISO 8601 with timezone UTC.
mode TransportMode M Mode of transport
packagingOrTrEqType String O Category of relevant packaging or transport equipment units utilized for the transport of the consignment. See data type PackagingOrTrEqType for further information.
packagingOrTrEqAmount Number O Number of packaging or transport equipment units utilized to transport the related consignment by the Transport Operator or Transport Service Organizer.
energyCarrier EnergyCarrierType O The substance used to generate mechanical movement or heat and to generate chemical or physical processes as per the [GLEC] Framework. See data type EnergyCarrierType for further information.

If energyCarrier is not defined, then feedstocks MUST be defined. If possible, both SHOULD be defined.

feedstocks Feedstock[] O If defined, the non-empty array of Feedstocks of the energy carrier. The sum total of the feedstock percentages MUST be smaller than or equal to 1.

If feedstocks is not defined, then energyCarrier MUST be defined. If possible, both SHOULD be defined.

TAD properties

6.6. Additional Utility Data Types

6.6.1. Data Type GLECDistance

Data type GLECDistance represents a distance between origin and destination as defined in the [GLEC] Framework.

In JSON an GLECDistance MUST be encoded as a JSON Object.

At least one of the following properties of data type GLECDistance the MUST be defined:

Attribute Id Type Req Description
actual : Decimal String O The distance between the origin and the destination of a consignment of freight or a vehicle, along a specified route (or from telematics), as defined in the [GLEC] Framework
gcd : Decimal String O Great Circle Distance between the origin and the destination, as defined in the [GLEC] Framework
sfd : Decimal String O Shortest Feasible Distance between the origin and the destination, as defined in the [GLEC] Framework
GLECDistance properties

6.6.2. Data Type Location

Properties of data type Location:

Attribute Id Type Req Definition
street String O Street of the location
zip String O Postal code of the location
city String M City of the location
country Country M An ISO 3166-2 alpha-2 country code. See https://wbcsd.github.io/data-exchange-protocol/v2/#iso3166cc for details.
iata iataCode O IATA code of airport
locode locode O UN/LOCODE of the location
uic uic O UIC Code of the location
lat Decimal O Latitude of the location. If lng is defined, so MUST lat be defined
lng Decimal O Longitude of the location. If lat is defined, so MUST lng be defined
GLECDistance properties

6.6.3. Data Type TransportMode

The Data Type TransportMode is an enumeration of the transport modes as defined in the [GLEC] Framework.

It MUST be encoded as a String using one of the following values:

Road

for transport mode road

Rail

for transport mode rail

Air

for transport mode air

Sea

for transport mode sea

InlandWaterway

for transport mode inland waterway

NOTE: : Hub operations are excluded from here, as these transport modes are defined for TOC, and HOC is defined separately

6.6.4. Data Type HubType

The Data Type HubType is an enumeration of the main hub types as defined in the [GLEC] Framework.

It MUST be encoded as a String using one of the following values:

Transshipment

refers to hubs where transshipment is the main service (>80% of goods handled)

StorageAndTransshipment

refers to hubs where both transshipment and warehousing are relevant services

Warehouse

refers to hubs where warehousing is the main service (>80% of goods handled)

LiquidBulkTerminal

refers to terminals equiped to handle cargo in liquid and gaseous forms

MaritimeContainerTerminal

refers to hubs where maritime containers are handled

6.6.5. Data Type Decimal

A decimal number.

In JSON, a Decimal MUST be encoded as a JSON String.

Note: the JSON String encoding is necessary to avoid floating point rounding errors.

Example of the decimal numbers 10 and -0.123 encoded in JSON:
"10"
"-0.123"

6.6.6. Data Type EnergyCarrier

Data type EnergyCarrier represents an energy carrier, including its feedstocks.

In JSON an EnergyCarrier MUST be encoded as a JSON Object.

The following properties are defined for data type EnergyCarrier:

Attribute Id Type Req Definition
energyCarrier EnergyCarrierType M The substance used to generate mechanical movement or heat and to generate chemical or physical processes as per the [GLEC] Framework. See data type EnergyCarrierType for further information.
feedstocks Feedstock[] O If defined, theon-empty array of Feedstocks of the energy carrier. The sum total of the feedstock percentages MUST be smaller than or equal to 1.
energyConsumption : Decimal String O Amount of energy carrier consumed per transport activity, as defined for the TOC or HOC. If defined, energyConsumptionUnit MUST be defined as well.
energyConsumptionUnit String O Unit of the energy consumed corresponding to the energyConsumption. energyConsumptionUnit MUST be defined if energyConsumption is defined.

Possible values are:

The enumeration of energy consumption units will be evolved in future revisions. Account for this when implementing the validation of this property.

l

for liters

kg

for kilograms

kWh

for kiloWhat/hour

MJ

for MegaJoules

emissionFactorWTW : Decimal String M The WTW fuel emission factor (certified) with unit kgCO2e / energy consumption unit (energyConsumptionUnit)
emissionFactorTTW : Decimal String M The TTW fuel emission factor (certified) with unit kgCO2e / energy consumption unit (energyConsumptionUnit)

6.6.7. Data Type EnergyCarrierType

Data type EnergyCarrierType represents the substance used to generate mechanical movement or heat and to generate chemical or physical processes as per the [GLEC] Framework.

It MUST be encoded as a String using one of the following values:

The enumeration of energy carrier types below will be evolved in future revisions. Account for this when implementing the validation of this property.

Diesel

refers to diesel

HVO

refers to Hydrotreated Vegetable Oil

Petrol

refers to petrol

CNG

refers to Compressed Natural Gas

LNG

refers to Liquefied Natural Gas

LPG

refers to Liquefied Petroleum Gas

HFO

refers to Heavy Fuel Oil

MGO

refers to Marine Gas Oil

Aviation fuel

refers to aviation fuel

Hydrogen

refers to hydrogen

Methanol

refers to methanol

Electric

refers to electricity

6.6.8. Data Type Feedstock

Data type Feedstock represents one feedstock of an EnergyCarrier.

In JSON an Feedstock MUST be encoded as a JSON Object.

The following properties are defined for data type Feedstock:

Attribute Id Type Req Definition
feedstock String M A feedstock of an EnergyCarrier.

The value MUST be one of the following:

The enumeration of feedstocks below will be evolved in future revisions. Account for this when implementing the validation of this property.

Fossil

refers to fossil sources

Natural gas

refers to natural gas

Grid

refers to grid electricity

Renewable electricity

refers to renewable sources of electricity

Cooking oil

refers to cooking (e.g., vegetable) oil

feedstockPercentage : [0..1] Number O Percentage of the feedstock in the total composition of energy carrier.
regionProvenance String O Country or region of provenance of the feedstock.

6.6.9. Data Type PackagingOrTrEqType

Data type PackagingOrTrEqType represents the category of relevant packaging or transport equipment units utilized for the transport of the consignment by the Transport Operator or Transport Service Organizer.

It MUST be encoded as a String using one of the following values:

The enumeration of packaging or transport equipment units below will be evolved in future revisions. Account for this when implementing the validation of this property.

Box

refers to boxes

Pallet

refers to pallets

Container

refers to containers

7. HTTP REST API

A host system MUST implement:

  1. The endpoint for the exchange of Transport Activity Data (see § 7.1 Action TransportActivityData); and

  2. The exchange of ShipmentFootprint and TOC as specified in § 7.2 Pathfinder Integration.

The exchange of logistics emissions data throught the § 6 Data Model presupposes the implementation of the HTTP REST API defined in [PACTDX] (Chapter 6).

Reusing the [PACTDX] data exchange protocol simplifies the integration of logistics emissions data into existing host systems software, especially if they are already used by Transport Service Users.

They can then use 1 interoperable API for the exchange of different categories of carbon emissions data related to GHG Protocol lifecycle stages (such as material acquisition and transport).

Additionally, by mapping the GLEC Data model into the [PACTDX] data model, existing host systems can be gradually extended to support calculation of logistics emissions in accordance with the [GLEC] Framework and [ISO14083].

7.1. Action TransportActivityData

Lists the data owner's Transport Activity Data with § 7.1.2 Pagination and optional § 7.1.1 Filtering

A Host system SHOULD implement an access management system to return only the transport activity data intended for the requesting data recipient.

7.1.1. Filtering

Filtering CAN be requested by a data recipient by supplying a filter statement through the Filter request parameter.

Note: The filter statement syntax is described at the Filter request parameter.

If a host system does not implement filtering, it MUST process the request as if no Filter was provided.

If a host system implements filtering, it CAN process the filter statement on a best-effort basis:

  1. it CAN ignore the filter statement or parts of the filter statement, or

  2. it CAN return an error response as defined in the Pathfinder Technical Specifications. For instance, a host system CAN return an error with code NotImplemented if it does not support a specific filter pair.

  3. it CAN treat concatenated filters disjunctively, i.e., returning the union of the results of the individual filters.

7.1.2. Pagination

Host systems MUST implement pagination server-side such that

  1. The host system MAY return less Transport Activity Data than requested through the Limit request parameter

  2. The host system MUST return a Link header if there is additional Transport Activity Data ready to be retrieved, such that

  3. The Link header conforms to [RFC8288]

  4. The value of the rel parameter is equal to next

  5. the target IRI (RFC8288, section 3.1) of the Link header is absolute

  6. The value of host of the target IRI is equal to the value of the host request header from the original TransportActivityData HTTP request

The target IRI from a pagination link header is called a pagination link.

Upon a host system returning a pagination link

  1. a data recipient CAN call the pagination link more than once

  2. upon each call, the host system

    1. MUST return the same Transport Activity Data upon successful authentication (i.e. a Bearer token authentication as defined in [PACTDX] Section 6.3)

    2. MUST NOT return more data than requested in case Limit was defined by a data recipient

    3. MUST return a Link header conforming with the previous description in case there is additional Transport Activity Data available

  3. If a response contains a second pagination link and the data recipient upon calling the second pagination link, the previous pagination link MAY no longer work

    • i.e. data recipients MUST NOT assume that previous pagination links continue to return results after advancing in the pagination process

  4. a pagination link MUST be valid for at least 180 seconds after creation

  5. a data recipient SHOULD retry calling the pagination link after the server returned an error

  6. and SHOULD use a randomized exponential back-off strategy when retrying

7.1.3. Request Syntax

GET Subpath/2/ileap/tad?Filter&Limit HTTP/1.1
host: Hostname
authorization: Bearer BearerToken
Subpath

If a host system uses a relative subpath, then the requesting data recipient MUST prepend this subpath.

Hostname

The requesting data recipient MUST use the domain name of the host system.

BearerToken

See [PACTDX] section 6.3 Authentication Flow.

Filter

Filter is an OPTIONAL request parameter containing a filter statement. A filter statement is a list of name-value filter pairs. Each filter pair has a $name=$value syntax where $name is the (case-sensitive) name of the field to filter by, and $value the (case-insensitive) value to filter for. Filter pairs CAN be concatenated with &.

Get transport activity data with Feedstock "Fossil" and packagingOrTrEqType "Pallet"
GET /2/ileap/tad?feedstock=Fossil&packagingOrTrEqType=pallet HTTP/1.1
Limit

Limit is an OPTIONAL request parameter. If defined,

  1. the name of the HTTP request parameter MUST be limit

  2. and the value MUST be a positive integer.

7.1.4. Response Syntax

Response without a link header:

HTTP/1.1 TadStatusCode TadStatusText
content-type: application/json
content-length: ContentLength

TadResponseBody

Paginated response with a link header:

HTTP/1.1 TadStatusCode TadStatusText
content-type: application/json
content-length: ContentLength
link: PaginationLink; rel="next"

TadResponseBody

With response parameters

TadStatusCode

If the host system returns transport activity data, the HttpStatusCode MUST be 200.

If the host system responds with an error response, the HttpStatusCode MUST match the HTTP Status Code of the respective error response code, as defined in the Pathfinder Technical Specifications.

TadStatusText

The HTTP Status text conforming to the HTTP status code TadStatusCode.

TadResponseBody

If the host system accepts the access token, the body MUST be a JSON object with property data with value the list of Transport Activity Data. The list MUST be encoded as a JSON array.

If the host system does not accept the access token, the body MUST be an error response with code AccessDenied.

If the host system does not accept the access token because it expired, the body SHOULD be an error response with code TokenExpired.

In all other cases, for instance in case of a malformed value of the header authorization, the body SHOULD be an error response with code BadRequest.

ContentLength

The length of the Body. See [rfc9112].

PaginationLink

see pagination link and § 7.1.2 Pagination.

7.2. Pathfinder Integration

The Data types defined in § 6 Data Model are specific to [ISO14083] and the [GLEC] Framework.

This section specifies the integration of the data types ShipmentFootprint and TOC into the Pathfinder Data Model ([PACTDX] Chapter 4).

The integration of the data types ShipmentFootprint and TOC is achieved by storing them as extensions to the Pathfinder Data Model (see [DATA-MODEL-EXTENSIONS]). Therefore, all properties defined in the latter are also properties of the former. As a result, some properties relevant to logistics do not need to be defined in the § 6 Data Model. The list below contains the properties that were omitted for this reason.

Attribute Id Type Req Description Source
validityPeriodStart : DateTime String O Determines the start of the validity period, ie., the time interval during which the ProductFootprint is declared as valid for use by a receiving data recipient. ProductFootprint/validityPeriodStart
validityPeriodEnd : DateTime String O Determines the end (excluding) of the validity period, ie., the time interval during which the ProductFootprint is declared as valid for use by a receiving data recipient. ProductFootprint/validityPeriodEnd
assurance : Assurance Object O If present, the Assurance information in accordance with the [PATHFINDER-FRAMEWORK]. CarbonFootprint/assurance

7.2.1. ShipmentFootprint

Note: This chapter refers to the PACT Data Model. See [PACTDX] Chapter 4 for further details.

A ShipmentFootprint CAN be integrated into the Pathfinder Data Model ([PACTDX]) by storing a ShipmentFootprint as an extension (see [DATA-MODEL-EXTENSIONS]) in a ProductFootprint.

For interoperability reasons, [PACTDX]-related attributes MUST be derived from the ShipmentFootprint where possible. Details are specified in the table below.

Note: Section ShipmentFootprint example contains an example.

PACT Data Type Property Value Derivation
ProductFootprint productIds MUST contain the shipment ID shipmentId, encoded as
urn:pathfinder:product:customcode:vendor-assigned:shipment:<shipment id>

in case the transport service organizer has assigned a shipping id, or

urn:pathfinder:product:customcode:buyer-assigned:shipment:<shipment id>

in case the transport service user has assigned a shipping id

Note: productIds can contain multiple entries. If multiple or different shipment ids are assigned to a single shipment, productIds CAN contain all of them.

ProductFootprint productCategoryCpc MUST be equal to 83117, the CPC code of logistics services.
CarbonFootprint declaredUnit MUST be set to ton kilometer conforming with the Pathfinder Tech Specs.

See [PACTDX] Chapter 4 for further details.

CarbonFootprint unitaryProductAmount MUST equal the total ton kilometers over all TCEs (tces), calculated by taking the sum of the ton kilometers over all TCEs (see property transportActivity)
CarbonFootprint pCfExcludingBiogenic MUST be set to the total logistics emissions of the shipment, excluding biogenic emissions, calculated by taking the sum of the co2eWTW over all TCEs (tces).
CarbonFootprint pCfIncludingBiogenic This property is OPTIONAL in the [PACTDX] data Model.

It SHOULD be set to the total logistics emissions of the shipment, including biogenic emissions, calculated by taking the sum of the co2eWTW over all TCEs (tces).

CarbonFootprint fossilGhgEmissions see the specification for pCfExcludingBiogenic in this table
CarbonFootprint packagingEmissionsIncluded see [PACTDX] for further details

this property is pending input from the tech workshop(s)

CarbonFootprint primaryDataShare The relative share of logistics emissions for which primary data has been used for the calculation.

See [PACTDX] and the Pathfinder Framework ([PATHFINDER-FRAMEWORK]) for further details.

Mapping of PACT Data Model properties to ShipmentFootprint properties

7.2.2. TOC

Note: This chapter refers to the PACT Data Model. See [PACTDX] Chapter 4 for further details.

A TOC CAN be integrated into the Pathfinder Data Model ([PACTDX]) by storing a TOC as an extension (see [DATA-MODEL-EXTENSIONS]) in a ProductFootprint.

For interoperability reasons, several attributes of a ProductFootprint MUST be derived from the TOC. This is specified in the table below.

Note: Section TOC example contains an example.

PACT Data Type Property Value Derivation
ProductFootprint productIds MUST contain the TOC ID tocId, encoded as
urn:pathfinder:product:customcode:vendor-assigned:toc:<toc id>

in case the transport service organizer has assigned a toc id, or

urn:pathfinder:product:customcode:buyer-assigned:toc:<toc id>

in case the transport service user has assigned a toc id

Note: productIds can contain multiple entries. If multiple or different toc ids are assigned to a single TOC, productIds CAN contain all of them.

ProductFootprint productCategoryCpc MUST be equal to 83117, the CPC code of logistics services.
CarbonFootprint declaredUnit MUST be set to ton kilometer conforming with the Pathfinder Tech Specs.

See [PACTDX] Chapter 4 for further details.

CarbonFootprint unitaryProductAmount SHOULD be set to "1" so that the ProductFootprint represents the emissions per ton kilometer of the TOC.
CarbonFootprint pCfExcludingBiogenic MUST be set to the logistics emissions intensity of the TOC, excluding biogenic emissions, defined in co2eIntensityWTW.
CarbonFootprint pCfIncludingBiogenic This property is OPTIONAL in the [PACTDX] data Model.

It SHOULD be set to the logistics emissions intensity of the TOC, including biogenic emissions, found in co2eIntensityWTW.

CarbonFootprint fossilGhgEmissions see the specification for pCfExcludingBiogenic in this table
CarbonFootprint packagingEmissionsIncluded see [PACTDX] for further details

MUST be set to false.

CarbonFootprint primaryDataShare The relative share of logistics emissions for which primary data has been used for the calculation.

See [PACTDX] and the Pathfinder Framework ([PATHFINDER-FRAMEWORK]) for further details.

Mapping of PACT Data Model properties to TOC properties

7.2.3. HOC

Note: This chapter refers to the PACT Data Model. See [PACTDX] Chapter 4 for further details.

An HOC CAN be integrated into the Pathfinder Data Model ([PACTDX]) by storing an HOC as an extension (see [DATA-MODEL-EXTENSIONS]) in a ProductFootprint.

For interoperability reasons, several attributes of a ProductFootprint MUST be derived from the HOC. This is specified in the table below.

Note: Section HOC example contains an example.

PACT Data Type Property Value Derivation
ProductFootprint productIds MUST contain the HOC ID hocId, encoded as
urn:pathfinder:product:customcode:vendor-assigned:hoc:<hoc id>

in case the transport service organizer has assigned an hoc id, or

urn:pathfinder:product:customcode:buyer-assigned:hoc:<hoc id>

in case the transport service user has assigned an hoc id

Note: productIds can contain multiple entries. If multiple or different hoc ids are assigned to a single HOC, productIds CAN contain all of them.

ProductFootprint productCategoryCpc MUST be equal to 83117, the CPC code of logistics services.
CarbonFootprint declaredUnit MUST be set to kilogram conforming with the Pathfinder Tech Specs.

See [PACTDX] Chapter 4 for further details.

CarbonFootprint unitaryProductAmount MUST be set to "1000" so that the ProductFootprint represents the emissions of the HOC per tonne leaving the hub.
CarbonFootprint pCfExcludingBiogenic MUST be set to the logistics emissions intensity of the HOC, excluding biogenic emissions, defined in co2eIntensityWTW.

Note: In case the co2eIntensityThroughput of the HOC is TEU, per the [GLEC] framework, "an average weight of 10 tonnes per TEU can be assumed. If the containers are light, then 6 tonnes can be used as approximation, and if they are heavy, an average weight of 14.5 tonnes can be assumed."

CarbonFootprint pCfIncludingBiogenic This property is OPTIONAL in the [PACTDX] data Model.

It SHOULD be set to the logistics emissions intensity of the HOC, including biogenic emissions, found in co2eIntensityWTW.

CarbonFootprint fossilGhgEmissions see the specification for pCfExcludingBiogenic in this table
CarbonFootprint packagingEmissionsIncluded see [PACTDX] for further details

MUST be set to false.

CarbonFootprint primaryDataShare The relative share of logistics emissions for which primary data has been used for the calculation.

See [PACTDX] and the Pathfinder Framework ([PATHFINDER-FRAMEWORK]) for further details.

Mapping of PACT Data Model properties to HOC properties

Appendix A: Changelog

Version 0.2.1-20240716 (2024-07-16)

Version 0.2.1-20240708 (2024-07-08)

Version 0.2.1-20240611 (2024-06-11)

Version 0.2.0 Release (2024-06-05)

Stable Release including the following changes:

Version 0.2.0 Draft (2024-05-21)

Release Consultation Draft

Version 0.2.0-20240514 (2024-05-14)

Version 0.2.0-20240513 (2024-05-13)

Summary of changes:

Version 0.1.0 (2024-05-13)

Summary: Initial release of the specification.

Appendix B: Example PCFs with iLEAP Data embedded

In both examples, the value of dataSchema is currently placeholder and should not be taken as a link to the actual data schema. This will be updated as soon as possible.

ShipmentFootprint example

A Product Footprint with a ShipmentFootprint highlighted:

{  "id": "d9be4477-e351-45b3-acd9-e1da05e6f633",  "specVersion": "2.0.0",  "version": 0,  "created": "2022-05-22T21:47:32Z",  "status": "Active",  "companyName": "Super Duper Transport Co.",  "companyIds": [      "urn:epc:id:sgln:4063973.00000.8"  ],  "productDescription": "Logistics emissions related to shipment with ID 1237890",  "productIds": [      "urn:pathfinder:product:customcode:vendor-assigned:shipment:1237890"  ],  "productCategoryCpc": "83117",  "productNameCompany": "Shipment with ID 1237890",  "comment": "",  "pcf": {    "declaredUnit": "ton kilometer",    "unitaryProductAmount": "36.801",    "pCfExcludingBiogenic": "3.6801",    "fossilGhgEmissions": "3.6801",    "fossilCarbonContent": "0",    "biogenicCarbonContent": "0",    "characterizationFactors": "AR6",    "ipccCharacterizationFactorsSources": [        "AR6"    ],    "crossSectoralStandardsUsed": [        "GHG Protocol Product standard"    ],    "productOrSectorSpecificRules": [],    "boundaryProcessesDescription": "SFC GLEC Framework-conforming (W2W CO2e emissions)",    "referencePeriodStart": "2021-01-01T00:00:00Z",    "referencePeriodEnd": "2022-01-01T00:00:00Z",    "secondaryEmissionFactorSources": [        {            "name": "Ecoinvent",            "version": "3.9.1"        }    ],    "exemptedEmissionsPercent": 0,    "exemptedEmissionsDescription": "",    "packagingEmissionsIncluded": true,    "primaryDataShare": 56.12  },  "extensions": [    {      "specVersion": "2.0.0",      "dataSchema": "https://api.ileap.sine.dev/shipment-footprint.json",      "documentation": "https://sine-fdn.github.io/ileap-extension/",      "data": {          "mass": "87",          "shipmentId": "1237890",          "tces": [              {                  "tceId": "abcdef",                  "prevTceIds": [],                  "tocId": "truck-40t-euro5-de",                  "shipmentId": "1237890",                  "mass": "87",                  "distance": {                      "actual": "423"                  },                  "transportActivity": "3.6801",                  "co2eWTW": "3.6801",                  "co2eTTW": "3.2801"              }          ]      }    }  ]}

TOC example

A Product Footprint with a TOC highlighted:

{  "id": "f3c04ec8-b33a-43b1-9fa7-d6a448fd60af",  "specVersion": "2.0.0",  "version": 0,  "created": "2022-05-22T21:47:32Z",  "status": "Active",  "companyName": "Super Duper Transport Co.",  "companyIds": [      "urn:epc:id:sgln:4063973.00000.8"  ],  "productDescription": "Logistics emissions related to TOC with ID 4561230",  "productIds": [      "urn:pathfinder:product:customcode:vendor-assigned:toc:4561230"  ],  "productCategoryCpc": "83117",  "productNameCompany": "TOC with ID 4561230",  "comment": "",  "pcf": {    "declaredUnit": "ton kilometer",    "unitaryProductAmount": "1",    "pCfExcludingBiogenic": "3.6801",    "fossilGhgEmissions": "3.6801",    "fossilCarbonContent": "0",    "biogenicCarbonContent": "0",    "characterizationFactors": "AR6",    "ipccCharacterizationFactorsSources": [        "AR6"    ],    "crossSectoralStandardsUsed": [        "GHG Protocol Product standard"    ],    "productOrSectorSpecificRules": [],    "boundaryProcessesDescription": "SFC GLEC Framework-conforming (W2W CO2e emissions)",    "referencePeriodStart": "2021-01-01T00:00:00Z",    "referencePeriodEnd": "2022-01-01T00:00:00Z",    "secondaryEmissionFactorSources": [        {            "name": "Ecoinvent",            "version": "3.9.1"        }    ],    "exemptedEmissionsPercent": 0,    "exemptedEmissionsDescription": "",    "packagingEmissionsIncluded": false,    "primaryDataShare": 56.12  },  "extensions": [    {      "specVersion": "2.0.0",      "dataSchema": "https://api.ileap.sine.dev/toc.json",      "documentation": "https://sine-fdn.github.io/ileap-extension/",      "data": {          "tocId": "4561230",          "isVerified": true,          "isAccredited": true,          "mode": "Road",          "temperatureControl": "refrigerated",          "truckLoadingSequence": "FTL",          "energyCarriers": [              {                  "energyCarrier": "Diesel",                  "co2eIntensityWTW": "3.6801",                  "co2eIntensityTTW": "3.2801"              }          ],          "co2eIntensityWTW": "3.6801",          "co2eIntensityTTW": "3.2801",          "co2eIntensityThroughput": "tkm"      }    }  ]}

HOC example

A Product Footprint with a HOC highlighted:

{  "id": "f3c04ec8-b33a-43b1-9fa7-d6a448fd60af",  "specVersion": "2.0.0",  "version": 0,  "created": "2022-05-22T21:47:32Z",  "status": "Active",  "companyName": "Super Duper Transport Co.",  "companyIds": [      "urn:epc:id:sgln:4063973.00000.8"  ],  "productDescription": "Logistics emissions related to HOC with ID 7890123",  "productIds": [      "urn:pathfinder:product:customcode:vendor-assigned:hoc:7890123"  ],  "productCategoryCpc": "83117",  "productNameCompany": "HOC with ID 7890123",  "comment": "",  "pcf": {    "declaredUnit": "kilogram",    "unitaryProductAmount": "1000",    "pCfExcludingBiogenic": "3.6801",    "fossilGhgEmissions": "3.6801",    "fossilCarbonContent": "0",    "biogenicCarbonContent": "0",    "characterizationFactors": "AR6",    "ipccCharacterizationFactorsSources": [        "AR6"    ],    "crossSectoralStandardsUsed": [        "GHG Protocol Product standard"    ],    "productOrSectorSpecificRules": [],    "boundaryProcessesDescription": "SFC GLEC Framework-conforming (W2W CO2e emissions)",    "referencePeriodStart": "2021-01-01T00:00:00Z",    "referencePeriodEnd": "2022-01-01T00:00:00Z",    "secondaryEmissionFactorSources": [        {            "name": "Ecoinvent",            "version": "3.9.1"        }    ],    "exemptedEmissionsPercent": 0,    "exemptedEmissionsDescription": "",    "packagingEmissionsIncluded": false,    "primaryDataShare": 56.12  },  "extensions": [    {      "specVersion": "2.0.0",      "dataSchema": "https://api.ileap.sine.dev/toc.json",      "documentation": "https://sine-fdn.github.io/ileap-extension/",      "data": {          "hocId": "7890123",          "isVerified": true,          "isAccredited": true,          "hubType": "Warehouse",          "temperatureControl": "refrigerated",          "energyCarriers": [              {                  "energyCarrier": "Diesel",                  "co2eIntensityWTW": "3.6801",                  "co2eIntensityTTW": "3.2801"              }          ],          "co2eIntensityWTW": "3.6801",          "co2eIntensityTTW": "3.2801",          "co2eIntensityThroughput": "tonnes"      }    }  ]}

Index

Terms defined by this specification

References

Normative References

[DATA-MODEL-EXTENSIONS]
Technical Specification for Data Model Extensions. LS. URL: https://wbcsd.github.io/data-model-extensions/spec/
[GLEC]
Global Logistics Emissions Council Framework for Logistics Emissions Accounting and Reporting; v3.0 edition, revised and updated (2023).. LS. URL: https://smart-freight-centre-media.s3.amazonaws.com/documents/GLEC_FRAMEWORK_v3_UPDATED_12_10.pdf
[ISO14083]
Greenhouse gases — Quantification and reporting of greenhouse gas emissions arising from transport chain operations. International Standard published. URL: https://www.iso.org/standard/78864.html
[PACTDX]
Martin Pompéry; Cecilia Valeri. Technical Specifications for PCF Data Exchange (Version 2.1.0). CR. URL: https://wbcsd.github.io/tr/2023/data-exchange-protocol-20231207/
[PATHFINDER-FRAMEWORK]
Pathfinder Framework: Guidance for the Accounting and Exchange of Product Life Cycle Emissions (Version 2.0). LS. URL: https://www.carbon-transparency.com/media/srhhloun/pathfinder-framework.pdf
[RFC8288]
M. Nottingham. Web Linking. October 2017. Proposed Standard. URL: https://httpwg.org/specs/rfc8288.html
[RFC9112]
R. Fielding, Ed.; M. Nottingham, Ed.; J. Reschke, Ed.. HTTP/1.1. June 2022. Internet Standard. URL: https://httpwg.org/specs/rfc9112.html

Issues Index

numberOfItems and typeOfItems are currently underspecified and need to be re-visited / revised soon.
the exact calculation rules must be defined
this property is pending input from the tech workshop(s)