Calculate Fuel Emissions

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

Calculate CO2e emissions from direct fuel combustion. Returns Scope 1 emissions with individual CO₂, CH₄, and N₂O breakdown.

Request

Required Parameters

Parameter	Type	Description
`fuel_type`	string	Fuel type identifier (e.g., `natural_gas`, `diesel`, `hvo`)
`amount`	number	Quantity of fuel consumed (minimum 0.001)

Optional Parameters

Parameter	Type	Default	Description
`unit`	string	Auto	Unit of measurement. Defaults to the most common unit for the fuel type
`include_wtt`	boolean	`true`	Include Well-to-Tank upstream emissions (Scope 3 Category 3)
`equivalents`	boolean	`false`	Include real-world equivalents

Fuel Types

Gaseous Fuels

`fuel_type`	Label	Available Units	Default Unit
`natural_gas`	Natural Gas	`kwh`, `therm`, `m3`	`kwh`
`lpg`	LPG (Liquefied Petroleum Gas)	`kwh`, `litre`, `kg`	`litre`
`cng`	CNG (Compressed Natural Gas)	`kwh`, `kg`	`kg`
`biogas`	Biogas / Biomethane	`kwh`	`kwh`

Liquid Fuels

`fuel_type`	Label	Available Units	Default Unit
`diesel`	Diesel (Gas Oil)	`kwh`, `litre`	`litre`
`petrol`	Petrol (Gasoline)	`kwh`, `litre`	`litre`
`kerosene`	Burning Oil / Kerosene	`kwh`, `litre`	`litre`
`fuel_oil`	Fuel Oil (Heavy)	`kwh`, `litre`	`litre`
`red_diesel`	Gas Oil (Red Diesel / Off-road)	`kwh`, `litre`	`litre`

Biofuels

`fuel_type`	Label	Available Units	Default Unit
`biodiesel`	Biodiesel (B100 / FAME)	`litre`	`litre`
`hvo`	HVO (Hydrotreated Vegetable Oil)	`litre`	`litre`
`bioethanol`	Bioethanol	`litre`	`litre`
`wood_logs`	Wood Logs	`kwh`, `kg`	`kg`
`wood_pellets`	Wood Pellets	`kwh`, `kg`	`kg`

Solid Fuels

`fuel_type`	Label	Available Units	Default Unit
`coal_industrial`	Coal (Industrial)	`kwh`, `kg`	`kg`
`coal_domestic`	Coal (Domestic / Household)	`kwh`, `kg`	`kg`

Response

Full Response Example

{
  "data": {
    "type": "fuel_emission",
    "id": "c9f3a5b2-4d6e-5f7a-b8c9-0d1e2f3a4b5c",
    "attributes": {
      "emissions": {
        "co2e": 3152.5,
        "co2e_unit": "kg",
        "co2e_calculation_method": "ipcc_ar6_gwp100",
        "co2e_grams": 3152500,
        "breakdown": {
          "direct_co2e": 2512.1,
          "direct_co2": 2494.6,
          "direct_ch4": 0.11,
          "direct_n2o": 16.4,
          "wtt_co2e": 640.4,
          "unit": "kg"
        },
        "ghg_protocol_scopes": {
          "scope_1": 2512.1,
          "scope_3_category_3": 640.4
        },
        "equivalents": {
          "trees_yearly": {
            "value": 143,
            "label": "trees needed to absorb this CO₂ in a year"
          },
          "driving_km": {
            "value": 19703,
            "label": "km driven in an average car"
          }
        },
        "source_trail": [
          {
            "data_category": "emission_factor",
            "name": "Diesel (Gas Oil) — 2.5121 kgCO₂e/litre",
            "source": "DEFRA",
            "source_dataset": "Greenhouse gas reporting: conversion factors 2025",
            "year": "2025",
            "region": "GB",
            "region_name": "United Kingdom"
          },
          {
            "data_category": "wtt_factor",
            "name": "Well-to-Tank — Diesel (Gas Oil)",
            "source": "DEFRA",
            "source_dataset": "Greenhouse gas reporting: conversion factors 2025",
            "year": "2025",
            "region": "GB",
            "region_name": "United Kingdom"
          }
        ]
      },
      "fuel": {
        "fuel_type": "diesel",
        "fuel_label": "Diesel (Gas Oil)",
        "fuel_category": "liquid",
        "is_biofuel": false,
        "amount": 1000,
        "unit": "litre",
        "emission_factor": 2.5121,
        "emission_factor_unit": "kgCO2e/litre",
        "include_wtt": true
      },
      "notices": []
    }
  },
  "meta": {
    "methodology": "DEFRA 2025 - GHG Conversion Factors",
    "emission_factors_year": 2025,
    "standards_compliance": {
      "GHG_Protocol": "Scope 1 (Direct combustion)",
      "ISO_14064": "Part 1 - Organisation level"
    },
    "calculated_at": "2026-02-08T14:00:00Z"
  }
}

