iLEAP Technical Specifications (Version 1.1.0-draft.2)

1. Introduction

Transport Service Users, Transport Service Organizers, and Transport Operators face a growing need to calculate and report logistics emissions with greater accuracy and transparency. Increasingly, this means moving beyond default and modeled data toward primary data that reflects actual operational emissions.

The methodological foundations for this shift are already in place: ISO 14083:2023 and the GLEC Framework have established a shared basis for emissions accounting. Yet data access processes remain largely manual and vary from company to company, making the exchange of primary emissions data both challenging and costly.

The iLEAP Technical Specifications address this gap by enabling the structured flow of emissions and activity data across organizations and IT systems. They do so by:

1. "working backwards" from concrete business cases (§ 3 Business Cases),

2. translating those business cases into well-defined data transactions (§ 4 Data Transactions) that can be realized through independent software implementations, known as host systems,

3. defining a data exchange protocol (§ 7 HTTP REST API) to unlock the interoperable flow of data between host systems, and

4. introducing a data model (§ 6 Data Model) that aligns with ISO 14083 and the GLEC Framework V3.1.

1.1. Methodological Interoperability

The iLEAP Technical Specifications are based on ISO14083:2023, with which they are methodologically aligned and the GLEC Framework V3.1.

Furthermore, the specifications are designed to be methodologically interoperable with the PACT Methodology Version 2 and Version 3.

The iLEAP Technical Specifications will soon be updated to align with the upcoming GLEC Framework Version 3.3.

1.2. PACT Technical Interoperability

iLEAP is interoperable with the PACT Data Exchange Protocol and its PCF data model (§ 7.11 PACT Integration).

With v1.1.0, the iLEAP standalone protocol (§ 7 HTTP REST API) is introduced as the primary protocol for data exchange, while support for the PACT Data Exchange Protocol is maintained for backward compatibility and fallback purposes.

Note: The PACT Data Exchange Protocol integration is scheduled for removal with the v2.0.0 release of the iLEAP Technical Specifications.

Note: The editors of this specification strive to assert semantical interoperability with the PACT Technical Specifications with future releases.

1.3. Out of Scope

Note: Non-normative section

These specifications do 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. The technical specifications' normative foundations are the [GLEC] Framework and [ISO14083].

2. Black Carbon Methodological and Accounting principles.

3. Technical details on capturing necessary data for primary data-based calculations approaches, such as data collection with or through telematics systems, TMS, etc.

4. Contracts or legal aspect of data exchange between parties, including third party entities offering digital services or tools.

5. Auditing and verification of actual emissions calculations beyond systems-level accreditation. Verification-related properties are expected to be included in future versions of these technical specifications.

6. Market-based accounting approaches (e.g., based on contractual instruments such as energy attribute certificates), project accounting, and book and claim approaches. Emissions from electricity exchanged under these specifications are quantified using the location-based approach as specified in [ISO14083], Annex J.3 (see § 6.7.8.1 Emission Factors of Electricity). Market-based figures, which [ISO14083], Annex J.3 permits only in addition to location-based figures and to be reported separately, are expected to be included in future versions of these technical specifications, as are book and claim-related approaches.

7. Variables for detailed GHG emissions modeling, as described in [ISO14083], Section 13.4.3 and Annex M. The current data model focuses on enabling primary data collection. Basic use of modeled and default data is supported, but detailed parameters remain excluded.

8. Modes of transport "cable car" and "pipeline".

9. The exchange of refrigerant-specific data, such as refrigerant type, leaked quantity, and global warming potential. Leakage of refrigerants used by vehicles or hubs is part of the system boundary of [ISO14083] (Section 5.2.2; see also Section 9.2, Annex H.1.2 and, for transport operations, Annex I); emission values exchanged under these specifications follow it, including the requirement to state any omission (Section 5.2.3). The extent to which emission values include refrigerant leakage is stated with refrigerantLeakageCoverage and refrigerantLeakageCoverage. Data model support for refrigerant data is expected in future versions of these technical specifications.

10. Reporting with per-modality transparency as defined in Section 13.3 of [ISO14083]. The key difference between this approach and iLEAP is that the former also allows for a) aggregating over more than 1 shipment, and b) disclosing emissions per modality. The iLEAP Technical Specifications operate on a per-shipment and per-TCE basis. However, transparency at this level is implicitly assumed by ISO14083 Chapter 13.3 (when aggregating over multiple shipments). Comprehensive reporting according to [ISO14083] Chapter 13.3 is expected to be included in future versions of these technical specifications.

1.4. 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://specs.ileap.global/.

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://specs.ileap.global/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://specs.ileap.global/TR/2024/ileap-extension-20240605/.

1.5. Acknowledgements

The iLEAP Technical Specifications are the result of a collaborative effort by numerous iLEAP project participants.

The authors would like to thank the many individuals and organizations for their contributions and their commitment to iLEAP in the various phases of its development.

2. Definitions and Conventions

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

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.

Consignment id

A digital identifier which uniquely identifies a Consignment relative to the Host system and to the data recipient.

Default Value

Secondary data value taken from a published source, e.g. a default value of the [GLEC] Framework. A default value does not necessarily correspond to the parameters of the transport operation or hub operation being evaluated. See [ISO14083], Section 3.3.4.2 and Annex Q.

Distance

See Transport Distance and Actual Distance

Great Circle Distance (GCD)

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

Location where freight is transferred from one vehicle or transport mode to another before, after, or between the elements of a transport chain, e.g. cross-docking sites, distribution centres, warehouses, rail/road terminals, and terminals at seaports, inland ports, and airports. See [ISO14083], Section 3.1.8 and Annex H.

Hub Activity

Parameter that quantifies the throughput of a hub. For freight, hub activity is the quantity of freight leaving the hub (outbound), expressed in the unit given by hubActivityUnit. Hub activity is not transport activity (see § 2.4 Transport Activity and Hub Activity). See [ISO14083], Sections 3.1.9, 5.5.2 and 9.4.1, and the [GLEC] Framework.

Hub Equipment

Equipment and facilities used at a hub to transfer freight, e.g. handling, on-site transportation, and transhipment equipment, including heating and temperature control. See [ISO14083], Sections 3.1.10 and 5.2.2.

Hub Operation

Operation to transfer freight through a hub. See [ISO14083], Section 3.1.11.

Hub Operation Category (HOC)

Represents a group of hub operations sharing similar characteristics. See [ISO14083], Section 3.1.12, and the [GLEC] Framework.

Hub Operator

Refers to the entity that carries out hub operations involving freight. See [ISO14083], Section 3.1.13.

Hub Service

Service provided within a hub TCE. See [ISO14083], Section 3.1.14.

Hub TCE

A TCE within which the freight transits through a single hub, i.e. a TCE taking place within a hub operation. A hub TCE is represented by a TCE that references a HOC through hocId (see § 6.2.2 Hub TCEs). See [ISO14083], Clause 11.

Modeled Data

Secondary data established by use of a model that takes into account primary data and/or GHG emission-relevant parameters of a transport operation or hub operation, such as vehicle size, load factor, or fuel type. See [ISO14083], Section 3.3.4.1.

Primary Data

Quantified value of a process or an activity obtained from a direct measurement or a calculation based on direct measurements. Primary data can include GHG emission factors and/or GHG activity data. See [ISO14083], Section 3.3.3, and the [GLEC] Framework.

Secondary Data

Data that do not meet the requirements for primary data. Secondary data are either modeled data or default values. See [ISO14083], Section 3.3.4, and the [GLEC] Framework.

Shipment

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

ShipmentFootprint

See § 6.1 ShipmentFootprint for the definition.

Shipment id

A digital identifier which uniquely identifies a Shipment relative to the Host system and to the Data recipient.

Shipper

Refers to the party sending goods for transport; e.g. buying transport services from Transport Service Organizers or Transport Operators. See [GLEC] Framework.

Shortest Feasible Distance (SFD)

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

Throughput

The quantity of freight that is handled, sorted, cross-docked, or transferred at a hub, within or between transport modes. See [ISO14083], Section 3.1.21.

Transport Activity

Transport activity for each consignment is calculated by multiplying the consignment’s mass by the TCE distance. It is measured with unit tonne-kilometer. See [ISO14083] Section 3.1.24 and the [GLEC] Framework. It does not include hub activity (see § 2.4 Transport Activity and Hub Activity).

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)

