Checklist
Here's a quick checklist for your files before you try importing:
Filename is valid
File is ideally UTF-8 encoded but Pledge 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)
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, there will be different fields which are deemed to be mandatory or optional.
A value must be present for fields that are mandatory and a value can be provided for non-mandatory fields or left empty.
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 Pledge 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 Pledge app.
WARNING: Do not send any PII as metadata 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 (or are expected to have, in future versions) additional significance and the contents of those fields, if present, may be validated accordingly
CLIENT_KEY
CLIENT_KEY can be used to provide a key, id or code for a client that the emissions should be allocated to if you. Therefore, providing a value for CLIENT_KEY will allow the filtering and grouping of emissions data by client in the Pledge app as a first class concept.
To use CLIENT_KEY, simply add another column into your CSV/Excel file with the header of CLIENT_KEY just like any other metadata.