Response Fields

emissions

Field	Type	Description
`co2e`	number	Total CO₂e in kg (Scope 1 + WTT if included)
`co2e_unit`	string	Always `kg`
`co2e_grams`	integer	Total CO₂e in grams

breakdown

Field	Type	Description
`direct_co2e`	number	Total direct combustion CO₂e (kg) — Scope 1
`direct_co2`	number	Carbon dioxide from combustion (kg)
`direct_ch4`	number	Methane from incomplete combustion (kg)
`direct_n2o`	number	Nitrous oxide from combustion (kg)
`wtt_co2e`	number	Well-to-Tank upstream emissions (kg) — Scope 3 Category 3

ghg_protocol_scopes

Field	Type	Description
`scope_1`	number	Direct combustion emissions (kg)
`scope_3_category_3`	number	WTT upstream fuel emissions (kg)

fuel

Field	Type	Description
`fuel_type`	string	Fuel type identifier
`fuel_label`	string	Human-readable label
`fuel_category`	string	`gaseous`, `liquid`, `solid`, or `biofuel`
`is_biofuel`	boolean	`true` for biogenic fuels
`amount`	number	Input amount
`unit`	string	Unit used
`emission_factor`	number	Factor applied (kgCO₂e per unit)
`emission_factor_unit`	string	Factor unit (e.g., `kgCO2e/litre`)

notices

Code	Severity	When
`biofuel_biogenic_carbon`	info	Biofuel fuel type used — explains zero direct CO₂
`wtt_excluded`	info	WTT was disabled
`high_carbon_fuel`	warning	Coal fuel type — suggests lower-carbon alternatives

Biofuel Handling

For biofuels (biodiesel, hvo, bioethanol, biogas, wood_logs, wood_pellets):

direct_co2 is zero — biogenic carbon is excluded from Scope 1
direct_co2e reflects only CH₄ and N₂O from incomplete combustion
WTT emissions may still be significant (e.g., bioethanol WTT = 0.618 kgCO₂e/litre)
A biofuel_biogenic_carbon notice is always included

Example: HVO vs Diesel

# Diesel: 1,000 litres
curl "...?fuel_type=diesel&amount=1000&unit=litre"
# → 3,152.5 kg CO₂e

# HVO: 1,000 litres
curl "...?fuel_type=hvo&amount=1000&unit=litre"
# → 203.8 kg CO₂e (38.2 direct + 165.6 WTT)
# 93.5% total reduction

Examples

Office natural gas heating

curl "https://api.emissions.dev/v1/fuel/emissions?\
fuel_type=natural_gas&\
amount=15000&\
unit=kwh" \
  -H "Authorization: Bearer em_live_xxxx"

→ 3,106.1 kg CO₂e (2,747.4 Scope 1 + 358.5 WTT)

Backup diesel generator

curl "https://api.emissions.dev/v1/fuel/emissions?\
fuel_type=diesel&\
amount=500&\
unit=litre" \
  -H "Authorization: Bearer em_live_xxxx"

→ 1,576.3 kg CO₂e (1,256.1 Scope 1 + 320.2 WTT)

Natural gas in therms (US billing)

curl "https://api.emissions.dev/v1/fuel/emissions?\
fuel_type=natural_gas&\
amount=500&\
unit=therm" \
  -H "Authorization: Bearer em_live_xxxx"

→ 3,035.5 kg CO₂e

Biomass heating (wood pellets)

curl "https://api.emissions.dev/v1/fuel/emissions?\
fuel_type=wood_pellets&\
amount=2000&\
unit=kg" \
  -H "Authorization: Bearer em_live_xxxx"

→ 245.2 kg CO₂e (144.8 direct CH₄+N₂O + 100.4 WTT)

Scope 1 only (no WTT)

curl "https://api.emissions.dev/v1/fuel/emissions?\
fuel_type=diesel&\
amount=1000&\
unit=litre&\
include_wtt=false" \
  -H "Authorization: Bearer em_live_xxxx"

→ 2,512.1 kg CO₂e (Scope 1 only)

Error Responses

Missing Fuel Type

{
  "error": {
    "code": "validation_error",
    "message": "Fuel type is required (e.g. 'natural_gas', 'diesel', 'petrol').",
    "status": 422
  }
}

Invalid Fuel Type

{
  "error": {
    "code": "invalid_fuel_type",
    "message": "Fuel type 'propane' not recognised. Available: natural_gas, lpg, cng, biogas, diesel, petrol, kerosene, fuel_oil, red_diesel, biodiesel, hvo, bioethanol, wood_logs, wood_pellets, coal_industrial, coal_domestic",
    "status": 422,
    "available_fuel_types": ["natural_gas", "lpg", "..."]
  }
}

Invalid Unit

{
  "error": {
    "code": "invalid_unit",
    "message": "Unit 'gallon' not supported for diesel. Available: kwh, litre",
    "status": 422,
    "available_units": ["kwh", "litre"]
  }
}