Section of a transport chain within which the freight is carried by a single vehicle or transits through a single hub. A TCE therefore relates either to transport activity or to hub activity. See [ISO14083], Section 3.1.26, and the [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

Operation of a vehicle to transport freight. See [ISO14083], Section 3.1.28.

Transport Operation Category (TOC)

Represents a group of transport operations sharing similar characteristics. See [ISO14083], Section 3.1.29, and the [GLEC] Framework.

Transport Operator

Refers to the entity that carries out transport operations involving the carriage of freight. See [ISO14083], Section 3.1.30.

Transport Service

Service provided to a Transport Service User for the transport of freight from an origin to a destination. A transport service can comprise several Transport Chain Elements and require both transport operations and hub operations. See [ISO14083], Section 3.1.31.

Transport Service Organizer

Refers to the party providing transport services, where some of the operations are subcontracted 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.

Tool Provider

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

2.2. Auxiliary Definitions

Needs revision

Access Token

Credential to provide access to protected resources, as defined in [rfc6749] Section 1.4 (see also Section 5.1 and Appendix A.12).

Data Owner

The party in the logistics value chain that owns the data being exchanged.

Data Recipient

The party in the logistics value chain requesting and/or receiving the data being exchanged.

Host System

A host system serves the needs of a single or multiple data owner. Additionally, it can also serve the needs of a data recipient, by calling the HTTP REST API defined in § 7 HTTP REST API. A host system implements support for the data transactions defined in § 4 Data Transactions.

iLEAP standalone protocol

The iLEAP standalone API and data model, introduced in v1.1.0 of these technical specifications, which enables the exchange of logistics emissions. See § 7 HTTP REST API for details.

OpenId Provider Configuration Document

An OpenId Provider Configuration Document in accordance with [OPENID-CONNECT] section 4.

PCF

Product Carbon Footprint. See PACT Technical Specifications for further details.

Smart Freight Centre (SFC)

The Smart Freight Centre Organization.

2.3. Conventions

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in (BCP14)[https://www.rfc-editor.org/info/bcp14] [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.

2.4. Transport Activity and Hub Activity

Transport Activity and Hub Activity are distinct quantities. They MUST NOT be summed, converted into each other, or used interchangeably.

1. Transport Activity quantifies the transport of freight by vehicles. Its unit is tonne-kilometer unless stated otherwise (see transportActivityUnit).

2. Hub Activity quantifies the throughput of a hub. Its unit is the one given in hubActivityUnit, e.g. tonnes leaving the hub.

3. The transport activity of a transport chain or of a set of shipments is the sum of the transport activity of its TCEs representing transport operations only. Hub TCEs contribute GHG emissions, but no transport activity (see § 6.2.2 Hub TCEs and [ISO14083], Sections 12.1.2 and 12.2.3).

4. GHG emissions of hub operations result from hub equipment operation and hub equipment energy provision (see [ISO14083], Sections 3.2.8.1 and 3.2.8.2), not from vehicle operation.

2.5. Forward Compatibility

To allow these specifications to evolve in minor versions (see § 1.4 Document Statuses):

1. A data recipient MUST ignore properties not defined in the version of these specifications it implements and MUST NOT reject a data object for this reason alone.

2. New enumeration values MAY be added in minor versions. Enumeration values are only removed or renamed in major versions; they are deprecated in a minor version first.

3. Host systems MUST only use enumeration values defined in these specifications.

4. A data recipient receiving an unknown enumeration value MUST NOT reject the response or other data objects contained in it, MUST NOT map the value to a known value, SHOULD treat the affected property as not interpretable, and SHOULD inform its user accordingly.

These rules apply to all enumerations of these specifications, including those defined inline in property descriptions.

3. Business Cases

Note: Non-normative section

These specifications shall serve the general need of businesses for logistics GHG emissions accounting and reporting, conforming to the [GLEC] Framework and [ISO14083].

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

To achieve this objective, the specifications are 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 interested in accessing accurate emission and emission intensity values based on actual measurements ("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 or HOC 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 its 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 or HOC Data Exchange enable this business case.

3.3. Emissions Calculation from Transport Activity Data

Consider the two following scenarios:

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

• A stakeholder collects primary data related to transport activity but is not in the business of calculating emissions data.

In each case, the party can collect Transport Activity Data, that is, data related to a single shipment including mass, distance, and energy carriers used, but excluding emissions data.

After collecting Transport Activity Data, the party can calculate TOC and HOC level data from its Transport Activity Data, either inhouse or by contracting a third party (such as a Tool Provider).

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

iLEAP generally simplifies data collection efforts for the parties involved in this business case. For instance, each party needs to collect the activity data only once. This data can be then made available to multiple parties 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. Aggregated Emissions Reporting

Consider the following scenarios:

1. A Transport Service Organizer or a Transport Service User requests emissions data from a Transport Operator or a Transport Service Organizer which decide to share an aggregated report instead of TCE-level data, due to privacy or competition concerns.

2. A Transport Service User or a Transport Service Organizer requests emissions reports from a Transport Operator or a Transport Service Organizer, aggregated per transport mode or over one or more shipments.

3. A Transport Service User, a Transport Service Organizer, or a Transport Operator needs to report logistics emissions data to a public body for regulatory purposes.

Data Transaction 4 (§ 4.4 Data Transaction 4: Aggregated Emissions Data Exchange) enables this business case, while Data Transactions 1, 2, and 3 support the collection of relevant input data for report calculations (see § 4.1 Data Transaction 1: TCE Data Exchange, § 4.2 Data Transaction 2: TOC or HOC Data Exchange, § 4.3 Data Transaction 3: Transport Activity Data Exchange).

3.5. 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.11.1 ShipmentFootprint).

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

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.

4. Data Transactions

Note: Non-normative section

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

It facilitates interoperability between different parties by explaining the context and their intentions.

Each transaction enables interoperability between host systems by exchanging data in the format defined by the iLEAP data model (§ 6 Data Model) through the protocols defined in § 7 HTTP REST API and the PACT Data Exchange Protocol (§ 7.11 PACT Integration).

The following diagram shows how data transactions 1, 2, and 3 are related:

A new diagram reflecting Data Transaction 4 is needed.

Note: A Tool Provider can assume various roles on behalf of the Transport Service User, Transport Service Organizer, or Transport Operator. 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 emissions from Transport Chain Elements from a Transport Operator or a Transport Service Organizer for a single shipment.

To execute this transaction, the Transport Operator or the Transport Service Organizer MUST

1. calculate the emissions of 1 or more Transport Chain Elements in accordance with the [GLEC] Framework and [ISO14083], and then

2. make the resulting ShipmentFootprint available to the Transport Service User through the (recommended) iLEAP standalone protocol (§ 7.6 Action ShipmentFootprintData) and through the (deprecated) PACT Data Exchange Protocol (§ 7.11.1 ShipmentFootprint).

The Transport Service User CAN then derive emissions using the shipment id, by

1. collecting the TCEs from the ShipmentFootprints of all the Transport Operators and the Transport Service Organizers involved in 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 or HOC Data Exchange

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

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

To execute this transaction, first the Transport Operator or Transport Service Organizer MUST

1. calculate 1 or more TOC or HOC emission profiles in accordance with the [GLEC] Framework and [ISO14083], and then

2. make the resulting TOCs or HOCs available through the iLEAP standalone protocol (§ 7.7 Action TOCData and § 7.8 Action HOCData) and through the PACT Data Exchange Protocol (see § 7.11 PACT Integration).

   Note: Details on the definition and calculation of TOCs and HOCs are specified in [ISO14083] and guidance is provided in the [GLEC] Framework.

Then, a Transport Service Organizer or a Transport Service User can retrieve the TOCs or HOCs using the (recommended) iLEAP standalone protocol (§ 7.7 Action TOCData and § 7.8 Action HOCData) or the (deprecated) PACT Data Exchange Protocol (§ 7.11.1 ShipmentFootprint). (see § 7.11 PACT Integration for details).

4.3. Data Transaction 3: Transport Activity Data Exchange

Note: This data transaction is considered necessary by logistics parties, especially SMEs, lacking the capabilities to make emissions data available. Yet, standardizing the exchange of activity data can enable the use of primary data and facilitate the calculation of emissions data.

This data transaction enables a Transport Service Organizer or a Transport Service User to receive Transport Activity Data from a Transport Operator, as described in Business Case 3 (§ 3.3 Emissions Calculation from Transport Activity Data).

Using Data Transaction 3 is recommended for the following cases:

1. emissions data (at the level of ShipmentFootprints, TOCs, or HOCs) is not (yet) available, or

2. the data flow is used to calculate emissions data, e.g. by a Tool Provider on behalf of a Transport Service Organizer or a Transport Operator.

To enable this transaction, the data owner (a Transport Operator or Transport Service Organizer) must

1. collect Transport Activity Data scoped by a single consignment, and then

2. make the resulting TAD available through § 7.9 Action TransportActivityData.

Then, the Transport Service Organizer or Transport Service User can retrieve the TADs through the ileap standalone protocol using § 7.9 Action TransportActivityData).

4.4. Data Transaction 4: Aggregated Emissions Data Exchange

This data transaction enables a Transport Service Organizer, a Transport Service User, or Public Authorities to receive emissions data related to one or more shipments from a Transport Operator, a Transport Service Organizer, or a Transport Service User, without disclosing TCE-level data. The data exchanged through this transaction MAY disclose emissions aggregated per transport mode and an aggregation of all hub TCEs (as requested in [ISO14083] Chapter 13.3.2, see information"j)").

To execute this transaction, a Transport Operator or Transport Service Organizer MUST:

1. calculate all TCEs' emissions corresponding to the shipment(s) in accordance with the GLEC Framework and ISO 14083,

2. generate the AggregatedReport from the collected TCEs, and

3. make the AggregatedReport available to a Transport Service Organizer, Transport Service User, or Public Body, through an iLEAP Conformant API.

Aggregated Emissions Data is less granular than TCE-level data. Therefore, once Aggregated Emissions Data is exchanged, it is no longer possible to derive more granular (i.e., TCE-level) data from it, thereby affecting the all data exchanges downstream. Please consider this when opting for this data transaction.

4.4.1. Examples

Note: The following are are usecase examples, where a Transport Service Organizer and a Telematics Provider send data to a GHG Calculation Tool with the goal of having the emissions calculated and aggregated, in order to share less granular data with a Transport Service User.

5. End-to-End Example

Note: Non-normative section

Missing example with Data Transaction 4.

5.1. Example Case with 2 Carriers and 1 LSP

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

Transport Service User Shipper

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

Using § 4.1 Data Transaction 1: TCE Data Exchange and § 4.2 Data Transaction 2: TOC or HOC Data Exchange, Shipper pulls TCE and TOC data from LSP and calculates the Transport Chain (TC) emissions.

Since no further Transport Service Organizer or Transport Service Operator is involved, no additional calculation is needed.

Transport Service Organizer LSP

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

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

Using § 4.1 Data Transaction 1: TCE Data Exchange and § 4.2 Data Transaction 2: TOC or HOC Data Exchange, LSP pulls TCE and TOC data from Transport Operator Carrier A.

Using § 4.3 Data Transaction 3: Transport Activity Data Exchange, LSP pulls Transport Activity Data from Carrier B, which it uses to calculate emissions data for the shipment.

LSP then calculates the consolidated ShipmentFootprint and provides it to Transport Service User Shipper.

Transport Operator Carrier A

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

This Operator has a host system which is capable of calculating TCE and TOC data.

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

Transport Operator Carrier B

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

This Transport Operator is capable of making TAD data available to the Transport Service Organizer LSP.

5.1.1. Data Collection by Transport Service Organizer LSP

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

Note: The call to /footprints can return several footprints, one for each shipment. By filtering, e.g. by shipment id, LSP can retrieve the TCEs for the shipment of interest. The use of this functionality is not included in the example below.

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

Consider having an example with the iLEAP standalone protocol instead, moving this to the examples section.

curl -X 'GET' \
'https://api.transport-operator-a.com/2/footprints' \
-H 'accept: application/json' \
-H 'Authorization: Bearer [access-token]'

{    "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://api.ileap.sine.dev/shipment-footprint.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"            }          ]        }      }    ]  }

