carbon_footprint
Compute CO2e footprint and EU-ETS carbon cost for a shipment lane, comparing ocean, air, and sea-air modes with per-leg breakdown and vessel-class intensity.
Instructions
Compute the CO2e CARBON FOOTPRINT of a shipment and the EU-ETS carbon COST for a lane — the Scope-3 (upstream transport) number importers increasingly must report, and the maritime carbon cost they now must pay on EU-touching lanes. The rate tools price the money; this prices the CARBON. Returns the WELL-TO-WAKE (WTW) kg CO2e of the move computed the GLEC Framework / ISO 14083 way — grams CO2e per TONNE-KILOMETRE × the routed distance × the cargo mass — with a per-LEG breakdown (drayage + main sea/air leg) and the well-to-tank vs tank-to-wake split that reporting frameworks ask for. Ocean intensity is taken by VESSEL CLASS (a ULCV moves a tonne-km for a fraction of a feeder's gCO2e/t-km — the economy-of-scale effect a naïve estimate misses); the engine picks the corridor's mainline class and lengthens the sea distance when a lane is Cape-of-Good-Hope diverted (more km → more CO2e). It puts the THREE modes side by side — OCEAN vs AIR vs SEA-AIR — on the same lane & cargo, surfacing that air emits roughly 10-50× the ocean footprint per tonne-km (the central ESG-vs-speed trade-off, linking to compare_modes), with sea-air as the carbon-smart middle. For lanes that touch an EU/EEA port it computes the EU-ETS maritime carbon COST: the voyage CO2 in scope (100% intra-EU, 50% for an EU↔non-EU voyage) × the year's phase-in (2024 40% → 2025 70% → 2026 100%) × the EUA market price — the surcharge carriers now pass to cargo. A lane that doesn't touch the EU (e.g. Asia→US) is correctly OUT of scope (no ETS). It also clarifies FuelEU Maritime and — honestly — that CBAM taxes the PRODUCT's embedded carbon, NOT the freight (the confusion importers keep making). Every emission factor and the EUA price are MODELED bands tagged typical/modeled (regla 7) — indicative footprinting & carbon-cost modeling, NOT an audited per-vessel carbon statement or a filed surcharge. PREMIUM: pay per call with x402 (USDC on Base) or set a prepaid key (FREIGHT_PULSE_KEY). Same UN/LOCODE port normalization as get_spot_rate.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| origin_port | Yes | Origin port (city name, UN/LOCODE, or 'City, Country'). Same resolution as get_spot_rate. The origin COUNTRY drives EU-ETS scope. | |
| dest_port | Yes | Destination port (city name, UN/LOCODE, or 'City, Country'). The destination COUNTRY drives EU-ETS scope (touching the EU/EEA brings the voyage into scope). | |
| container_type | No | Container size '20ft'/'40ft'/'40HC'. Optional; defaults to '40ft'. Drives the modeled typical laden cargo mass when no weight is given. | |
| ship_date | No | Intended ship date (ISO 'YYYY-MM-DD'). The YEAR drives the EU-ETS phase-in (2024 40%, 2025 70%, 2026+ 100%). Optional; defaults to today. | |
| weight_kg | No | Actual cargo gross weight in kg. Strongly recommended — emissions are per tonne-km, so the real mass sharpens the footprint and the EU-ETS cost. If omitted, a modeled typical laden mass for the container is used. | |
| volume_m3 | No | Shipment volume in m³. Used for the AIR mode's IATA chargeable mass (max of actual and volumetric @167 kg/m³). Optional. | |
| band | No | Emission-factor band to report: 'low', 'typical' or 'high'. Optional; default 'typical' (factors are honest bands, not a single audited number). | |
| eua_price_eur | No | Override the EUA (EU Allowance) market price in €/tonne for the EU-ETS cost. Optional; defaults to a modeled typical (~€75) within a €55-100 band. | |
| air_role | No | Air emission factor role: 'freighter' (default, higher intensity) or 'belly' (passenger-jet hold, lower allocation). Optional. |