Overview

This article covers the file format used by Blue Yonder Logistics Emissions Calculator to import data pertaining to shipment-level freight, where there is data about the mode of transport and weight or containers being shipped.

General CSV/Excel file specification

Before diving into the freight specific fields, you are encouraged to first familiarise yourself with the general CSV/Excel file specification for importing data.

Understanding how to map freight data

Blue Yonder Logistics Emissions Calculator supports the import of data that describes end-to-end multi-modal movements of freight, including pre-carriage, main carriage or port-to-port and on-carriage movements.

Each movement or leg in the shipment of cargo is represented as one line in the file where that one line describes things such as the origin, destination, type of vehicle used and other related information for that movement. Therefore, if a shipment has multiple legs, multiple lines in the file should be provided.

SHIPMENT_ID and SEQUENCE_NO

For each shipment of cargo, the shipment must have a unique identifier (provided by you) in the SHIPMENT_ID field. If there are multiple legs as part of the same shipment then the same unique identifier must be used for all of those legs in addition to specifying a SEQUENCE_NO that defines in what order the legs occurred e.g. pre-carriage movements will have lower sequence numbers than the main carriage movements and on-carriage movements.

Template and sample files

You can find an empty template and other relevant sample files in our public repository.

Fields

Fields marked with ✅ are mandatory; ⚠️ are conditionally mandatory; and 🚫 are deprecated.

Shipment details

	Column	Data Type
✅	SHIPMENT_ID	TEXT e.g. ABC250304 Notes: A unique identifier for the shipment. If there are multiple legs in a shipment, then the same identifier should be used for all of those legs.
✅	DATE	RFC 3339-like format e.g. 2021-09-15 12:31 Ideally, the pick-up date, date of departure or otherwise start date of the shipment. Notes: Only the date provided for SEQUENCE_NO=1 in a shipment will be considered; others will be ignored at this time. However, dates for each sequence may be taken into consideration in future (as date of departure), so please provide, if available.
	SEQUENCE_NO	INTEGER e.g. 1 Notes: The sequence number specifies the sequence of legs in a shipment, which may cover: pre-carriage, main carriage and on-carriage or multiple flights within the carriage, if applicable. 1-based indexing. 0 is not an allowed value. If not specified, then it will default to 1.
	CARRIAGE	TEXT eg. MAIN One of: PRE MAIN ON Where PRE is sometimes referred to as "first mile" and ON is sometimes referred to as "last mile" Notes: If not specified, will default to MAIN

Route and locations

	Column	Data Type
✅	FROM_ADDRESS	TEXT e.g. 66 Faubourg Saint Honoré, Paris Or provide one of: FROM_COORDINATES, FROM_CODE, or DISTANCE. Notes: Optional for Logistics Sites (VEHICLE_TYPE=LOGISTICS_SITE)
	FROM_COUNTRY_CODE	TEXT e.g. GB Notes: ISO 3166-1 alpha-2 country code. Can be optionally provided in addition to FROM_ADDRESS, to improve geocoding, or in addition to DISTANCE* to improve the accuracy of emissions calculation based on geography.*
✅	FROM_COORDINATES	DECIMAL,DECIMAL e.g. 48.8700388,2.3185802 Or provide one of: FROM_ADDRESS, FROM_CODE, or DISTANCE. Notes: Convention dictates format is: latitude, longitude Optional for Logistics Sites (VEHICLE_TYPE=LOGISTICS_SITE)
✅	FROM_CODE	TEXT e.g. GBBYS Or provide one of: FROM_ADDRESS, FROM_COORDINATES, or DISTANCE. Notes: 3 letter IATA code for flights or 5 letter UN/LOCODE for sea ports or rail stations. White-spaces will be stripped. Optional for Logistics Sites (VEHICLE_TYPE=LOGISTICS_SITE)
✅	TO_ADDRESS	TEXT e.g. 4 rue Sophie Germain, Paris, France Or provide one of: TO_COORDINATES, TO_CODE, or DISTANCE. Notes: Optional for Logistics Sites (VEHICLE_TYPE=LOGISTICS_SITE)
	TO_COUNTRY_CODE	TEXT e.g. GB Notes: ISO 3166-1 alpha-2 country code. Can be optionally provided in addition to TO_ADDRESS, to improve geocoding, or in addition to DISTANCE* to improve the accuracy of emissions calculation based on geography.*