LSP can further access the TOCs from Carrier A through the same endpoint (see § 4.2 Data Transaction 2: TOC or HOC Data Exchange and § 7.11.2 TOC).

5.1.2. Data Collection by LSP from Carrier A

To collect the TCE data related to the shipment, LSP performs the following HTTP call, yielding 2 TCEs in this hypothetical example.

Note: The highlighted lines show 2 TCEs which Carrier A has collected and calculated for LSP.

Consider having an example with the iLEAP standalone protocol instead, moving this to the examples section.

curl -X 'GET' \
'https://api.transport-organizer.com/2/footprints' \
-H 'accept: application/json' \
-H 'Authorization: Bearer [access-token]'

{    "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://api.ileap.sine.dev/shipment-footprint.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 upon ISO 14083 and the GLEC Framework. The purpose of the data model is to define the syntax and semantics with the goal of enabling the interoperable exchange of data between a data owner and a data recipient using the HTTP REST API (§ 7 HTTP REST API).

The data model is composed of six main data types organized into two categories.

The first category covers emissions data aligned with ISO 14083. At its foundation are the data types TCE, TOC, and HOC, corresponding to the ISO 14083 concepts of TCE, TOC, and HOC. Building on these, the data model defines two complementary approaches to emissions reporting in line with ISO 14083 reporting principles: ShipmentFootprint, which represents the footprint of an individual shipment across its transport chain, and AggregatedReport, which facilitates the exchange of aggregated emissions data, e.g. for reporting to public authorities and to avoid disclosing sensitive data.

The second category covers activity data. TAD (transport activity data, TAD) enables reporting in case of missing data or limited emissions calculation capabilities from e.g. Transport Operators.

ShipmentFootprints, TOCs, and HOCs can also be embedded as data extensions in the PACT Data Model ([PACTDX]) (see [DATA-MODEL-EXTENSIONS] and § 7.11 PACT Integration) in a ProductFootprint.

6.1. ShipmentFootprint

The ShipmentFootprint data type enables reporting at the level of transport or hub services for a single shipment, aligned with ISO 14083 (Chapter 13.3) and the GLEC Framework.

A ShipmentFootprint covers one or more Transport Chain Elements and their respective emissions, encoded as TCEs. By collecting one or more ShipmentFootprints, a Transport Chain (TC) and its emissions data can be assembled together ultimately enabling the calculation of the shipment’s logistics emissions.

Note: A ShipmentFootprint CAN include TCEs that the data owner collected from other parties.

6.1.1. Data Attributes

A ShipmentFootprint has the following properties:

Consider adding declaredUnit

6.2. Transport Chain Element (TCE)

The TCE data type models information related to a single Transport Chain Element and its emissions data.

The emissions data represented in a TCE can be obtained from direct measurement (see Primary Data) or from secondary data (modeled data or default values).

TCEs are typically calculated by Transport Operators and Transport Service Organizers. They are made available to Transport Service Users through the ShipmentFootprint data type (see § 6.1 ShipmentFootprint), through the RECOMMENDED iLEAP standalone protocol (see § 7.6 Action ShipmentFootprintData) and through the (deprecated) PACT Data Exchange Protocol (see § 7.11 PACT Integration).

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 comprising 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"].

6.2.2. Hub TCEs

A TCE that references a HOC through hocId represents a hub TCE. For hub TCEs, the following applies (see [ISO14083], Clause 11, and § 2.4 Transport Activity and Hub Activity):

1. Hub TCEs are associated with zero distance (see the [GLEC] Framework). Each defined property of distance MUST be 0.

2. transportActivity MUST be 0, as hub TCEs contribute no transport activity.

3. The hub activity of a hub TCE is quantified in the hubActivityUnit of the referenced HOC (see [ISO14083], Section 11.2). If the unit is tonnes, the hub activity is the value of mass divided by 1000. If the unit is TEU, the hub activity is the number of TEUs; in this case, packagingOrTrEqType SHOULD be Container-TEU and packagingOrTrEqAmount SHOULD be defined.

4. co2eWTW and co2eTTW are calculated by multiplying the hub activity of the TCE with co2eIntensityWTW and co2eIntensityTTW of the referenced HOC, respectively (see [ISO14083], Section 11.4). They cover hub equipment operation and hub equipment energy provision, not vehicle operation.

5. If temperatureControl is defined and the referenced HOC defines temperatureSpecificIntensities with an element for the same temperature condition, the GHG emission intensities of this element MUST be used instead (see [ISO14083], Section 11.5). An element with value refrigerated applies to a TCE with value chilled or frozen if the HOC defines no element for that value.

See § 6.4.3 GHG Emission Intensity Example for an example of a hub TCE.

6.2.3. 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.

{
  "packagingOrTrEqType": "Container-TEU",
  "packagingOrTrEqAmount": "2"
}

{
  "packagingOrTrEqType": "Container-TEU",
  "packagingOrTrEqAmount": "2.25"
}

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 SHOULD then make the TOC available through the RECOMMENDED iLEAP standalone protocol (§ 7.6 Action ShipmentFootprintData) and through the (deprecated) PACT Data Exchange Protocol (§ 7.11.1 ShipmentFootprint).

Transport Operation Category data can be obtained from direct measurement (see Primary Data) or from secondary data, i.e. modeled data or default values.

6.3.1. Data Attributes

The Data Type TOC has the following properties:

Consider adding declaredUnit

[
  {
    "energyCarrier": "Diesel",
    "relativeShare": "0.30",
    "emissionFactorWTW": "2.67",
    "emissionFactorTTW": "2.80"

  },
  {
    "energyCarrier": "Electric",
    "relativeShare": "0.70",
    "feedstocks": [
      {
        "feedstock": "Renewable electricity",
        "feedstockPercentage": "1"
      }
    ]
    "emissionFactorWTW": "0.05",
    "emissionFactorTTW": "0.05"
  }
]

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.

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

6.4.1. System Boundary

The GHG emissions represented in a HOC MUST follow the system boundary of [ISO14083] (Section 5.2 and Annex H.1). In particular:

1. The GHG emissions of all hub operations of the HOC that consume energy or cause refrigerant leakage are included (see [ISO14083], Annex H.1.2, and refrigerantLeakageCoverage).

2. The GHG emissions of inbound and outbound transport operations, including grid electricity used to charge vehicles leaving the hub and refills of refrigerants into refrigerated containers or vehicles, are not included. They are accounted for in the respective TCEs (see [ISO14083], Annex H.1.3).

3. GHG emissions from energy used by vehicles or vessels while temporarily at the hub (e.g. ground power units at airports or shore power in ports) are allocated to the transport operation by default in [ISO14083] (Annex H.1.3), while the GLEC Framework v3.2 includes shore power in the hub emissions unless otherwise agreed with the shipping company. If the hub supplies such energy, the data owner MUST state in comment whether the related GHG emissions are included in the HOC.

6.4.2. Data Attributes

The Data Type HOC has the following properties:

Consider adding declaredUnit

[
  {
    "energyCarrier": "Diesel",
    "relativeShare": "0.75",
    "emissionFactorWTW": "2.67",
    "emissionFactorTTW": "2.80"

  },
  {
    "energyCarrier": "Electric",
    "relativeShare": "0.25",
    "feedstocks": [
      {
        "feedstock": "Grid",
        "feedstockPercentage": "1"
      }
    ]
    "emissionFactorWTW": "0.35",
    "emissionFactorTTW": "0.35"
  }
]

6.4.3. GHG Emission Intensity Example

{
  "hocId": "container-terminal-de",
  "hubType": "IntermodalTerminal",
  "temperatureControl": "mixed",
  "co2eIntensityWTW": "0.2333",
  "co2eIntensityTTW": "0.0668",
  "temperatureSpecificIntensities": [
    {
      "temperatureControl": "ambient",
      "co2eIntensityWTW": "0.2178",
      "co2eIntensityTTW": "0.0668"
    },
    {
      "temperatureControl": "refrigerated",
      "co2eIntensityWTW": "1.5378",
      "co2eIntensityTTW": "0.0668"
    }
  ],
  "hubActivityUnit": "tonnes"
}

{
  "tceId": "tce-hub-1",
  "hocId": "container-terminal-de",
  "shipmentId": "shipment-1",
  "mass": "87000",
  "temperatureControl": "ambient",
  "distance": {
    "actual": "0"
  },
  "transportActivity": "0",
  "co2eWTW": "18.95",
  "co2eTTW": "5.81"
}

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 feedstock mix). In this case, the values CAN be calculated from the actual data of more than one consignment (“representative” or “average data”).

