🎯 What this guide is about

This guide answers a frequently asked question: is the carbon benefit of a fuel switch worth the cost or operational constraint?

Fuel switches are often easier and faster to implement than full modal shifts. They offer a practical way to reduce freight emissions without redesigning the entire transport flow.

Typical fuel switch scenarios include:

Diesel → Electric (road)
Diesel → Biodiesel blends (road)
Standard bunker → Biofuels (ocean)

In this guide, we’ll simulate these options by sending one request per fuel type, in the Shipment API.

🧠 Scenarios covered

In this guide we’ll look at:

Fuel switch for road: comparing diesel, electric, B100, B50, and LNG.
Fuel switch for sea: comparing UCO and BioLNG.

🛠 Steps overview and prerequisites

Build a payload for your shipment (orders + transportChainElements)
Prepare mode-specific details (fuelType at least)
POST to the /shipment/v2/report/co2 endpoint
Parse the co2e.total value from the JSON response
Repeat for each fuel you'd like to compare with.

Prerequisites

✅ Valid API key for Shipment API v2.1 (ISO 14083-compliant).
⚠️ Note that multi-leg requests return emissions for hubs. Run one request per scenario for easier comparisons.

🧑‍💻Scenarios

🚛 Road example

Compares CO₂ emissions for the same road route using different fuel types.

Scenario: Compare Diesel, Electric, B100, B50, and LNG options for 5 tonnes of cargo moving from Paris to Hamburg, using a 33-tonne truck.

⚙️ Example payload

 {
  "orders": [
    {
      "type": "PARCEL",
      "weight": 5000
    }
  ],
  "transportChainElements": [
    {
      "type": "leg",
      "from": "FRPAR",
      "to": "DEHAM",
      "mode": "road",
      "details": {
        "truckSize": 33,
        "fuelType": "DIESEL"
      }
    }
  ]
}

⚙️ Example request

We now loop over multiple fuel types to compare their impact on the same route.

API_KEY = 'your-api-key'
BASE_URL = 'https://api.searoutes.com/shipment/v2/report/co2'

from_location = "FRPAR"
to_location = "DEHAM"

fuel_types = ("DIESEL", "ELEC", "BIODIESEL", "B50", "LNG")

def compare_road_with_fuel_switch(body):
    results = dict()
    headers = {'x-api-key': API_KEY, 'Content-Type': 'application/json', 'Accept-Version': '2.1'}
    for fuel_type in fuel_types:
        # Add the road details with the corresponding fuel
        add_road_details_to_body(fuel_type, body)
        # Get the response
        response = requests.post(BASE_URL, headers=headers, json=body)
        data = response.json()
        # Save to the total CO2
        results[fuel_type] = data["co2e"]["total"]
    return results

def add_road_details_to_body(fuel_type, body):
    road_details = {
        "truckSize": 33,
        "fuelType": fuel_type
    }
    body["transportChainElements"][0]["mode"] = "road"
    body["transportChainElements"][0]["details"] = road_details

def create_base_body(from_location, to_location):
    base_body = {
        "orders": [
            {
                "type": "parcel",
                "weight": 5000
            }
        ],
        "transportChainElements": [
            {
                "from": from_location,
                "to": to_location,
                "type": "leg",
            }
        ]
    }
    return base_body


print(compare_road_with_fuel_switch(create_base_body(from_location, to_location)))

✅ Example results

This example highlights:

the much better result from electric trucks, due to the French electricity network being little carbon-intensive;
B100 outperforms B50, and B50 performs better than LNG.

Fuel	gCO₂e WTW
DIESEL	541,520
ELEC	39,522
B100	166,867
B50	369,893
LNG	449,156

🚢 Sea example

Compares CO₂ emissions for the same sea route using different fuel types.

Scenario: Move one 40-foot container from La Spezia to Antwerp on the MSC MADELEINE, testing UCO and BioLNG options.

Industry context

In most cases, biofuel offers in ocean shipping are based on a book-and-claim system: the actual vessel transporting your cargo is not bunkered with the biofuel. Instead, the carrier uses biofuel elsewhere in their fleet, and attributes its environmental benefit to your journey. A third party certifies that this claim is valid and not double-counted.
UCO (used cooking oil) roughly corresponds to the ~85% savings offers sold by most major carriers.
BioLNG-based offer roughly corresponds to the ~25% offers sold by those same carriers.

⚙️ Example payload

{
  "orders": [
    {
      "type": "FCL",
      "containerSizeTypeCode": "40HC",
      "nContainers": 1,
      "weight": 10000
    }
  ],
  "transportChainElements": [
    {
      "type": "leg",
      "mode": "sea",
      "from": "ITSPE",
      "to": "BEANR",
      "details": {
        "vessel": {
          "name": "MSC MADELEINE"
        },
        "fuelType": "UCO"
      }
    }
  ]
}

Note: for sea, fuel switch requires specifying a vessel name or imo. Carrier-only or default values do not allow fuel override:

passing solely carrier data will average the performance over the carrier's operated fleet, each one computed with its own specific fuel
passing default data uses Clean Cargo Working Group averages, an industry average that also regroups several fuel emission factors.

⚙️ Example request

API_KEY = 'your-api-key'
BASE_URL = 'https://api.searoutes.com/shipment/v2/report/co2'

from_location = "ITSPE"
to_location = "BEANR"
vessel_imo = None
vessel_name = "MSC MADELEINE" # imo is preferred vs name for more accurate search

fuel_types = ("UCO", "BIOLNG")

def compare_sea_with_fuel_switch(body):
    results = dict()
    headers = {'x-api-key': API_KEY, 'Content-Type': 'application/json', 'Accept-Version': '2.1'}
    for fuel_type in fuel_types:
        # Add the sea details with the corresponding fuel
        add_sea_details_to_body(fuel_type, body)
        # Get the response
        response = requests.post(BASE_URL, headers=headers, json=body)
        data = response.json()
        # Save to the total CO2
        results[fuel_type] = data["co2e"]["total"]
    return results

def add_sea_details_to_body(fuel_type, body):
    sea_details = {
        "vessel": {

        },
        "fuelType": fuel_type
    }
    if vessel_imo is not None:
        sea_details["vessel"]["imo"] = vessel_imo
    elif vessel_name is not None:
        sea_details["vessel"]["name"] = vessel_name
    body["transportChainElements"][0]["mode"] = "sea"
    body["transportChainElements"][0]["details"] = sea_details

def create_base_body(from_location, to_location):
    base_body = {
        "orders": [
            {
                "type": "FCL",
                "nContainers": 1,
                "containerSizeTypeCode": "40HC",
                "weight": 10000
            }
        ],
        "transportChainElements": [
            {
                "from": from_location,
                "to": to_location,
                "type": "leg",
            }
        ]
    }
    return base_body


print(compare_sea_with_fuel_switch(create_base_body(from_location, to_location)))

✅ Example results

As we can see, UCO delivers the most impactful CO₂ savings, while BioLNG offers a more moderate reduction.

Fuel	gCO₂e WTW
UCO	194,426
BIOLNG	759,475

⏭️ What’s next?

🧪 Test it and let us know if you have any feedback!
📖 Check the full Shipment API v2.1 docs for all supported parameters.
🤝 Reach out to our [email protected] — we’d love your feedback on this guide or ideas for the next one!