✅	TO_COORDINATES	DECIMAL,DECIMAL e.g. 48.8307843, 2.3312721 Or provide one of: TO_ADDRESS, TO_CODE, or DISTANCE. Notes: Convention dictates format is: latitude, longitude Optional for Logistics Sites (VEHICLE_TYPE=LOGISTICS_SITE)
✅	TO_CODE	TEXT e.g. CN AHK Or provide one of: TO_ADDRESS, TO_COORDINATES, or DISTANCE. Notes: 3 letter IATA code for flights or 5 letter UN/LOCODE for sea ports or rail stations. White-spaces will be stripped. Optional for Logistics Sites (VEHICLE_TYPE=LOGISTICS_SITE)
	STOPS	TEXT e.g. THLCH;VNHPH;CNYTN Notes: semi-colon separated 3 letter IATA code for flight stopovers or 5 letter UN/LOCODE for port-calls. Only applies to sea (VEHICLE_TYPE=SHIP) and air freight (VEHICLE_TYPE=AIRCRAFT).
	VIA	TEXT e.g. GBSOU;50.85486,0.58273;GBEBO Notes: semi-colon separated 5-letter UN/LOCODEs and geo-coordinates (formatted as latitude,longitude). Only applies to road based shipments (i.e. Trucks and Vans) Only here to influence the route between the origin and destination. This will not involve a stop.
✅	DISTANCE	DECIMAL e.g. 12.54 Or provide FROM_X and TO_X Notes: If DISTANCE* is provided in addition to FROM_X and TO_X then DISTANCE will be used for emissions computations* Will be ignored for Logistics Sites (VEHICLE_TYPE=LOGISTICS_SITE)
	DISTANCE_UNIT	TEXT eg. KM One of : KM - KILOMETER MI - MILE NM - NAUTICAL MILE Notes: If not specified, will default to KM Will be ignored for Logistics Sites (VEHICLE_TYPE=LOGISTICS_SITE)

Cargo and load

	Column	Data Type
✅	WEIGHT	DECIMAL e.g. 12.54 Notes: All legs of a shipment must have the same weight. If different weights are provided, the Logistics Emissions Calculator defaults to the weight of the first leg.
	WEIGHT_UNIT	TEXT e.g. KG One of: KG - KILOGRAM LBS - POUNDS TONNES - METRIC TONS TONS - SHORT TONS (2,000 POUNDS) Or (DEPRECATED) TEU - TWENTY-FOOT EQUIVALENT UNIT - please use CONTAINER_20G_QTY instead of TEU or otherwise specify container types and quantities, if known Notes: If not specified, will default to KG
	CONTAINER_20G_QTY	INTEGER eg. 1 Notes: The quantity of 20 foot equivalent dry containers.
	CONTAINER_20R_QTY	INTEGER eg. 1 Notes: The quantity of 20 foot equivalent reefer containers.
	CONTAINER_40G_QTY	INTEGER eg. 1 Notes: The quantity of 40 foot equivalent dry containers.
	CONTAINER_40R_QTY	INTEGER eg. 1 Notes: The quantity of 40 foot equivalent reefer containers.
	CONTAINER_40HC_QTY	INTEGER eg. 1 Notes: The quantity of 40 foot high cube equivalent dry containers.
	CONTAINER_45HC_QTY	INTEGER eg. 1 Notes: The quantity of 45 foot high cube equivalent dry containers.
	CONTAINER_OTHER_QTY	INTEGER eg. 1 Notes: The quantity of containers with an ISO type code provided in the CONTAINER_OTHER_CODE column. If specified then CONTAINER_OTHER_CODE must also be specified.
	CONTAINER_OTHER_CODE	TEXT eg. 42H1 Notes: Must be a valid ISO 6346 container type code. See type codes for more information. Used to specify a container with an alternative ISO type code that is not represented in the other container columns. Both ISO type group code and ISO size type codes are supported. If specified, then CONTAINER_OTHER_QTY* must also be specified.*
	CARGO_TYPE	TEXT e.g. LIGHT One of: LIGHT - Light goods (6 MT per TEU) AVERAGE - Average goods (10 MT per TEU) HEAVY - Heavy goods (14.5 MT per TEU) Notes: If not specified, will default to AVERAGE
	LOAD_TYPE	TEXT e.g. FCL One of: FTL - Full truckload LTL - Less than truckload FCL - Full container load LCL - Less than container load Notes: Only relevant for road freight or container scenarios. If not specified, will default to LTL* for road and FCL for container scenarios.*