Note: 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

The table below lists the properties defined for the TAD data type.

When exchanging it through the Action TransportActivityData, it MUST be encoded as a JSON object.

6.6. Aggregated Report (AR)

The AggregatedReport data type contains aggregated emissions data for one or more shipments, disclosing total emissions, without disclosing TCE-level data. An AggregatedReport MAY disclose emissions aggregated per transport mode and an aggregation of all hub TCEs (see ISO 14083 Chapter 13.3).

6.6.1. Data Attributes

6.7. Additional Utility Data Types

6.7.1. Data Type GLECDistance

Data type GLECDistance represents a distance in kilometers 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 MUST be defined:

6.7.2. Data Type Location

Properties of data type Location:

6.7.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: TransportMode is used by mode, mode, inboundTransportModes, outboundTransportModes (and their deprecated singular forms), and transportMode. The transport modes cable car and pipeline are out of scope (see § 1.3 Out of Scope).

6.7.4. Data Type HubType

The Data Type HubType is an enumeration of the main hub types as defined in the [GLEC] Framework and aligned with the five hub types of the GLEC Framework v3.2 (Module 2).

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). Hub type 1 of the GLEC Framework v3.2.

StorageAndTransshipment

Refers to hubs where both transshipment and warehousing are relevant services. Hub type 2 of the GLEC Framework v3.2.

Warehouse

Refers to hubs where warehousing is the main service (>80% of goods handled). Hub type 3 of the GLEC Framework v3.2.

LiquidBulkTerminal

Refers to terminals equipped to handle cargo in liquid and gaseous forms. Hub type 4 of the GLEC Framework v3.2.

IntermodalTerminal

Refers to intermodal terminals at seaports or inland ports (hinterland). Hub type 5 of the GLEC Framework v3.2, which replaces the maritime container terminals of the GLEC Framework v3.0.

MaritimeContainerTerminal

Refers to hubs where maritime containers are handled. Hub type 5 of the GLEC Framework v3.0.

The GLEC Framework v3.2 is not yet a normative reference of these specifications (see § 1.1 Methodological Interoperability). The deprecation of MaritimeContainerTerminal in favour of IntermodalTerminal will be decided in a future revision.

Note: This enumeration may be extended in minor versions (see § 2.5 Forward Compatibility).

6.7.5. Data Type TemperatureControl

The Data Type TemperatureControl is an enumeration of the temperature conditions of freight (see [ISO14083], Sections 5.6.4 and 9.5.3, and Annex H.2). It is used by temperatureControl, temperatureControl, temperatureSpecificIntensities, and temperatureControl.

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

ambient

Freight that is not temperature-controlled.

chilled

Freight that is cooled to temperatures above freezing.

frozen

Freight that is kept frozen.

heated

Freight that is heated above ambient temperature.

refrigerated

Freight that is cooled, without a distinction between chilled and frozen. The use of this value is discouraged when the distinction is known.

mixed

Freight of two or more of the temperature conditions above, with a single average GHG emission intensity. SHOULD NOT be used when temperature-specific GHG emission intensities can be provided (see [ISO14083], Section 9.5.3, and temperatureSpecificIntensities).

Note: These specifications do not define temperature ranges for these values. Data owners SHOULD state the temperature ranges used in the comment property of the respective data type.

Note: This enumeration may be extended in minor versions (see § 2.5 Forward Compatibility).

6.7.6. Data Type RefrigerantLeakageCoverage

The Data Type RefrigerantLeakageCoverage is an enumeration of the extent to which GHG emission intensities include the GHG emissions from leakage of refrigerants (see [ISO14083], Sections 5.2.2 and 5.2.3). It is used by refrigerantLeakageCoverage and refrigerantLeakageCoverage.

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

Included

The GHG emissions from leakage of all refrigerants used are included.

PartiallyIncluded

The GHG emissions from leakage of some refrigerants or of some equipment are included, others are omitted. The omitted sources and the reasons for their omission MUST be stated in the comment property of the respective data type (see [ISO14083], Section 5.2.3).

Omitted

The GHG emissions from refrigerant leakage are omitted. The reasons for the omission MUST be stated in the comment property of the respective data type (see [ISO14083], Section 5.2.3).

NotApplicable

No refrigerants are used within the scope of the respective property.

Note: This enumeration may be extended in minor versions (see § 2.5 Forward Compatibility).

6.7.7. 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.

"10"

"-0.123"

6.7.8. 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:

6.7.8.1. Emission Factors of Electricity

For an EnergyCarrier with energyCarrier Electric, the following applies:

1. emissionFactorWTW and emissionFactorTTW MUST be determined using the location-based approach of [ISO14083], Annex J.3, i.e. with the GHG emission factor that best characterizes the pertinent grid: a dedicated transmission line, or the local, regional, or national grid average.

2. emissionFactorWTW MUST include all relevant GHG emissions associated with the generation of electricity, including transmission and distribution losses and other life cycle processes (see [ISO14083], Annex J.3). Emission factors conveyed by contractual instruments (e.g. energy attribute certificates) MUST NOT be used.

3. emissionFactorMethod SHOULD be set to LocationBased.

