Calculate Freight Emissions

<span class="api-method api-method-get">GET</span> /v1/freight/emissions

Calculate CO2e emissions for freight transport between two locations.

Request

Required Parameters

Location Parameters

Transport Parameters

Service Parameters

Override Parameters

Output Parameters

Transport Modes

Fuel Sources

Vehicle Types

Road

Sea

Air

Response

{
  "data": {
    "type": "freight_emission",
    "id": "f33ee387-c1b3-4941-b5f1-9a61f144e1f2",
    "attributes": {
      "emissions": {
        "co2e": 156.78,
        "co2e_unit": "kg",
        "co2e_calculation_method": "ipcc_ar6_gwp100",
        "co2e_grams": 156780,
        "energy_usage_mj": 2450.5,
        "lifecycle_breakdown": {
          "unit": "kg",
          "vehicle_operation": 125.42,
          "energy_provision": 31.36
        },
        "ghg_protocol_scopes": {
          "asset_owner": {
            "scope_1": 125.42,
            "scope_2": 0,
            "scope_3_category_3": 31.36
          },
          "freight_buyer": {
            "scope_3_category_4": 156.78
          }
        },
        "equivalents": {
          "trees_yearly": {
            "value": 7.47,
            "label": "trees needed to absorb this CO2 in a year"
          },
          "driving_km": {
            "value": 922.8,
            "label": "km driven in an average car"
          }
        },
        "source_trail": [
          {
            "data_category": "emission_factor",
            "name": "Articulated HGV - Diesel",
            "source": "GLEC",
            "source_dataset": "Default fuel efficiency and GHG emission intensity values v3.1",
            "year": "2025",
            "region": "GLOBAL"
          }
        ]
      },
      "cargo": {
        "weight_input": 5000,
        "unit_input": "kg",
        "weight_normalized_kg": 5000,
        "service_type": "shared",
        "cargo_tonnes": 5
      },
      "vehicle": {
        "requested": "average",
        "class_used": "Articulated HGV - Diesel",
        "fuel_source": "diesel",
        "empty_return_included": false
      },
      "route": {
        "type": "direct",
        "total_distance_km": 1098,
        "transport_mode": "road",
        "origin": {
          "input": "London",
          "resolved": "London, Greater London, England, United Kingdom",
          "country_code": "GB",
          "lat": 51.5074,
          "lon": -0.1278,
          "confidence_score": 0.95
        },
        "destination": {
          "input": "Berlin",
          "resolved": "Berlin, Germany",
          "country_code": "DE",
          "lat": 52.52,
          "lon": 13.405,
          "confidence_score": 0.95
        },
        "waypoints": [
          { "lat": 51.27891, "lon": 1.07812 },
          { "lat": 50.95142, "lon": 1.85832 },
          { "lat": 50.63178, "lon": 3.05712 }
        ],
        "duration_seconds": 42979,
        "duration_formatted": "11h 56m"
      },
      "geography": {
        "origin_country": "GB",
        "destination_country": "DE",
        "transit_countries": ["GB", "FR", "BE", "DE"],
        "border_crossing": true
      },
      "notices": []
    }
  },
  "meta": {
    "methodology": "GLEC Framework v3.1",
    "emission_factors_year": 2025,
    "standards_compliance": {
      "ISO_14083": true,
      "EN_16258": true,
      "GHG_Protocol": "Scope 3 Category 4"
    },
    "distance_method": "road_routing",
    "calculated_at": "2026-02-07T12:00:00Z"
  }
}

Response Fields

emissions

cargo

route

Examples

Basic Road Freight

curl "https://api.emissions.dev/v1/freight/emissions?\
origin_country=GB&\
destination_country=FR&\
weight=1000" \
  -H "Authorization: Bearer em_live_xxxx"

With Specific Locations

curl "https://api.emissions.dev/v1/freight/emissions?\
origin_country=GB&\
origin_location=Sheffield&\
destination_country=DE&\
destination_location=Munich&\
weight=2500&\
unit=kg" \
  -H "Authorization: Bearer em_live_xxxx"

International Sea Freight

curl "https://api.emissions.dev/v1/freight/emissions?\
origin_country=CN&\
origin_location=Shanghai&\
destination_country=GB&\
destination_location=Felixstowe&\
weight=20000&\
transport_mode=sea" \
  -H "Authorization: Bearer em_live_xxxx"

Electric Vehicle