Transport mode and equipment

	Column	Data Type
✅	VEHICLE_TYPE	TEXT eg. TRUCK One of: TRUCK - Heavy road freight vehicle, such as a rigid truck, articulated truck, or dump truck VAN - Light commercial road vehicle, such as a delivery van or small goods vehicle SHIP - Freight vessel, such as a container ship, bulk carrier AIRCRAFT - Air freight transport, such as a dedicated cargo aircraft or freight carried on a passenger aircraft. TRAIN - Rail freight transport BARGE - Inland waterway freight vessel, such as a motor vessel, pushed convoy LOGISTICS_SITE - Fixed logistics hubs, such as a warehouse, terminal, or transhipment site Examples: For a truck where the category and size are unknown, simply use VEHICLE_TYPE = TRUCK For a 44-tonne articulated truck, use VEHICLE_TYPE = TRUCK, VEHICLE_CATEGORY = ARTICULATED, and VEHICLE_MAX_SIZE = 44.0 For a dry van truck used for full truckload freight, use VEHICLE_TYPE = TRUCK, VEHICLE_CATEGORY = ARTICULATED, VEHICLE_BODY_TYPE = DRY_VAN, and LOAD_TYPE = FTL For a small delivery van, use VEHICLE_TYPE = VAN For a 10,000 dwt general cargo ship, use VEHICLE_TYPE = SHIP, VEHICLE_CATEGORY = GENERAL_CARGO, and VEHICLE_MAX_SIZE = 10000 For air freight on a passenger flight, use VEHICLE_TYPE = AIRCRAFT and VEHICLE_CATEGORY = PASSENGER Notes: When selecting VEHICLE_BODY_TYPE = REFRIGERATED, the IS_REFRIGERATED flag will automatically be set to TRUE and override any provided value. Migrating from the deprecated VEHICLE* field? See Mapping legacy vehicle codes to vehicle attributes for the complete mapping from legacy vehicle codes to the new vehicle attributes.*
⚠️	VEHICLE_CATEGORY	TEXT eg. RIGID The specific classification of the vehicle or logistics hub. Must be compatible with the selected VEHICLE_TYPE. For the TRUCK vehicle type, this indicates the physical chassis configuration, which must be one of: RIGID - Single-unit rigid truck. ARTICULATED - Multi-unit combination truck (tractor-trailer). DUMP - Specialised dump/tipper truck configuration. For the SHIP vehicle type, this indicates the freight vessel type, which must be one of: BULK_CARRIER - Bulk cargo carrier. CONTAINER_SHIP - Containerised cargo vessel. GENERAL_CARGO - Non-specialised bulk vessel. REFRIGERATED_BULK - Bulk vessel with refrigerated hold. ROPAX - Ferry for passengers and freight vehicles. RORO - Roll-on/roll-off freight vessel. VEHICLE - Dedicated vehicle transport vessel. For the AIRCRAFT vehicle type, this field differentiates between various cargo transit classifications, which must be one of: FREIGHTER - Dedicated cargo aircraft. PASSENGER - Belly-freight capacity on commercial passenger flights. For the BARGE vehicle type, this specifies the classification of inland waterway transport vessels, which must be one of: CONTAINER_VESSEL - Inland container-carrying barge. COUPLED_CONVOY - Multiple barges linked together. MOTOR_VESSEL - Self-propelled inland vessel. PUSHED_CONVOY - Barges pushed by a tugboat. TANKER_VESSEL - Inland barge for bulk liquids. For the LOGISTICS_SITE vehicle type, this specifies the type of fixed facility used for emission modelling, which must be one of: TRANSHIPMENT - Node for cargo transfer between modes. STORAGE_AND_TRANSHIPMENT - Storage area combined with cargo transfer. CONTAINER_TERMINAL - Port area for handling containers. WAREHOUSE - Facility for storing goods. LIQUID_BULK_TERMINAL - Facility for bulk liquid storage. Notes: Required for SHIP, BARGE, and LOGISTICS_SITE. Optional, but recommended, for TRUCK* and AIRCRAFT.* Not used for TRAIN* and VAN.*
	VEHICLE_MAX_SIZE	DECIMAL e.g. 26.0 The maximum physical size or capacity of the vehicle. For Trucks, provide the Gross Vehicle Weight (GVW) in tonnes, e.g. 24 or 44. For Ships, provide the deadweight tonnage (DWT), e.g. 25000. For Barges, the required value depends on the vehicle type: For MOTOR_VESSEL, TANKER_VESSEL, and CONTAINER_VESSEL, provide the vessel length in metres, e.g. 85. For PUSHED_CONVOY, provide the total number of barges in the convoy, e.g. 4. Not supported for COUPLED_CONVOY, as this uses the standard vessel-length range of 163–185 metres. Notes: Only applicable for Trucks, Ships, and Barges. Will be ignored otherwise. If not specified, will default to a capacity based on the relevant vehicle type and methodology being applied.
	VEHICLE_BODY_TYPE	TEXT e.g. DRY_VAN The physical body or trailer configuration of the vehicle. One of: AUTO_CARRIER – Vehicle transport service, e.g. a car hauler. DRY_VAN – Standard enclosed box trailer, rigid truck or bare chassis equipment used for general freight. FLATBED – Flatbed or open-trailer freight service. HEAVY_BULK – Heavy or bulk commodity service, e.g. steel, logs or aggregates. MIXED – An unsegregated mix of equipment types, or where the specific configuration is unknown. MOVING – Household or commercial moving and relocation service. REFRIGERATED – Active temperature-controlled service, including cooling or heating. SPECIALIZED – Specialised equipment for non-standard cargo, e.g. hopper, livestock or glass haulers. TANKER – Liquid or gas tanker service. *Notes:* Only applicable for TRUCK. Will be ignored otherwise. For DRY_VAN, providing LOAD_TYPE* as FTL or LTL can improve calculation accuracy.* If REFRIGERATED is provided, IS_REFRIGERATED will automatically be set to TRUE
	VEHICLE_OPERATION_TYPE	TEXT e.g. DRAYAGE The operational nature or driving profile of the freight service. One of: DRAYAGE – Short-haul movement of intermodal containers between ports, rail terminals and local hubs. Typically associated with congested, stop-start driving. EXPEDITED – Time-sensitive freight service, typically associated with long-haul, steady-state highway driving. MIXED – An unclassified or blended mix of service profiles, e.g. local distribution combined with regional hauling. PACKAGE – Parcel, courier or last-mile delivery service characterised by frequent stops. *Notes:* Only applicable for TRUCK. Will be ignored otherwise.
	IS_REFRIGERATED	BOOLEAN eg. TRUE Notes: If not specified, will default to FALSE Only applicable for Vans, Trucks, Container Ships, Transhipment and Storage Logistics Sites. Will be ignored otherwise
	EMISSION_STANDARD	TEXT e.g. EURO_6 One of: EURO_1 EURO_2 EURO_3 EURO_4 EURO_5 EURO_6 Notes: Only applicable for Trucks and Vans. If not provided, will default to a value based on the relevant methodology being applied.