Note: Market-based approaches are out of scope (see § 1.3 Out of Scope). [ISO14083], Annex J.3, permits them only in addition to the location-based approach, subject to quality criteria for contractual instruments, and requires their separate reporting.

6.7.9. Data Type EnergyCarrierType

Data type EnergyCarrierType represents the substance or phenomenon used to generate mechanical movement or heat and to generate chemical or physical processes as per the [GLEC] Framework (see also [ISO14083], Section 3.2.2).

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

Note: This enumeration may be extended in minor versions (see § 2.5 Forward Compatibility).

Diesel

Refers to diesel

Biodiesel

Refers to biodiesel (fatty acid methyl ester, FAME)

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

Natural gas

Refers to natural gas supplied via the gas grid and combusted in stationary equipment, e.g. for heating. For vehicles, CNG or LNG applies. This value MUST only be used for HOCs and for ModeSpecificReports relating to hub operations.

Heat

Refers to purchased heat, including district heating and steam. Heat generated on site from another energy carrier (e.g. natural gas) MUST be represented by that energy carrier instead. The GHG emissions from generating the purchased heat are energy provision GHG emissions (see [ISO14083], Section 3.2.8.1); emissionFactorTTW is therefore 0. This value MUST only be used for HOCs and for ModeSpecificReports relating to hub operations.

The encoding of blends (e.g. diesel blended with biodiesel) as one or several EnergyCarriers will be specified in a future revision.

6.7.10. 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:

6.7.11. 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:

Note: This enumeration may be extended in minor versions (see § 2.5 Forward Compatibility).

Box

Refers to boxes

Pallet

Refers to pallets

Container-TEU

Refers to containers as the PackagingOrTrEqAmount is in TEU (Twenty-foot Equivalent Unit).

Container-FEU

Refers to containers as the PackagingOrTrEqAmount is in FEU (Forty-foot Equivalent Unit).

Container

Refers to containers where the size is unknown. PackagingOrTrEqAmount will be the number of container.

SwapBody

Refers to swap bodies. PackagingOrTrEqAmount is the number of swap bodies.

Trailer

Refers to trailers. PackagingOrTrEqAmount is the number of trailers.

Note: The use of value Container is discouraged, as it does not provide any information about the container equivalent unit.

6.7.12. Data Type ModeSpecificReport

7. HTTP REST API

7.1. Introduction

The iLEAP Technical Specifications define two REST API families:

iLEAP standalone API

The standalone API enables the exchange of ShipmentFootprint, TOC, HOC, Transport Activity Data, and Aggregated Report data.

The standalone API consists of the following REQUIRED actions:

1. § 7.4 Action Authenticate and the authentication flow § 7.3 Authentication

2. § 7.6 Action ShipmentFootprintData for the exchange of ShipmentFootprints

3. § 7.7 Action TOCData for the exchange of TOCs

4. § 7.8 Action HOCData for the exchange of HOCs

5. § 7.9 Action TransportActivityData for the exchange of TAD

6. § 7.10 Action AggregatedEmissionsData for the exchange of Aggregated Reports

Except for Action Authenticate, all actions share characteristics regarding access control, filtering, and pagination of results, as well as the request and response syntax.

A host system MUST implement the iLEAP standalone API which is now the preferred option for data exchange.

Note: The iLEAP standalone API is introduced in v1.1.0. It is RECOMENDED for data recipients.

PACT-based API

The PACT-based API also enables the exchange of ShipmentFootprint, TOC, and HOC data, yet is based on the [PACTDX] Protocol (see § 7.11 PACT Integration).

The PACT-based API is enabled through a mapping from the iLEAP Data model to the PACT PCF data model (see § 7.11 PACT Integration). The exchange of mapped data through the PACT-based API is done through the actions defined in [PACTDX] chapters 7.6 and 7.7, plus the authentication flow defined in [PACTDX] chapter 6.3.

Since April 1 2026, the v2 family of the PACT Technical Specifications, including [PACTDX], is sunset. Consequently, the PACT-based API approach SHOULD only be used for backward compatibility reasons.

We recommend new implementations to use the iLEAP standalone API by default. Specifically, we encourage data recipients to pull data through the new endpoints. Accordingly, data owners are encouraged to prioritize the implementation of the new endpoints, which is required for conformance with iLEAP v1.1.0.

7.2. Definitions and Parameters

The following defintions and parameters are used throughout this chapter:

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 7.3 Authentication Flow or § 7.3 Authentication.

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 &.

The $name of a filter pair CAN use dot notation to reference nested or embedded properties within a data type. When dot notation is used:

1. Each segment of the path (separated by .) represents a property name;

2. For properties that are arrays (e.g., tces), the filter matches if any element in the array satisfies the filter condition;

3. Host systems CAN support any depth of nesting.

To filter ShipmentFootprints by the origin location of their embedded TCEs:

tces.origin.city=Rotterdam

This returns all ShipmentFootprints containing at least one TCE whose origin has a matching city.

For all properties with timestamp or numerical values, filtering SHOULD support the possibility of specifying a range of values, implemented as follows:

1. The $name of the filter pair is the name of the timestamp or numerical property (e.g., createdAt).

2. The $name should be followed by either the operator =gte. (greater than or equal) or =lt. (less than).

3. The $value of the filter pair is either numerical (integer or Decimal) or a date and time string conforming to ISO 8601 with timezone UTC.

4. To filter within the range defined by a start value and an end value, two filter pairs need to be concatenated with &.

To filter ShipmentFootprints by the creation time between 2025-01-01 (inclusive) and 2026-01-01 (exclusive):

createdAt=gte.2025-01-01T00:00:00Z&createdAt=lt.2026-01-01T00:00:00Z

This returns all ShipmentFootprints created on or after 2025-01-01T00:00:00Z and before 2026-01-01T00:00:00Z.

Limit

Limit is an OPTIONAL request parameter. If defined,

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

2. the value MUST be a positive integer.

StatusCode

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 PACT Technical Specifications.

StatusText

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

ResponseBody

The HTTP response body upon a successful request. The body MUST be a JSON object with property data with value the list of the respective data (ShipmentFootprint for Action ShipmentFootprintData, TOC for Action TOC, etc. ). 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.5.3 Pagination.

AuthEndpoint

The endpoint to request an access token. See § 7.3 Authentication for further details on discovery and request syntax.

7.3. Authentication

Needs revision. In particular, we need to consider not demanding BasicAuth implementation with client credentials.

With the deprecation of PACT interoperability, iLEAP defines an authentication flow for the iLEAP standalone API. An access token obtained through either authentication method (PACT or iLEAP standalone API) MUST be valid for both PACT-based and iLEAP standalone API endpoints.

7.3.1. Authentication Flow

The iLEAP authentication flow consists of the following steps:

1. Token endpoint discovery, as specified in § 7.3.2 AuthEndpoint Discovery.

2. Authentication against the token endpoint, as specified in § 7.4 Action Authenticate.

Note: The iLEAP authentication flow follows the approach of [PACTDX], Section 7.3. This means that host systems implementing the PACT-based authentication flow are also conforming with the iLEAP authentication flow.

7.3.2. AuthEndpoint Discovery

A host system MAY use any endpoint for authentication, as long as they make it available through an OpenId Configuration Document. In order to discover the authentication endpoint, a data recipient MUST:

1. retrieve and validate the OpenId Provider Configuration Document of the host system (see [OPENID-CONNECT]) from the endpoint https://Hostname/Subpath/.well-known/openid-configuration;

2. use as AuthEndpoint the value of the token_endpoint property of the OpenId Provider Configuration Document.

If the host system does not provide a valid OpenId Configuration Document at the above endpoint or that the token_endpoint is not defined, the data recipient MUST use Hostname/Subpath/auth/token as the AuthEndpoint.

7.4. Action Authenticate

Request an access token using client credentials.

Host systems MUST implement this action in conformance with [rfc6749] Section 4.4 (OAuth2 Client Credentials).

Host systems MAY offer this action under any AuthEndpoint, discoverable as per § 7.3.2 AuthEndpoint Discovery. Accordingly, if no discovery method through an OpenId Configuration Document is implemented, the host system MUST offer this action under the endpoint Hostname/Subpath/auth/token.

7.4.1. Request Syntax

POST AuthEndpoint HTTP/1.1
accept: application/json
content-type: application/x-www-form-urlencoded
authorization: Basic BasicAuth
content-length: ContentLength

AuthBody

With Request parameters:

BasicAuth

See [rfc6749] Section 4.4.2

AuthBody

See [rfc6749] Section 4.4

7.4.1.1. Example

