Checklist
Here's a quick checklist for your files before you try importing:
Filename is valid
File is ideally UTF-8 encoded but the Logistics Emissions Calculator will attempt to handle other encodings
File has a header row
File has all of the fields for the specific use case specification (even if the fields are not mandatory or are otherwise empty)
File includes the CLIENT_KEY, SUPPLIER_KEY, or both required by your organisation's configuration, with a value provided for every row
Filename rules
Must have .csv or .xlsx extension
Must be at least 5 characters and no more than 128 characters including the extension
Must begin with an alphanumeric character
Must only contain alphanumerics, hyphens, periods, underscores and brackets eg. ()
Examples
Valid | Invalid |
a.csv | ..csv |
1.csv | _.csv |
A1234(2).csv | A1234 (2).csv |
a1234(2).v2.csv | a1234(2)!.csv |
a1234(2)-v3.csv | -a1234-v3.csv |
Header row
Header rows must be included in your CSV/Excel file.
Mandatory fields
Depending on the use case, different fields will be mandatory or optional. A value must be present for mandatory fields. Optional fields can contain a value or be left empty.
In addition to the use-case-specific fields, your organisation can require a CLIENT_KEY, SUPPLIER_KEY, or both for every emission. Each row must contain a value for the key or keys required by your organisation's configuration.
See Special Metadata fields below.
Common field types
Date
Dates are specified in a variation of RFC 3339 format and can include time.
Dates must be specified in YYYY-MM-DD format
Times are optional
Times must be specified in HH:MM:SS or HH:MM:SS.mmm format
'T' or space can be used to separate the Date and Time
'Z' or '+/-HH:MM' can be used to denote the time zone offset
Valid examples
2022-06-12
2019-08-13 12:30:00
2022-06-12 00:00:00
2019-08-13 00:00:00.000
2019-08-13 12:30:00Z
2019-08-13 12:30:00+01:00
2019-08-13 12:30:00-02:00
2019-08-13 12.30:00.000
2019-08-15 12:30:00.000Z
2019-08-13T12:30:00
Coordinates
Coordinates are specified in latitude and longitude format in the following way:
51.5144951,-0.0824952
Where latitude is first. Due to there being a comma in the coordinates, it will be necessary to quote the entire contents when converting to CSV.
Metadata
Any column headers that are present in the CSV/Excel file that are in addition to the well-defined columns headers for the particular use case will be treated as metadata names and any values present in these columns will be imported alongside the relevant emissions data provided as metadata values.
Metadata can useful for correlation purposes i.e. if you have certain IDs in your system that you would want to be able to track through to the Logistics Emissions Calculator, then you can include those IDs in the CSV/Excel file and they will be attached as metadata - that is, they will play no part in the emissions computations but can provide more informational context. You can then subsequently search and filter by this metadata in the platform.
WARNING: Do not send any personally identifiable information (PII), such as personal names or email addresses, as key values, as this could inadvertently cause GDPR issues.
Special Metadata fields
You are free to specify arbitrary metadata fields, but there are a few pre-defined metadata fields that have additional significance and may be validated accordingly.
CLIENT_KEY
CLIENT_KEY identifies the organisation that contracted you to handle the shipment. This is the organisation one step downstream of you in the commercial relationship and typically the client you would report emissions back to.
Providing a CLIENT_KEY allows emissions to be allocated, filtered, grouped, and reported by client in the Logistics Emissions Calculator.
To use CLIENT_KEY, add a column to your CSV/Excel file with the header CLIENT_KEY and populate it with the key, ID, code, or name you use to identify that organisation.
SUPPLIER_KEY
SUPPLIER_KEY identifies the organisation that you contracted to handle the shipment. This is the organisation one step upstream of you in the commercial relationship and may be a carrier, freight forwarder, or your own internal fleet.
The key should represent the organisation you contracted directly, not necessarily the organisation that physically moved the goods. For example, if you contracted a freight forwarder who then subcontracted the transport to a carrier, the freight forwarder is your SUPPLIER_KEY.
Providing a SUPPLIER_KEY allows emissions to be allocated, filtered, grouped, and analysed by supplier in the Logistics Emissions Calculator.
To use SUPPLIER_KEY, add a column to your CSV/Excel file with the header SUPPLIER_KEY and populate it with the key, ID, code, or name you use to identify that organisation.
Required allocation keys
Your organisation can configure which allocation keys are mandatory:
CLIENT_KEY
SUPPLIER_KEY
Both CLIENT_KEY and SUPPLIER_KEY
Every row must contain a value for the key or keys required by your organisation's configuration. Emissions that do not contain the required allocation will be rejected.
CLIENT_KEY and SUPPLIER_KEY describe your direct commercial relationship on the shipment, rather than the type of organisation or necessarily who physically moved the goods. The same organisation can therefore appear as a client on some emissions and a supplier on others.
For more information, including worked examples for shippers, logistics service providers and freight forwarders, see Allocating emissions with CLIENT_KEY and SUPPLIER_KEY.