All Collections
Pledge platform
Importing your data
Multimodal freight file specification
Multimodal freight file specification

File specification for multimodal freight data

Updated over a week ago

Overview

This article covers the file format used by Pledge 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 to familiarise yourself with Pledge's general CSV/Excel file specification for importing data.

Understanding how to map freight data

Pledge 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

Fields

Column

Data Type

Mandatory

SHIPMENT_ID

TEXT

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.

Yes

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.

No

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"

No

If not specified, will default to MAIN

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.

Yes

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.

FROM_ADDRESS

TEXT e.g. 66 Faubourg Saint Honoré, Paris

Yes (one of FROM_ADDRESS, FROM_COORDINATES, FROM_CODE or DISTANCE)

Notes: Optional for Logistics Sites

FROM_COUNTRY_CODE

TEXT e.g. GB

Notes: ISO 3166-1 alpha-2 country code.

No

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

Notes: Convention dictates format is: latitude, longitude

Yes (one of FROM_ADDRESS, FROM_COORDINATES, FROM_CODE or DISTANCE)

Notes: Optional for Logistics Sites

FROM_CODE

TEXT e.g. GBBYS

Notes: 3 letter IATA code for flights or 5 letter UN/LOCODE for sea ports or rail stations. White-spaces will be stripped

Yes (one of FROM_ADDRESS, FROM_COORDINATES, FROM_CODE or DISTANCE)

Notes: Optional for Logistics Sites

TO_ADDRESS

TEXT e.g. 4 rue Sophie Germain, Paris, France

Yes (one of TO_ADDRESS, TO_COORDINATES, TO_CODE or DISTANCE

Notes: Optional for Logistics Sites

TO_COUNTRY_CODE

TEXT e.g. GB

Notes: ISO 3166-1 alpha-2 country code.

No

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

Notes: Convention dictates format is: latitude, longitude

Yes (one of TO_ADDRESS, TO_COORDINATES, TO_CODE or DISTANCE)

Notes: Optional for Logistics Sites (VEHICLE=LS**)

TO_CODE

TEXT e.g. CN AHK

Notes: 3 letter IATA code for flights or 5 letter UN/LOCODE for sea ports or rail stations. Whitespaces will be stripped

Yes (one of TO_ADDRESS, TO_COORDINATES, TO_CODE or DISTANCE)

Notes: Optional for Logistics Sites (VEHICLE=LS**)

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.

No

Notes: Only applies to sea (VEHICLE=S**) and air freight (VEHICLE=A).

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

No

Notes:

  • 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

Yes (either this or 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=LS**)

DISTANCE_UNIT

TEXT eg. KM

One of :

  • KM - KILOMETER

  • MI - MILE

  • NM - NAUTICAL MILE

No

Notes: If not specified will default to KM

Will be ignored for Logistics Sites (VEHICLE=LS**)

WEIGHT

DECIMAL e.g. 12.54

Yes

WEIGHT_UNIT

TEXT e.g. KG

One of:

  • KG - KILOGRAM

  • LBS - POUNDS

  • TONNES - METRIC TONS

  • TONS - SHORT TONS (2,000 POUNDS)

Or

  • TEU - TWENTY-FOOT EQUIVALENT UNIT

No

Notes: If not specified will default to KG

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)

No

Notes: If not specified will default to AVERAGE

VEHICLE

TEXT eg. HR1

One of:

  • A - AIRCRAFT

  • T - TRAIN

  • SBC - Ship - Bulk Carrier - Average

  • SBC1 - Ship Bulk Carrier (0-10k dwt)

  • SBC2 - Ship Bulk Carrier (10-100k dwt)

  • SBC3 - Ship Bulk Carrier (>100k dwt)

  • SGC - Ship - General Cargo

  • SGC1 - Ship - General Cargo (0-10k dwt)

  • SGC2 - Ship - General Cargo (10-20k dwt)

  • SCS - Ship - Container Ship - Average

  • SRR - Ship - RoRo Ferry

  • SRP - Ship - RoPax Ferry

  • V - VAN (0-3.5 tonnes)

  • LST - Logistics Hub - Transhipment

  • LSST - Logistics Hub - Transhipment and Storage

  • LSC - Logistics Hub - Container Terminal

  • LSW - Logistics Hub - Warehouse

  • BMV - Barge - Motor vessels

  • BMV1 - Barge - Motor vessels < 80 m (< 1000 t)

  • BMV2 - Barge - Motor vessels 85–110 m (1000–2000 t)

  • BMV3 - Barge - Motor vessels 135 m (2000–3000 t)

  • BCC - Barge - Coupled convoys (163–185 m)

  • BTV - Barge - Tanker vessels

  • BTV1 - Barge - Tanker vessels 110 m

  • BTV2 - Barge - Tanker vessels 135 m

  • BCV - Barge - Container vessels

  • BCV1 - Barge - Container vessels 110 m

  • BCV2 - Barge - Container vessels 135 m

  • BCVCC - Barge - Container vessels – Coupled convoys

  • BPC - Barge - Pushed convoy

  • BPC1 - Barge - Pushed convoy – push boat + 2 barges

  • BPC2 - Barge - Pushed convoy – push boat + 4/5 barges

  • BPC3 - Barge - Pushed convoy – push boat + 6 barges

