UN/LOCODE Data Model Extension (Version 0.1.0-20230522)

1. Introduction

This document contains the necessary technical foundation for the UN/LOCODE extension to the Pathfinder Framework Data Model.

The Pathfinder Framework Data Model allows for the interoperable exchange of product footprint data. This includes the product’s carbon footprint, represented in the Data Model as a CarbonFootprint. Each CarbonFootprint is scoped by Geography, specified (at maximum resolution) as a ISO 3166-2 country subdivision.

In some cases, the current resolution is insuficient and a more precise, hopefully plant-level, geographic specification would be recommended. The UN/LOCODE Data Model Extension aims at providing precisely the required level of granularity, using an international coding scheme that is public and can be integrated into solutions.

As its name suggests (United Nations Code for Trade and Transport Locations), UN/LOCODE has the advantage of being maintained by the United Nations, ensuring maintenance and data quality. A list of all UN/LOCODEs can be found here.

2. Data Model Extension

The UN/LOCODE data model extension adds four properties to the ProductFootprint (see § 3 Example ProductFootprint with extension):

unlocode

coordinates

name

remarks

2.1. Data Type: UNLOCODE

A UN/LOCODE is a string and MUST be composed by a 2-character country code and a 3-character location.

Country codes are exclusively constituted by capital letters from A to Z.

Locations are primarily composed by capital letters from A to Z but might, when the letter combinations have been exhausted, include numerals from 2 to 9.

An UN/LOCODE MUST NOT include whitespace.

"ZMCHZ"

2.2. Data Type: Coordinates

Coordinates is a string and MUST be composed by a latitude and a longitude separated by a whitespace.

latitude

Four numerals from 0 to 9 (two for degrees and two for minutes) followed by either the letter N (for North) or S (for South).

longitude

Five numerals from 0 to 9 (three for degrees and two for minutes) followed by either the letter W (for West) or E (for East).

"0917S 03220E"

2.3. Properties

3. Example ProductFootprint with extension

{
    "id": "d9be4477-e351-45b3-acd9-e1da05e6f633",
    "specVersion": "2.0.0",
    "version": 0,
    "created": "2022-05-22T21:47:32Z",
    "companyName": "My Corp",
    "companyIds": [
        "urn:uuid:51131FB5-42A2-4267-A402-0ECFEFAD1619",
        "urn:epc:id:sgln:4063973.00000.8"
    ],
    "productDescription": "Cote’d Or Ethanol",
    "productIds": [
        "urn:gtin:4712345060507"
    ],
    "productCategoryCpc": "3342",
    "productNameCompany": "Green Ethanol",
    "comment": "",
    "pcf": {
        "declaredUnit": "liter",
        "unitaryProductAmount": "12.0",
        "fossilGhgEmissions": "0.123",
        "biogenicEmissions": {
            "landUseEmissions": "0.001",
            "otherEmissions": "0"
        },
        "biogenicCarbonContent": "0.0",
        "reportingPeriodStart": "2021-01-01T00:00:00Z",
        "reportingPeriodEnd": "2022-01-01T00:00:00Z",
        "geographyCountry": "ZM",
        "primaryDataShare": 56.12,
        "emissionFactorSources": [
            {
                "name": "Ecoinvent",
                "version":
                "1.2.3"
            }
        ],
        "boundaryProcessesDescription": "End-of-life included",
        "crossSectoralStandardsUsed": [
            "GHG Protocol Product standard"
        ],
        "productOrSectorSpecificRules": [
            {
                "operator": "EPD International",
                "ruleNames": [
                    "ABC 2021"
                ]
            }
        ]
    },
    "extensions": [
        {
            "specVersion": "2.0.0",
            "dataSchema": "https://github.com/sine-fdn/locode-extension/blob/main/locode_schema.json",
            "data": {
              "unlocode": "ZMCHZ",
              "coordinates": "0917S 03220E",
              "name": "Chozi"
            }
        }
    ]
}