Skip to content
Navo24 Navo24
POSTAPI key

Calculate shipment CO2e

POSTapi.navo24.com/v1/carbon/calculate

Well-to-wheel CO2e of one shipment with the tank-to-wheel and well-to-tank split, per leg and in total. Distances come from Navo Distance & Time: the real sea route with canals and ECA miles, road and rail networks, air as great circle + 95 km. Every transport_mode and shipping_type of the Freight Rates API is covered. The example is two 40'hc, 36 t of cargo, Shanghai to Rotterdam, with the mode comparison.

Request body

originstringrequired

UN/LOCODE, IATA, city, address or "lat,lng". from is accepted too. Not needed when you send distance_km.

destinationstringrequired

Same formats as origin. to is accepted too.

transport_modestringrequired

Sea, Air, Road or Rail. The same hierarchy as the Freight Rates API.

shipping_typestring

Sea: FCL, LCL, Bulk, RoRo. Air: Aircargo, ULD. Road: FTL, LTL, FCL. Rail: FCL, FWL, FTL, LWL. Defaults: Sea FCL, Air Aircargo, Road FTL, Rail FCL. The old Freight Rates values (FCL, LCL, BULK, RORO, AIR with road_type / rail_type) work too.

transport_unitstring

Container for FCL (20'st, 40'hc... or 20ST, 40HC, 20GP), vehicle for RoRo (Truck, Trailer, Lorry, Van, Car, Plant), ULD type for Air ULD. container_type and vehicle_type are accepted. Default 40'hc / Truck / PMC.

unitsinteger

Number of containers, vehicles or ULDs. Default 1.

weight_kgnumber

Cargo gross mass. Required for LCL, Air, Road FTL/LTL and Rail wagons. Optional for FCL and RoRo (GLEC default load per unit is used and marked cargo_basis: default).

weight_mtnumber

Cargo mass in metric tonnes, for Bulk. Wins over weight_kg.

volume_cbmnumber

Air only: we return chargeable_kg (1:6000) for reference. CO2e is always on actual mass, as ISO 14083 requires.

routing_modestring

Sea legs. safe (default since 27 October 2026): Red Sea closed, Asia, the Gulf and India to Europe round the Cape of Good Hope, as most carriers sail now (about 31% more distance and CO2e on Shanghai to Rotterdam). short: shortest open route via Suez, as in EcoTransIT and most calculators. When the two differ, route_alternative returns the other one.

rail_tractionstring

average (default), electric or diesel.

aircraftstring

Air only: unknown (default, 55% belly / 45% freighter), freighter or belly.

vessel_dwtnumber

Bulk only: the vessel deadweight, picks the GLEC bulk carrier class. Without it the class follows the cargo size (navo_assumption).

distance_kmnumber

Skip routing and use your own distance (one leg of transport_mode). Air adds the GLEC 95 km.

intensity_overrideobject

Primary data from your carrier, g CO2e per t km (per TEU km for Sea FCL) by leg mode: {"SEA": 61.5}. The leg then says source: client primary data.

compareboolean

Also calculate the same cargo by Sea, Rail, Road and Air on the same lane. Adds compare[] with vs_lowest.

pathboolean

Return each leg geometry as [[lat, lng], ...] for a map. Default false.

Response schema

100 fields

Derived from the example response, nested as the JSON is.

dataobject

The payload. Everything an endpoint returns sits under this key.

request_idstring
methodstring

How the position was produced, for example route_reckoning.

factor_setstring
scopestring
queryobject
originstring

Origin code (airport IATA or UN/LOCODE).

destinationstring

Destination code (airport IATA or UN/LOCODE).

transport_modestring

Mode the source named for the move. Null when it named none.

shipping_typestring
transport_unitstring