Outside of North America:

  • H - Truck

  • H1 - Truck - Urban Truck (3.5-7.5 tonnes)

  • H2 - Truck - MGV (7.5-20 tonnes)

  • H3 - Truck - HGV (>20 tonnes)

  • HR1 - Truck - Rigid (3.5-7.5 tonnes)

  • HR2 - Truck - Rigid (7.5-12 tonnes)

  • HR3 - Truck - Rigid (12-20 tonnes)

  • HR4 - Truck - Rigid (20-26 tonnes)

  • HR5 - Truck - Rigid (26-32 tonnes)

  • HA1 - Truck - Articulated (3.5 - 34 tonnes)

  • HA2 - Truck - Articulated (34-40 tonnes)

  • HA3 - Truck - Articulated (40-44 tonnes)

  • HA4 - Truck - Articulated (44-60 tonnes)

  • HA5 - Truck - Articulated (60-72 tonnes)

In North America:

  • NA_HG - Truck - General

  • NA_HAC - Truck - Auto Carrier

  • NA_HD - Truck - Dray

  • NA_HE - Truck - Expedited

  • NA_HF - Truck - Flatbed

  • NA_HHB - Truck - Heavy Bulk

  • NA_HLTL - Truck - LTL

  • NA_HMI -Truck - Mixed

  • NA_HMO - Truck - Moving

  • NA_HP - Truck - Package

  • NA_HS - Truck - Specialized

  • NA_HT - Truck - Tanker

  • NA_HTL - Truck - TL

Notes: For North America truck movements, the type of goods rather than the truck size needs to be specified using the appropriate NA_* code.

It is your responsibility to choose the appropriate code based on whether the movement is in North America or not - Pledge will not validate this.

Yes

IS_REFRIGERATED

BOOLEAN eg. TRUE

No

Notes: If not specified will default to FALSE

Only applicable for Vans, Trucks, Container Ships, Transhipment and Storage Logistics Sites. Will be ignored otherwise

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

No

The following default values are used:

- For aircrafts (VEHICLE=A), AVIATION_FUEL.

- For barges (VEHICLE=B**), DIESEL.

For trains (VEHICLE=T) 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=V) and trucks outside of North America (VEHICLE=H**), DIESEL is the default value.

For non-container ships (VEHICLE=S**, except SCS), HFO is the default value.

FUEL_CONSUMPTION

DECIMAL e.g. 10

No

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

No

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

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

No

LOAD_FACTOR

DECIMAL e.g. 0.7

No

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

No

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.

EMISSION_STANDARD

TEXT e.g. EURO_6

One of:

  • EURO_1

  • EURO_2

  • EURO_3

  • EURO_4

  • EURO_5

  • EURO_6

No

Notes: Only applicable for Trucks and Vans.

If not provided will default to a value based on the relevant methodology being applied.

VESSEL_ID

TEXT e.g. 9321483

Notes: 7 digit IMO ship identifier of the cargo ship

No

Notes: Will be ignored unless mode is sea (VEHICLE=S**). If provided will override VEHICLE if value is incorrect.

If VESSEL_ID can't be mapped to vessel, will use vehicle code as default.

If size can't be mapped, will use general ship type for IMO provided.

VESSEL_NAME

TEXT e.g. EVER GIVEN

No

Notes: Will be ignored unless mode is sea (VEHICLE=S**).

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 will be used as default.

If the vessel size can't be determined, general ship type for name provided 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 will be used as default.

VOYAGE_NO

TEXT e.g. 987AB1

No

Notes: Will be ignored unless mode is sea (VEHICLE=S**).

If VOYAGE_NO can’t be mapped to a voyage, will use defaults for inferred values.

AIRCRAFT_CODE

TEXT e.g. B37M

Notes: IATA aircraft code

No

Notes: Will be ignored unless air freight (VEHICLE=A)

FLIGHT_NO

TEXT e.g. BA113

No

Notes: Will be ignored unless air freight (VEHICLE=A)

If provided will override AIRLINE_CODE and AIRCRAFT_CODE if those are provided.

Did this answer your question?