POST https://api.ileap.sine.dev/auth/token HTTP/1.1
accept: application/json
content-type: application/x-www-form-urlencoded
authorization: Basic Q2xpZW50SUQ6Q2xpZW50U2VjcmV0
content-length: 29
grant_type=client_credentials

Authentication flow identical to [PACTDX] (see Chapter 7.3).

7.4.2. Response Syntax

HTTP/1.1 AuthStatusCode OK
content-type: application/json
content-length: ContentLength

AuthResponseBody

With action-specific response parameters

AuthStatusCode

A HTTP response code conforming to [rfc6749] Section 4.4 and Section 5.

AuthResponseBody

A JSON Object conforming to either [rfc6749] Section 4.4 in case of successful authentication (containing an access token), or [rfc6749] Section 5.2 otherwise.

7.4.2.1. Example

HTTP/1.1 200 OK
content-type: application/json
content-length: 123

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600
}

7.5. Common HTTP Endpoint Behaviors

The specifications, behaviors, and considerations of this subchapter apply to all iLEAP standalone API actions except for § 7.4 Action Authenticate.

7.5.1. Access Control

A host system MUST implement an access control mechanism such that each API response contains only data intended for the requesting data recipient.

This applies to all iLEAP standalone API actions except for Action Authenticate.

The mechanism by which a host system determines which data is intended for a given data recipient is implementation-specific.

7.5.2. Filtering

Filtering CAN be requested by a data recipient by supplying a filter statement through 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 SHOULD 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 ResponseBody. For instance, a host system CAN return an HTTP error code 400 and a body with error 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.5.3. Pagination

Support for pagination is REQUIRED for host systems and data recipients.

Host systems MUST implement pagination server-side, such that

1. the host system MAY return less data than requested through the Limit request parameter;

2. the host system MUST return a Link header if there is additional data ready to be retrieved, such that

   1. the Link header conforms to [RFC8288];

   2. the value of the rel parameter is equal to next;

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

   4. the value of host of the target IRI is equal to the value of the host request header from the original 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 data from the same pagination link, upon successful authentication (see § 7.3 Authentication);

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

   3. MUST return a second Link header conforming with the previous description in case there is additional data available;

3. if a response contains a second pagination link, upon the data recipient 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, and SHOULD use a randomized exponential back-off strategy when retrying.

A data recipient CAN trigger pagination by supplying a Limit request parameter.

Irrespective of whether a Limit parameter is supplied, a data recipient SHOULD be able to process paginated responses, such that it is able

1. to process responses containing a pagination link, and

2. to call pagination links until no more pagination link are provided by the host system.

Data recipients SHOULD implement a strategy to deal with pagination links no longer working, including retrying (using appropriate back-off strategies etc.), or completely re-starting the data retrieval process from the beginning.

7.6. Action ShipmentFootprintData

Lists the data owner’s ShipmentFootprints with REQUIRED § 7.5.1 Access Control, REQUIRED § 7.5.3 Pagination, and OPTIONAL § 7.5.2 Filtering.

Note: To retrieve ShipmentFootprints based on embedded properties (regardless of the level of nesting), data recipients SHOULD use § 7.5.2 Filtering. See § 7.6.1.1 Examples for examples.

7.6.1. Request Syntax

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

7.6.1.1. Examples

To retrieve all ShipmentFootprints, the data recipient can call the endpoint as follows:

GET /v1/ileap/shipments HTTP/1.1

To retrieve the ShipmentFootprint for the shipment with shipmentId equal to 47389557, the data recipient can use the Filter parameter with filter pair shipmentId=$shipmentId as follows:

GET /v1/ileap/shipments?shipmentId=47389557 HTTP/1.1

To get ShipmentFootprints where at least one TCE has tceId equal to "40t-diesel-2023":

GET /v1/ileap/shipments?tces.tceId=40t-diesel-2023 HTTP/1.1

To filter for ShipmentFootprints where at least one TCE has the origin city equal to "Berlin":

GET /v1/ileap/shipments?tces.origin.city=berlin HTTP/1.1

7.6.2. Response Syntax

Non-paginated response:

HTTP/1.1 StatusCode StatusText
Content-Type: application/json
Content-Length: ContentLength

ResponseBody

Paginated response (§ 7.5.3 Pagination):

HTTP/1.1 StatusCode StatusText
Content-Type: application/json
Content-Length: ContentLength
Link: PaginationLink; rel="next"

ResponseBody

7.6.2.1. Examples

example needs revision

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 512
Link: <https://api.ileap.sine.dev/v1/ileap/shipments?limit=1&offset=1>; rel="next"

{
  "data": [
    {
      "shipmentId": "shipment-1",
      "companyName": "Acme Logistics",
      "referencePeriodStart": "2025-01-01T00:00:00Z",
      "referencePeriodEnd": "2026-01-01T00:00:00Z",
      "dataSchema": "https://api.ileap.sine.dev/shipment-footprint.json",
      "documentation": "https://sine-fdn.github.io/ileap-extension/",
      "productCategoryCpc": "83117",
      "mass": "1000",
      "tces": [
        {
          "tceId": "40t-diesel-2023",
          "shipentId": "shipment-1",
          "tocId": "40t-diesel-2023",
          "origin": {
            "country": "NL",
            "city": "Rotterdam"
          },
          "destination": {
            "country": "DE",
            "city": "Berlin"
          },
          "mass": "1000",
          "distance": {
            "actual": "800",
          },
          "transportActivity": "800000",
          "co2eWTW": "200",
          "co2eTTW": "150",
        }
      ]
    },
  ]
}

7.7. Action TOCData

Lists the data owner’s TOCs with REQUIRED § 7.5.1 Access Control, REQUIRED § 7.5.3 Pagination, and OPTIONAL § 7.5.2 Filtering.

Note: To retrieve TOCs based on embedded properties (regardless of the level of nesting), data recipients SHOULD use § 7.5.2 Filtering. See § 7.7.1.1 Examples for examples.

7.7.1. Request Syntax

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

7.7.1.1. Examples

GET /v1/ileap/tocs HTTP/1.1

To retrieve only one TOC, identified by tocId equal to "40t-diesel-2023":

GET /v1/ileap/tocs?tocId=40t-diesel-2023 HTTP/1.1

To retrieve TOCs where at least one of their energyCarriers has energyCarrier equal to "Diesel":

GET /v1/ileap/tocs?energyCarriers.energyCarrier=diesel HTTP/1.1

To filter for TOCs where the energyCarriers include EnergyCarriers with feedstock "Fossil"

GET /v1/ileap/tocs?energyCarriers.feedstocks.feedstock=fossil HTTP/1.1

7.7.2. Response Syntax

Non-paginated response:

HTTP/1.1 StatusCode StatusText
Content-Type: application/json
Content-Length: ContentLength

ResponseBody

Paginated response (§ 7.5.3 Pagination):

HTTP/1.1 StatusCode StatusText
Content-Type: application/json
Content-Length: ContentLength
Link: PaginationLink; rel="next"

ResponseBody

7.7.2.1. Examples

example needs revision

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 512
Link: <https://api.ileap.sine.dev/v1/ileap/tocs?limit=1&offset=1>; rel="next"

{
  "data": [
    {
      "tocId": "40t-diesel-2023",
      "companyName": "Acme Logistics",
      "referencePeriodStart": "2025-01-01T00:00:00Z",
      "referencePeriodEnd": "2026-01-01T00:00:00Z",
      "dataSchema": "https://api.ileap.sine.dev/shipment-footprint.json",
      "documentation": "https://sine-fdn.github.io/ileap-extension/",
      "productCategoryCpc": "83117",
      "mode": "Road",
      "energyCarriers": [
        {
          "energyCarrier": "Diesel",
          "relativeShare": "1.0",
        }
      ],
      "co2eIntensityWTW": "0.25",
      "co2eIntensityTTW": "0.2",
      "transportActivityUnit": "tkm"
    }
  ]
}

7.8. Action HOCData

Lists the data owner’s HOCs with REQUIRED § 7.5.1 Access Control, REQUIRED § 7.5.3 Pagination, and OPTIONAL § 7.5.2 Filtering.

Note: To retrieve HOCs based on embedded properties (regardless of the level of nesting), data recipients SHOULD use § 7.5.2 Filtering. See § 7.8.1.1 Examples for examples.

7.8.1. Request Syntax

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

7.8.1.1. Examples

To retrieve all HOCs:

GET /v1/ileap/hocs HTTP/1.1

To retrieve the HOC identified by hocId equal to "hub-rotterdam":

GET /v1/ileap/hocs?hocId=hub-rotterdam HTTP/1.1