🚫	VEHICLE	Deprecated. Use VEHICLE_TYPE instead. See Mapping legacy vehicle codes to vehicle attributes to understand how legacy vehicle codes translate to the new attributes

Fuel and operating data

	Column	Data Type
	FUEL_TYPE	TEXT eg. DIESEL For trains, one of: DIESEL ELECTRICITY For vans, one of: DIESEL PETROL CNG LPG ELECTRICITY For trucks (outside of North America), one of: DIESEL CNG LNG ELECTRICITY For non-container ships, one of: HFO MGO LNG Notes: The following default values are used: For aircrafts (VEHICLE_TYPE=AIRCRAFT, AVIATION_FUEL. For barges (VEHICLE_TYPE=BARGE), DIESEL. For trains (VEHICLE_TYPE=TRAIN) there is no default value. If you don’t provide a value, we will attempt to determine it based on the computed route. For vans (VEHICLE_TYPE=VAN) and trucks outside of North America, DIESEL* is the default value.* For non-container ships, HFO* is the default value.*
	FUEL_CONSUMPTION	DECIMAL e.g. 10 Notes: Positive decimal. Only applicable for Trucks and Vans outside of North America. If specified, then FUEL_TYPE* must also be specified.* We assume that the fuel consumption is representative of both loaded and empty journeys.
	FUEL_CONSUMPTION_UNIT	TEXT e.g. L_PER_100_KM It must be compatible with the given FUEL_TYPE: For DIESEL, PETROL and LPG: L_PER_100_KM US_GAL_PER_100_MI IMP_GAL_PER_100_MI For ELECTRICITY: KWH_PER_100_KM KWH_PER_100_MI For LNG and CNG: KG_PER_100_KM LBS_PER_100_MI Notes: If not specified, will default to: *L_PER_100_KM, for DIESEL, PETROL* and LPG *KWH_PER_100_KM, for ELECTRICITY* *KWH_PER_100_KM, for LNG* and CNG
	LOAD_FACTOR	DECIMAL e.g. 0.7 Notes: Decimal between 0 and 1. Only applicable for Trucks and Vans. If not provided will default to a value based on the relevant methodology being applied
	EMPTY_RUNNING	DECIMAL e.g. 0.3 Notes: Decimal between 0 and 1. Only applicable for Trucks and Vans. If not provided will default to a value based on the relevant methodology being applied.

Carrier details

	Column	Data Type
	CARRIER_CODE	TEXT e.g. 4Y Notes: For air freight: 2 letter IATA airline code. For North-American road freight: SmartWay SCAC identifier. For container vessels: Clean Cargo carrier identifier
	CARRIER_NAME	TEXT e.g. Maersk

Transport mode-specific details

	Column	Data Type
	VESSEL_ID	TEXT e.g. 9321483 Notes: 7 digit IMO ship identifier of the cargo ship Will be ignored unless mode is sea (VEHICLE_TYPE=SHIP). If provided, and a matching vessel is found, will override VEHICLE_CATEGORY and VEHICLE_MAX_SIZE with the vessel's actual category and size. If VESSEL_ID* can't be mapped to vessel, will use whatever has been provided for VEHICLE_CATEGORY and VEHICLE_MAX_SIZE as default.* If size can't be mapped, the default size for that vessel's ship category will be used.
	VESSEL_NAME	TEXT e.g. EVER GIVEN Notes: Will be ignored unless mode is sea (VEHICLE_TYPE=SHIP). If both VESSEL_ID* and VESSEL_NAME are provided, VESSEL_ID will have priority.* If VESSEL_NAME can't be mapped to a specific vessel then whatever has been provided for VEHICLE_CATEGORY and VEHICLE_MAX_SIZE will be used as default. If the vessel size can't be determined, the default size for that vessel's ship category will be used. In case several matches are found for the VESSEL_NAME, VESSEL_NAME* will then be ignored and whatever is provided for VEHICLE_CATEGORY and VEHICLE_MAX_SIZE will be used as default.*
	VOYAGE_NO	TEXT e.g. 987AB1 Notes: Will be ignored unless mode is sea (VEHICLE_TYPE=SHIP). If VOYAGE_NO* can’t be mapped to a voyage, will use defaults for inferred values.*
	FERRY_LOAD_CHARACTERISTICS	TEXT e.g. ACCOMPANIED One of: ACCOMPANIED UNACCOMPANIED Notes: Only relevant for explicit ferry legs, i.e. when the VEHICLE_TYPE=SHIP alongside one of the following: *VEHICLE_CATEGORY*=RORO (indicating a roll-on/roll-off freight vessel) *VEHICLE_CATEGORY*=ROPAX (indicating a combined passenger and freight ferry) Or for road legs involving a ferry segment (the ferry segment will be inferred automatically).
	AIRCRAFT_CODE	TEXT e.g. B37M Notes: IATA aircraft code Will be ignored unless air freight (VEHICLE_TYPE=AIRCRAFT)
	FLIGHT_NO	TEXT e.g. BA113 Notes: Will be ignored unless air freight (VEHICLE_TYPE=AIRCRAFT) If provided, it will override AIRLINE_CODE* and AIRCRAFT_CODE if those are provided*.

Reporting and classification

	Column	Data Type
	SCOPE	INTEGER eg. 1 Notes: Defines the greenhouse gas accounting scope, as set out in the GHG Protocol. Indicates whether the emissions reported are Scope 1 (direct), Scope 2 ( indirect), or Scope 3 (indirect).
	CATEGORY	INTEGER eg. 4 Notes: GHG Protocol category that further classifies Scope 3 emissions (e.g. purchased goods, upstream transport, downstream distribution).

Multimodal freight file specification