Third level of the rates transport hierarchy: a container (40'hc), a RoRo vehicle (Truck) or an air ULD (AKE, PMC, PAG). Null for LCL, LTL, LWL, Bulk and Aircargo.

notationstring
unitsnumber
teunumber

Vessel capacity in TEU.

cargo_tnumber
cargo_basisstring
fromobject
namestring

Human-readable name.

locodestring

UN/LOCODE of the place.

kindstring

carrier_event when a carrier filed it, trackingmcp_inference when we derived the step from surrounding events.

country_codestring

ISO 3166-1 alpha-2 country code.

countrystring

Country name.

latnumber

Latitude.

lngnumber

Longitude.

toobject
namestring

Human-readable name.

locodestring

UN/LOCODE of the place.

kindstring

carrier_event when a carrier filed it, trackingmcp_inference when we derived the step from surrounding events.

country_codestring

ISO 3166-1 alpha-2 country code.

countrystring

Country name.

latnumber

Latitude.

lngnumber

Longitude.

totalsobject
co2e_kgobject
wtwnumber
ttwnumber
wttnumber
co2e_tnumber
distance_kmnumber
intensity_g_per_tkmnumber
co2e_kg_per_unitnumber
legsobject[]

The voyage broken into legs. Empty when we cannot yet split it.

legs[]object
transport_modestring

Mode the source named for the move. Null when it named none.

fromobject
namestring

Human-readable name.

locodestring

UN/LOCODE of the place.

kindstring

carrier_event when a carrier filed it, trackingmcp_inference when we derived the step from surrounding events.

country_codestring

ISO 3166-1 alpha-2 country code.

latnumber

Latitude.

lngnumber

Longitude.

toobject
namestring

Human-readable name.

locodestring

UN/LOCODE of the place.

kindstring

carrier_event when a carrier filed it, trackingmcp_inference when we derived the step from surrounding events.

country_codestring

ISO 3166-1 alpha-2 country code.

latnumber

Latitude.

lngnumber

Longitude.

distance_kmnumber
distance_sourcestring
emissionsobject
activitynumber
activity_unitstring
intensityobject
valuenumber
unitstring
classstring
sourcestring

Where the answer on this call came from: direct_carrier or warm_db.

factor_idstring
navo_assumptionboolean
co2e_kgobject
wtwnumber
ttwnumber
wttnumber
notesstring[]

Your own free-text note on this box. Null when you have written none.

routeobject

The legs in order. Each carries its two endpoints, its geometry and its vessel.

labelstring

The event in plain words. A non-actual event is tagged "(planned)".

passagesobject[]
passages[]object
idstring

Stable identifier for the record. On the tracking endpoints this is the container UUID, except on a portfolio summary row, where it is the container number.

namestring

Human-readable name.

ecaobject
nmnumber
non_eca_nmnumber
sharenumber
zonesobject[]
zones[]object
idstring

Stable identifier for the record. On the tracking endpoints this is the container UUID, except on a portfolio summary row, where it is the container number.

namestring

Human-readable name.

nmnumber
took_msnumber
compareobject[]
compare[]object
transport_modestring

Mode the source named for the move. Null when it named none.

notationstring
co2e_kgobject
wtwnumber
ttwnumber
wttnumber
distance_kmnumber
intensity_g_per_tkmnumber
routestring

The legs in order. Each carries its two endpoints, its geometry and its vessel.

statusstring

Current normalised status of the shipment. Ocean lifecycle order: discharged, available, delivered, returned_empty. Two values end a shipment, delivered and returned_empty, and returned_empty outranks delivered.

vs_lowestnumber

Errors

A failure carries { "ok": false, "error": { "code", "message", "severity" } }. Branch on the code, and log the message.

missing_key401

No key in Authorization or x-api-key.

invalid_key401

The key is unknown or revoked.

invalid_transport_mode422

transport_mode is not Sea, Air, Road or Rail.

invalid_shipping_type422

shipping_type does not exist for this mode.

invalid_transport_unit422

Unknown container, RoRo vehicle or ULD.

weight_required422

LCL, Bulk, Air, Road FTL/LTL or a Rail wagon without weight_kg / weight_mt.

location_not_found422

origin or destination could not be resolved.

no_route422

No route by this mode between the points.

rate_limited429

More than 120 requests in one minute for one key.

routing_unavailable502

Distance & Time did not answer. Retry shortly.

Method

ISO 14083:2023 activity based: emissions = activity x intensity, well-to-wheel (WTW = TTW + WTT). Default intensities come from the GLEC Framework v3.2 (Smart Freight Centre, October 2025), Module 2 section 3, each row with its table (factor_set glec-3.2-navo-2026.10). Sea FCL and LCL use the CCWG trade lane of the port pair. Region for road and rail comes from the leg ends. Rows marked navo_assumption are our choice of class where GLEC gives several (LTL, inland vessel size, Ro-Ro size, bulk size without vessel_dwt, part wagon, block train). Carrier primary data always beats a default: send it as intensity_override.

Reporting

Quote the figure with its method, factor_set and distance_source. Results are estimates for Scope 3 category 4 or 9 reporting, not verified carrier figures.

Transport hierarchy and how each type is calculated

transport_mode, then shipping_type, then transport_unit, the same levels as the Freight Rates API. Activity is tonne km (TEU km for Sea FCL) times a GLEC v3.2 default intensity.

transport_modeshipping_typetransport_unitActivity and intensity
SeaFCL20'st, 40'st, 40'hc, 45'hc, 20'rf, 40'rfTEU km x CCWG trade lane intensity (GLEC Tables 18-19, 32 lanes, dry or reefer); industry average 71.7 / 142.3 when the lane is unknown
SeaLCLnonet km x the same trade lane intensity per tonne (10 t per TEU)
SeaBulknonet km x bulk carrier class by vessel_dwt, or by cargo size; weight_mt (GLEC Table 14)
SeaRoRoTruck, Trailer, Lorry, Van, Car, Plantt km (gross) x Ro-Ro intensity, Car = vehicle carrier (GLEC Table 17)
AirAircargononet km, great circle + 95 km, short haul under 1,500 km / long haul (GLEC Table 1); aircraft: unknown, freighter, belly
AirULDAKE, PMC, PAGas Aircargo, weight_kg required
RoadFTLnonet km x artic truck 34-40 t by region: Europe / South America, North America, China, India; Asia and Africa x1.22
RoadLTLnonet km x part load truck by region
RoadFCL20'st, 40'st, 40'hc, 20'rf, 40'rft km (cargo + tare) x container truck by region; reefer x1.12
RailFCL20'st, 40'st, 40'hc, 45'hc, 20'rf, 40'rft km (cargo + tare) x container train (GLEC Tables 4-5), rail_traction; US and India averages; reefer x1.12
RailFWLnonet km x rail intensity by region and traction
RailFTLnoneblock train, rail intensity x0.9
RailLWLnonepart wagon, rail intensity x1.25
curl -X POST 'https://api.navo24.com/v1/carbon/calculate' \
  -H "Authorization: Bearer tmcp_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"origin":"CNSHA","destination":"NLRTM","transport_mode":"Sea","shipping_type":"FCL","transport_unit":"40'hc","units":2,"weight_kg":36000,"compare":true}'
Response
{
  "data": {
    "request_id": "co2_3b9e0c51d2a84f17",
    "method": "ISO 14083:2023, GLEC Framework v3.2 (Oct 2025) Module 2 default intensities, well-to-wheel",
    "factor_set": "glec-3.2-navo-2026.10",
    "scope": "Scope 3, category 4/9 (upstream / downstream transport)",
    "query": {
      "origin": "CNSHA",
      "destination": "NLRTM",
      "transport_mode": "Sea",
      "shipping_type": "FCL",
      "transport_unit": "40'hc",
      "notation": "Sea-FCL-40'hc",
      "units": 2,
      "teu": 4.0,
      "cargo_t": 36.0,
      "cargo_basis": "declared"
    },
    "from": {
      "name": "Shanghai",
      "locode": "CNSHA",
      "kind": "port",
      "country_code": "CN",
      "country": "China",
      "lat": 31.40009,
      "lng": 121.49711
    },
    "to": {
      "name": "Rotterdam",
      "locode": "NLRTM",
      "kind": "port",
      "country_code": "NL",
      "country": "Netherlands",
      "lat": 51.90438,
      "lng": 4.44245
    },
    "totals": {
      "co2e_kg": {
        "wtw": 3686.7,
        "ttw": 3034.15,
        "wtt": 652.55
      },
      "co2e_t": 3.687,
      "distance_km": 19610.1,
      "intensity_g_per_tkm": 5.22,
      "co2e_kg_per_unit": 1843.35
    },
    "legs": [
      {
        "transport_mode": "SEA",
        "from": {
          "name": "Shanghai",
          "locode": "CNSHA",
          "kind": "port",
          "country_code": "CN",
          "lat": 31.40009,
          "lng": 121.49711
        },
        "to": {
          "name": "Rotterdam",
          "locode": "NLRTM",
          "kind": "port",
          "country_code": "NL",
          "lat": 51.90438,
          "lng": 4.44245
        },
        "distance_km": 19610.1,
        "distance_source": "Navo Distance & Time, sea route",
        "emissions": {
          "activity": 78440.4,
          "activity_unit": "TEU km",
          "intensity": {
            "value": 47.0,
            "unit": "g CO2e / TEU km",
            "class": "Container ship, Asia to-from North Europe (dry)",
            "source": "GLEC Framework v3.2, Module 2 §3, Table 18, trade lane Asia to-from North Europe, Dry",
            "factor_id": "sea_lane_asia_neu_dry",
            "navo_assumption": false
          },
          "co2e_kg": {
            "wtw": 3686.7,
            "ttw": 3034.15,
            "wtt": 652.55
          },
          "notes": [
            "trade lane Asia to-from North Europe"
          ]
        }
      }
    ],
    "route": {
      "label": "Sea",
      "passages": [
        {
          "id": "suez",
          "name": "Suez Canal"
        },
        {
          "id": "malacca",
          "name": "Strait of Malacca"
        },
        {
          "id": "babalmandab",
          "name": "Bab-el-Mandeb"
        },
        {
          "id": "gibraltar",
          "name": "Strait of Gibraltar"
        }
      ],
      "eca": {
        "nm": 2340.5,
        "non_eca_nm": 8248.1,
        "share": 0.221,
        "zones": [
          {
            "id": "north-sea",
            "name": "North Sea ECA",
            "nm": 405.7
          }
        ]
      }
    },
    "took_ms": 0,
    "compare": [
      {
        "transport_mode": "Sea",
        "notation": "Sea-FCL-40'hc",
        "co2e_kg": {
          "wtw": 3686.7,
          "ttw": 3034.15,
          "wtt": 652.55
        },
        "distance_km": 19610.1,
        "intensity_g_per_tkm": 5.22,
        "route": "Sea",
        "status": "ok",
        "vs_lowest": 1.0
      },
      {
        "transport_mode": "Rail",
        "notation": "Rail-FCL-40'hc",
        "co2e_kg": {
          "wtw": 8239.83,
          "ttw": 4012.8,
          "wtt": 4227.03
        },
        "distance_km": 11001.4,
        "intensity_g_per_tkm": 20.81,
        "route": "Rail",
        "status": "ok",
        "vs_lowest": 2.24
      },
      {
        "transport_mode": "Road",
        "notation": "Road-FCL-40'hc",
        "co2e_kg": {
          "wtw": 38120.04,
          "ttw": 29238.07,
          "wtt": 8881.97
        },
        "distance_km": 10763.3,
        "intensity_g_per_tkm": 98.38,
        "route": "Road",
        "status": "ok",
        "vs_lowest": 10.34
      },
      {
        "transport_mode": "Air",
        "notation": "Air-Aircargo",
        "co2e_kg": {
          "wtw": 255810.22,
          "ttw": 212066.67,
          "wtt": 43743.55
        },
        "distance_km": 9017.6,
        "intensity_g_per_tkm": 788.0,
        "route": "Air",
        "status": "ok",
        "vs_lowest": 69.39
      }
    ]
  }
}