To filter for HOCs where the energyCarriers include EnergyCarriers with feedstock "Fossil"

GET /v1/ileap/hocs?energyCarriers.feedstocks.feedstock=fossil HTTP/1.1

To filter for HOCs where the hubLocation has city equal to "Hamburg"

GET /v1/ileap/hocs?hubLocation.city=hamburg HTTP/1.1

7.8.2. Response Syntax

Non-paginated response:

HTTP/1.1 StatusCode StatusText
Content-Type: application/json
Content-Length: ContentLength

ResponseBody

Paginated response (§ 7.5.3 Pagination):

HTTP/1.1 StatusCode StatusText
Content-Type: application/json
Content-Length: ContentLength
Link: PaginationLink; rel="next"

ResponseBody

7.8.2.1. Examples

example needs revision

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 512
Link: <https://api.ileap.sine.dev/v1/ileap/hocs?limit=1&offset=1>; rel="next"

{
  "data": [
    {
      "hocId": "hub-rotterdam",
      "companyName": "Acme Logistics",
      "referencePeriodStart": "2025-01-01T00:00:00Z",
      "referencePeriodEnd": "2026-01-01T00:00:00Z",
      "dataSchema": "https://api.ileap.sine.dev/shipment-footprint.json",
      "documentation": "https://sine-fdn.github.io/ileap-extension/",
      "productCategoryCpc": "83117",
      "hubType": "Transshipment",
      "energyCarriers": [
        {
          "energyCarrier": "Electricity",
          "relativeShare": "1.0",
        }
      ],
      "co2eIntensityWTW": "0.5",
      "co2eIntensityTTW": "0.1",
      "hubActivityUnit": "tonnes"
    }
  ]
}

7.9. Action TransportActivityData

Lists the data owner’s Transport Activity Data with REQUIRED § 7.5.1 Access Control, REQUIRED § 7.5.3 Pagination, and OPTIONAL § 7.5.2 Filtering.

Note: To retrieve TransportActivityData based on embedded properties (regardless of the level of nesting), data recipients SHOULD use § 7.5.2 Filtering. See § 7.9.1.1 Examples for examples.

7.9.1. Request Syntax

As part of the deprecation of PACT interoperability, the version of the iLEAP native endpoints has been changed from /2/ileap/ to /v1/ileap/. However, to maintain backward compatibility with existing implementations, a host system MUST support both versions of the endpoint. Below, only the new version is documented.

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

7.9.1.1. Examples

To retrieve all TransportActivityData:

GET /v1/ileap/tad HTTP/1.1

To get the TransportActivity with activityId equal to "123456":

GET /v1/ileap/tad?activityId=123456 HTTP/1.1

To filter for TransportActivityData where the energyCarriers include EnergyCarriers with feedstock "Fossil":

GET /v1/ileap/tad?energyCarriers.feedstocks.feedstock=fossil HTTP/1.1

To retrieve TransportActivityData with Feedstock equal to "Fossil" and with packagingOrTrEqType equal to "Pallet":

GET /v1/ileap/tad?feedstock=Fossil&packagingOrTrEqType=pallet HTTP/1.1

7.9.2. Response Syntax

Non-paginated response:

HTTP/1.1 StatusCode StatusText
content-type: application/json
content-length: ContentLength

ResponseBody

Paginated response (§ 7.5.3 Pagination):

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

ResponseBody

7.9.2.1. Example

HTTP/1.1 200 OK
content-type: application/json
content-length: 1321
link: <https://api.ileap.sine.dev/v1/ileap/tad?offset=1&limit=1>; rel="next"

{
  "data": [
    {
      "activityId": "1",
      "consignmentIds": [
        "1"
      ],
      "distance": {
        "actual": "656.0"
      },
      "mass": "1000.0",
      "loadFactor": "0.8",
      "emptyDistanceFactor": "0.1",
      "origin": {
        "street": "Bredowstraße",
        "zip": "10551",
        "city": "Berlin",
        "country": "DE",
        "locode": "DEBER",
        "lat": "52.52437",
        "lng": "13.41053"
      },
      "destination": {
        "street": "Keizersgracht",
        "zip": "1017",
        "city": "Amsterdam",
        "country": "NL",
        "locode": "NLAMS",
        "lat": "52.37403",
        "lng": "4.88969"
      },
      "departureAt": "2025-12-01T14:33:51.076755968Z",
      "arrivalAt": "2025-12-11T14:33:51.076756378Z",
      "mode": "Road",
      "packagingOrTrEqType": "Pallet",
      "packagingOrTrEqAmount": 10,
      "energyCarriers": [
        {
          "energyCarrier": "Diesel",
          "feedstocks": [
            {
              "feedstock": "Fossil",
              "feedstockShare": "1.0",
              "regionProvenance": "Europe"
            }
          ],
          "energyConsumption": "10.496",
          "energyConsumptionUnit": "l",
          "emissionFactorWTW": "4.13",
          "emissionFactorTTW": "3.17",
          "relativeShare": "1.0"
        }
      ]
    }
  ]
}

7.10. Action AggregatedEmissionsData

Lists the data owner’s AggregatedReports with REQUIRED § 7.5.1 Access Control, REQUIRED § 7.5.3 Pagination, and OPTIONAL § 7.5.2 Filtering.

Note: To retrieve AggregatedReports based on embedded properties (regardless of the level of nesting), data recipients SHOULD use § 7.5.2 Filtering. See § 7.10.1.1 Examples for examples.

7.10.1. Request Syntax

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

7.10.1.1. Examples

To retrieve all AggregatedReports:

GET /v1/ileap/aed HTTP/1.1

To retrieve a single AggregatedReport, identified by reportId equal to "report-1":

GET /v1/ileap/aed?reportId=report-1 HTTP/1.1

To retrieve AggregatedReports with perModeEmissions including the transportMode "Rail"

GET /v1/ileap/aed?perModeEmissions.mode=rail HTTP/1.1

7.10.2. Response Syntax

Non-paginated response:

HTTP/1.1 StatusCode StatusText
content-type: application/json
content-length: ContentLength

ResponseBody

Paginated response (§ 7.5.3 Pagination):

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

ResponseBody

7.10.2.1. Example

HTTP/1.1 200 OK
content-type: application/json
content-length: 1321
link: <https://api.ileap.sine.dev/v1/ileap/aed?offset=1&limit=1>; rel="next"

{
  "data": [
    {
      "reportId": "ar-2025-q4-001",
      "shipmentIds": [
        "shipment-12345",
        "shipment-12346",
        "shipment-12347"
      ],
      "status": "Active",
      "reportPeriodStart": "2025-10-01T00:00:00Z",
      "reportPeriodEnd": "2025-12-31T23:59:59Z",
      "transportServiceUserId": "company-abc-123",
      "totalTransportActivity": "50000",
      "co2eWTW": "600",
      "co2eTTW": "550",
      "noxTTW": "2.5",
      "perModeEmissions": [
        {
          "transportMode": "Road",
          "co2eWTW": "400",
          "co2eTTW": "360",
          "noxTTW": "1.8"
        },
        {
          "transportMode": "Rail",
          "co2eWTW": "200",
          "co2eTTW": "190",
          "noxTTW": "0.7"
        }
      ]
    }
  ]
}

7.11. PACT Integration

As stated in § 1.2 PACT Technical Interoperability, PACT interoperability is deprecated. However, to ensure backward compatibility until the release of iLEAP v2.0.0, host systems MUST support the integration of the iLEAP data types into the PACT Data Model ([PACTDX] Chapter 5).

The iLEAP data models ShipmentFootprint, TOC, and HOC are integrated into the PACT Data Model through its extensions mechanism ([DATA-MODEL-EXTENSIONS]). This means, a ProductFootprint (see [PACTDX] Chapter 5.1) embeds the JSON representation of the iLEAP data type in the extensions property (see [DATA-MODEL-EXTENSIONS]).

The following chapters specify the exact embedding and mapping from iLEAP properties to PACT Data Model properties.

Note: Other iLEAP data types, such as AR and TAD, are available through HTTP Actions § 6.5 Transport Activity Data (TAD) and § 6.6 Aggregated Report (AR) only.

We are expecting methodological updates regarding (among others) biogenic emissions and black carbon. Once these updates are available, further guidance on how to represent them in the PACT Data Model will be provided.

7.11.1. ShipmentFootprint

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

A ShipmentFootprint CAN be integrated into the PACT 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.

{
  "name": "GLEC Framework",
  "version": "3.0"
}

The ProductFootprint mandatory properties id, version, status, productDescription, and productNameCompany cannot be derived from the ShipmentFootprint and MUST be provided by the data owner. Please follow the links above for further details.

