VerifiedCarrier CO2 — EU Ship Emissions League Tables (EMSA THETIS-MRV)

Audit-ready EU shipping CO₂ league tables and Scope 3 export rows built strictly from the official EMSA THETIS-MRV public publication of information (Regulation (EU) 2015/757, Art. 21). The Actor downloads the official per-period spreadsheet publication, normalizes the verified carbon-intensity indicators into like-for-like ship-type peer groups, ranks ships and carriers with percentile context, flags low-coverage fleets, and emits provenance-linked records that cite the exact publication version and generation date behind every figure.

Informational analytics only. Outputs are NOT compliance, legal, regulatory, scientific or financial advice, are not official figures, and must be verified against the official source before any regulatory use. Coverage reflects the EU MRV scope only (voyages touching EU/EEA ports), which limits comparability with global activity.

Who it is for

• Sustainability/ESG managers preparing CSRD-aligned Scope 3 (Cat. 4/9) inventories who need officially sourced, citable carrier carbon-intensity figures instead of carrier marketing sheets.
• Freight procurement teams benchmarking carriers during tenders on like-for-like peer groups.
• Consultants and auditors needing reproducible exports with publication-version provenance.

What one run produces

Record type	Meaning
run_summary	Always first: mode, metric, periods processed with official version/generation-date fingerprints, coverage counts, notes, disclaimers.
carrier_rank	Carrier league table per ship-type peer group: CO₂-weighted mean intensity, fleet size, ships ranked vs missing-indicator, rank + percentile. Emitted where EMSA publishes company attribution (FY2024+).
ship_rank	Ship league rows within peer groups: published indicator value, total verified CO₂, technical efficiency label, rank + percentile.
period_update	Incremental mode: emitted when EMSA republishes a period under a new version.

Every ranked record carries provenance (source URLs, official disclaimer, retrieval timestamp), periodVersion, and generationDate, so any figure in a customer's audit file can be traced to the exact official publication it came from.

Methodology (documented, deterministic)

1. Source. The official listing endpoint enumerates the published spreadsheet documents; the newest version per requested reporting period is downloaded (XLSX). No HTML scraping, no login, no circumvention — this is the portal's own advertised export channel.
2. Normalization. Columns are mapped by normalized header text (never fixed positions), so pre-ETS ("Annual average CO₂ emissions per transport work …") and post-ETS layouts both resolve. Published sentinel strings ("N/A", "Division by zero!") count as missing values, never zero.
3. Peer groups. Ships compete only within their own ship type. Ranks ascend by the selected verified indicator (rank 1 = lowest intensity). percentileWorseThan = share of peers with equal-or-worse intensity (0 = cleanest).
4. Carrier aggregation (FY2024+). Members of a company inside a peer group yield a CO₂-weighted mean indicator plus a simple median. Companies with fewer than minimumCarrierFleetSize rankable ships stay visible but receive no rank (visible de-ranking instead of misleading small-sample comparisons).
5. Coverage honesty. Ships without a usable published indicator are counted (shipsMissingIndicator, missingMetricValues) and never silently compared.

Input (see input schema for all options)

{
  "mode": "full",
  "reportingPeriods": [2024],
  "metric": "co2_per_transport_work_mass",
  "topKPerLeagueTable": 25,
  "minimumCarrierFleetSize": 5,
  "companyWatchlist": ["Maersk", "CMA SHIPS"]
}

• reportingPeriods: up to 3 official periods per run (2018–2025 as published).
• metric: mass / dwt / pax / freight / volume transport-work intensities, or CO₂-per-distance.
• companyWatchlist: matched companies/ships are always emitted and flagged watchlistMatch=true — even beyond the top-K cut.
• mode: incremental re-downloads nothing while the official publication fingerprint is unchanged; a republished period emits period_update plus fresh tables.

A default run downloads one ~9 MB official workbook and finishes comfortably within minutes; incremental unchanged runs make exactly one small API call. Incremental state persists in the named key-value store verified-carrier-co2-state (key state-v1), which survives across runs — the platform-scoped default store is wiped per run by design.

Honest scope limits

• Carrier rankings need FY2024+. EMSA's public publication attributes an ISM company to each ship only from the FY2024 publication onwards; earlier periods get ship-level tables only. This is disclosed in every run summary rather than approximated.
• Partial-period publications (e.g. a running FY2025 file) are marked partialPeriod: true.
• Percentiles describe position within the EU MRV-reporting universe of that peer group — not global fleet efficiency.

Attribution & terms

Data: © European Maritime Safety Agency (EMSA) THETIS-MRV public publication under Regulation (EU) 2015/757 Art. 21; data entered by companies and verified by accredited verifiers. The official source disclaimer is embedded verbatim in every run summary. VerifiedCarrier CO2 is an independent analytics Actor, not affiliated with EMSA or the European Commission. Source verification notes: see docs/SOURCE-VERIFICATION.md.

Development

npm install
npm run lint && npm run typecheck && npm run build
npm test                 # unit + integration + adversarial + schema tests
npm run test:smoke       # live-source smoke (hits real THETIS-MRV endpoints)
npm run smoke:local      # full local Actor run against the real source

Node.js 20+. Apache-licensed SheetJS is used for XLSX parsing; all other logic is local to src/.