curl "https://api.emissions.dev/v1/freight/emissions?\
origin_country=NO&\
origin_location=Oslo&\
destination_country=NO&\
destination_location=Bergen&\
weight=500&\
fuel_source=electric" \
  -H "Authorization: Bearer em_live_xxxx"

Refrigerated Transport

curl "https://api.emissions.dev/v1/freight/emissions?\
origin_country=ES&\
origin_location=Valencia&\
destination_country=GB&\
destination_location=London&\
weight=15000&\
refrigerated=true" \
  -H "Authorization: Bearer em_live_xxxx"

Air Freight

curl "https://api.emissions.dev/v1/freight/emissions?\
origin_country=GB&\
origin_location=London&\
destination_country=US&\
destination_location=New+York&\
weight=100&\
transport_mode=air" \
  -H "Authorization: Bearer em_live_xxxx"

With Equivalents

curl "https://api.emissions.dev/v1/freight/emissions?\
origin_country=GB&\
destination_country=FR&\
weight=1000&\
equivalents=true" \
  -H "Authorization: Bearer em_live_xxxx"

With Detailed Route (Polyline)

Request a full encoded polyline for smooth map rendering of road routes:

curl "https://api.emissions.dev/v1/freight/emissions?\
origin_country=GB&\
origin_location=London&\
destination_country=DE&\
destination_location=Berlin&\
weight=5000&\
detailed_route=true" \
  -H "Authorization: Bearer em_live_xxxx"

When detailed_route=true, the route object includes a Google-encoded polyline (precision 5) alongside the standard sampled waypoints:

"route": {
  "waypoints": [...],
  "duration_seconds": 42979,
  "duration_formatted": "11h 56m",
  "polyline": "cakyH`~WACAKAKAO?M@K@IBIBGBGBCBC...",
  "polyline_precision": 5,
  "attribution": "Route data © OpenStreetMap contributors"
}

Decode with any standard polyline library:

// Leaflet (via leaflet-polyline plugin)
const route = L.Polyline.fromEncoded(response.route.polyline);
route.addTo(map);

// Google Maps
const path = google.maps.geometry.encoding.decodePath(response.route.polyline);

// Python
import polyline
coords = polyline.decode(response['route']['polyline'])

Note: The polyline is only available for road mode. Sea, air, and rail routes return null for the polyline field. When displaying route geometry, you must include the attribution string as required by the data licence.

Code Examples

JavaScript

const response = await fetch(
  'https://api.emissions.dev/v1/freight/emissions?' + new URLSearchParams({
    origin_country: 'GB',
    destination_country: 'DE',
    origin_location: 'London',
    destination_location: 'Berlin',
    weight: 5000
  }),
  {
    headers: {
      'Authorization': `Bearer ${process.env.EMISSIONS_API_KEY}`
    }
  }
);

const data = await response.json();
console.log(`Emissions: ${data.data.attributes.emissions.co2e} kg CO2e`);
console.log(`Distance: ${data.data.attributes.route.total_distance_km} km`);

Python

import requests

response = requests.get(
    'https://api.emissions.dev/v1/freight/emissions',
    params={
        'origin_country': 'GB',
        'destination_country': 'DE',
        'origin_location': 'London',
        'destination_location': 'Berlin',
        'weight': 5000
    },
    headers={
        'Authorization': f'Bearer {api_key}'
    }
)

data = response.json()
emissions = data['data']['attributes']['emissions']
print(f"Emissions: {emissions['co2e']} kg CO2e")

PHP

$response = Http::withToken($apiKey)
    ->get('https://api.emissions.dev/v1/freight/emissions', [
        'origin_country' => 'GB',
        'destination_country' => 'DE',
        'origin_location' => 'London',
        'destination_location' => 'Berlin',
        'weight' => 5000,
    ]);

$data = $response->json();
$emissions = $data['data']['attributes']['emissions'];
echo "Emissions: {$emissions['co2e']} kg CO2e";

Errors

Invalid Route

{
  "error": {
    "code": "invalid_route",
    "message": "Cannot use 'road' transport between GB and US. These countries are not connected by land.",
    "status": 422,
    "available_modes": ["air", "sea"]
  }
}

Invalid Country

{
  "error": {
    "code": "invalid_origin_country",
    "message": "Country code 'XX' not recognised. Use ISO 3166-1 alpha-2 codes.",
    "status": 422
  }
}

Missing Weight

{
  "error": {
    "code": "validation_error",
    "message": "The weight field is required.",
    "field": "weight",
    "status": 422
  }
}