The CarbonFootprint mandatory properties characterizationFactors, ipccCharacterizationFactorsSources, crossSectoralStandardsUsed, boundaryProcessesDescription, exemptedEmissionsPercent, and exemptedEmissionsDescription cannot be derived from the ShipmentFootprint and MUST be provided by the data owner. Please follow the links above for further details.

Any optional property that is not explicitly mentioned above MAY remain unset. All mandatory properties that cannot be derived from ShipmentFootprint CAN be populated in a best-effort manner.

7.11.2. TOC

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

A TOC CAN be integrated into the PACT 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.

{
  "name": "GLEC Framework",
  "version": "3.0"
}

The ProductFootprint mandatory properties id, version, status, productDescription, and productNameCompany cannot be derived from the TOC and MUST be provided by the data owner. Please follow the links above for further details.

The CarbonFootprint mandatory properties characterizationFactors, ipccCharacterizationFactorsSources, crossSectoralStandardsUsed, boundaryProcessesDescription, exemptedEmissionsPercent, and exemptedEmissionsDescription cannot be derived from the TOC and MUST be provided by the data owner. Please follow the links above for further details.

Any optional property that is not explicitly mentioned above MAY remain unset. All mandatory properties that cannot be derived from TOC CAN be populated in a best-effort manner.

7.11.3. HOC

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

An HOC CAN be integrated into the PACT 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.

{
  "name": "GLEC Framework",
  "version": "3.0"
}

The ProductFootprint mandatory properties id, version, status, productDescription, and productNameCompany cannot be derived from the HOC and MUST be provided by the data owner. Please follow the links above for further details.

The CarbonFootprint mandatory properties characterizationFactors, ipccCharacterizationFactorsSources, crossSectoralStandardsUsed, boundaryProcessesDescription, exemptedEmissionsPercent, and exemptedEmissionsDescription cannot be derived from the HOC and MUST be provided by the data owner. Please follow the links above for further details.

Any optional property that is not explicitly mentioned above MAY remain unset. All mandatory properties that cannot be derived from HOC CAN be populated in a best-effort manner.

8. Conformance

The iLEAP Technical Specifications are designed to be incrementally adopted and realized in host systems for different stakeholder groups. Therefore, there are 2 kinds of iLEAP conformance defined:

1. iLEAP Emissions Data Conformance

2. iLEAP Activity Data Conformance

For each kind of iLEAP Conformance, a host system achieves conformity by

1. realizing the normative statements and relevant test cases referenced in § 8.1 Conformance Matrix below,

2. successfully passing Bilateral Testing (§ 8.2 Bilateral Testing)

3. succesfully passing the Automated Conformance Testing

To achieve iLEAP Emissions Data Conformance, host systems are further REQUIRED to support the following features:

1. fetching TAD from another host system and

2. using it to generate TOC, HOC, or ShipmentFootprint data.

It is RECOMMENDED for host systems to conform to both kinds of iLEAP conformance.

Sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in these specifications are non-normative. Everything else in these specifications is normative.

The key words MAY, MUST, MUST NOT, OPTIONAL, RECOMMENDED, REQUIRED, SHOULD, and SHOULD NOT in this document are to be interpreted as described in [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.

Currently, iLEAP Conformance ensures interoperability and syntactic correctness. Future updates will extend coverage to include semantic correctness, ensuring that emissions calculations are performed accurately in end-to-end scenarios.

Conformance tests, including the Automated Conformance Testing, MUST apply the rules in § 2.5 Forward Compatibility.

8.1. Conformance Matrix

Matrix needs revision

8.2. Bilateral Testing

A Bilateral Test is an interoperability test where two different host system implementations participate to verify conformance (§ 8 Conformance) and their ability to work together.

One system acts as the data owner. It is called the target host system and is the system under test. The second system acts as the testing party.

Note: The objective of Bilateral Testing is to ensure that systems can effectively communicate despite having independent codebases.

8.3. Submission

Note: non-normative

Once a host system achieved iLEAP conformance in 1 or all kinds of iLEAP conformance, the implementer is requested to reach out to the authors of these Technical Specifications to apply for additional support, materials, and marketing opportunities.

Appendix A: Changelog

Version 1.1.0-draft.3 (unreleased)

• addition of § 2.4 Transport Activity and Hub Activity: transport activity and hub activity are distinct and MUST NOT be mixed

• updated definitions of Hub Activity, TCE, and Transport Activity

• totalActivity no longer includes hub activity (transport activity in tonne-kilometers only)

• AggregatedReport and ModeSpecificReport: co2eWTW and co2eTTW cover hub equipment operation in addition to vehicle operation

• relative shares of energyCarriers are computed relative to the transport activity of the respective transport mode

• removed references to transport activity from energyCarriers, co2eIntensityWTW, and co2eIntensityTTW

• aligned the definitions of Hub Operator, Transport Operator, TOC, and Primary Data with [ISO14083] (freight only)

• § 1.3 Out of Scope: emissions from electricity are quantified using the location-based approach ([ISO14083], Annex J.3); market-based figures remain out of scope (semantic change)

• § 1.3 Out of Scope: refrigerant leakage is part of the system boundary of [ISO14083] (Section 5.2.2); only the exchange of refrigerant-specific data remains out of scope (semantic change)

• addition of § 2.5 Forward Compatibility: data recipients ignore unknown properties and do not reject unknown enumeration values; enumeration values may be added in minor versions

• replaced the advisements on evolving enumerations with a reference to § 2.5 Forward Compatibility

• addition of the definitions of Default Value, Hub, Hub Equipment, Hub Operation, Hub Service, Hub TCE, Modeled Data, Throughput, Transport Operation, and Transport Service; updated definitions of Hub Activity, HOC, and Secondary Data (aligned with [ISO14083], freight only)

• addition of § 6.2.2 Hub TCEs: hub TCEs have zero distance and zero transport activity; their emissions are derived from the HOC intensities and the hub activity of the TCE (semantic change)

• rewrote the note on TransportMode: the enumeration is used by TOCs, TADs, HOCs, and ModeSpecificReports

• energyConsumption: the reference quantity is specified per context (per unit of transport activity for TOCs, per unit of hub activity for HOCs, total quantity for TADs and ModeSpecificReports); energyConsumptionUnit SHOULD be defined when emission factors are defined

• addition of data type RefrigerantLeakageCoverage, used by the new properties refrigerantLeakageCoverage and refrigerantLeakageCoverage: TOC and HOC intensities MUST include GHG emissions from refrigerant leakage unless partial coverage or omission is stated (semantic change)

• addition of § 6.4.1 System Boundary: HOCs follow the system boundary of [ISO14083]; the allocation of energy supplied to vehicles at the hub and the inclusion of optional processes MUST be stated in comment

• corrected the description of comment (previously referring to the TOC)

• addition of data type TemperatureControl, used by temperatureControl, temperatureControl, and the new property temperatureControl; new values chilled, frozen, and heated; mixed now covers any two or more temperature conditions (semantic change)

• addition of temperatureSpecificIntensities for temperature-specific GHG emission intensities within one HOC ([ISO14083], Section 9.5.3); hub TCEs use the intensity matching their temperature condition

• addition of inboundTransportModes and outboundTransportModes; deprecation of inboundTransportMode and outboundTransportMode

• addition of the EnergyCarrierType values Biodiesel, Natural gas (stationary combustion, hub operations only), and Heat (purchased heat, hub operations only)

• hubActivityUnit: TEU is no longer restricted to sea and inland waterway outbound transport; addition of freightMassPerTEU; in § 7.11.3 HOC, the intensity of TEU-based HOCs is converted to a per tonne basis (semantic change)

• transportActivityUnit: TEUkm is no longer restricted to sea and inland waterways

• HubType: addition of IntermodalTerminal and alignment of the descriptions with the hub types of the GLEC Framework v3.2; IntermodalTerminal added to hubOperations

• PackagingOrTrEqType: addition of SwapBody and Trailer

• addition of § 6.7.8.1 Emission Factors of Electricity: emission factors of electricity MUST be determined using the location-based approach of [ISO14083], Annex J.3 (semantic change)

• addition of emissionFactorMethod with value LocationBased

• clarified the feedstock values Grid and Renewable electricity: grid electricity covered by contractual instruments is Grid (semantic change)

• hubLocation: IATA and UIC codes may be used; hubs that are part of a transport node SHOULD carry the code of the transport node

• addition of § 6.4.3 GHG Emission Intensity Example: a HOC with average and temperature-specific GHG emission intensities and a hub TCE, based on the GLEC Framework v3.2