{ "openapi": "3.1.0", "info": { "title": "Emission Factors API", "version": "1.0.0", "description": "13,000 DEFRA and EPA greenhouse-gas emission factors with gases, units and the published file they came from.\n\nAuthoritative greenhouse-gas emission factors with the provenance a reporting team actually needs to cite: 13,000+ factors covering Scope 1, 2 and 3, drawn from four editions (2023-2026) of the UK DEFRA/DESNZ conversion factors and the US EPA GHG Emission Factors Hub. Fuels, UK and US grid electricity (including every eGRID subregion), passenger and delivery vehicles by size and fuel, freight by mode and tonne.km, flights by haul and cabin class, rail, sea, hotel stays, homeworking, water supply and treatment, material use, waste by disposal route, and refrigerants with their AR5 global warming potentials. Every factor carries kg CO2e per unit plus the CO2 / CH4 / N2O split, the gases it actually covers, whether the CO2e was published or derived, the GWP basis used, and the exact source file and licence it came from. Because the API keys on a stable semantic slug rather than the publisher's own row id — which is not stable between editions — you can pull the same activity across years to restate a prior reporting period. A calculate endpoint turns activity data into kg CO2e in one call, single or batched, totalled by scope, keeping biogenic CO2 out of the scope totals and warning when a factor covers only some gases. A weekly job re-checks each publisher and records whether the file behind every edition is still the one we parsed, exposed at /v1/factors/updates so you can verify the dataset is current rather than take it on trust. Self-hosted dataset built from free, redistributable government sources — no third-party calls at request time.", "contact": { "name": "Data and APIs", "url": "https://dataandapis.com/contact" }, "termsOfService": "https://dataandapis.com/terms-of-service", "license": { "name": "Data and APIs Terms of Service", "url": "https://dataandapis.com/terms-of-service" }, "x-logo": { "url": "https://dataandapis.com/images/emission-factors.webp" } }, "externalDocs": { "description": "Documentation, live tester and pricing", "url": "https://dataandapis.com/apis/emission-factors" }, "servers": [ { "url": "https://api-emission-factors.dataandapis.com" } ], "tags": [ { "name": "Data", "description": "Emission Factors API belongs to the Data category of the Data and APIs catalog." } ], "paths": { "/v1/calculate": { "get": { "operationId": "calculateEmissions", "summary": "Calculate Emissions", "description": "Calculate Emissions endpoint of the Emission Factors API. Costs 1 token per call.", "externalDocs": { "url": "https://dataandapis.com/apis/emission-factors/calculate-emissions" }, "parameters": [ { "name": "factor", "in": "query", "required": true, "schema": { "type": "string" }, "example": "uk-electricity-electricity-generated-electricity-uk-kwh-kwh" }, { "name": "publisher", "in": "query", "required": false, "schema": { "type": "string" }, "example": "DEFRA" }, { "name": "quantity", "in": "query", "required": true, "schema": { "type": "string" }, "example": "1200" }, { "name": "year", "in": "query", "required": false, "schema": { "type": "string" }, "example": "2026" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "total_kg_co2e": 157.152, "total_tonnes_co2e": 0.157152, "by_scope": { "Scope 2": 157.152 }, "biogenic_kg_co2e": 0, "count": 1, "failed": 0, "items": [ { "ok": true, "factor": "uk-electricity-electricity-generated-electricity-uk-kwh-kwh", "label": "UK electricity - Electricity generated - Electricity: UK - kWh", "quantity": 1200, "unit": "kWh", "factor_value": 0.13096, "kg_co2e": 157.152, "by_gas": { "co2": 155.31599999999997, "ch4": 0.804, "n2o": 1.032 }, "scope": "Scope 2", "biogenic": false, "warnings": [], "source": { "set": "defra-2026", "publisher": "UK Department for Energy Security and Net Zero / Defra", "edition_year": 2026, "basis": "published", "gwp_set": "IPCC AR5 (100-year)", "gases_included": [ "CO2", "CH4", "N2O" ], "licence": "Open Government Licence v3.0", "source_url": "https://www.gov.uk/government/publications/greenhouse-gas-reporting-conversion-factors-2026" } } ] } } } }, "401": { "description": "Missing or invalid API key" }, "402": { "description": "Subscription past due; the response carries a payment_url" }, "429": { "description": "Monthly token allowance exhausted" } }, "security": [ { "ApiKey": [] } ] }, "post": { "operationId": "calculateEmissionsBatch", "summary": "Calculate Emissions Batch", "description": "Calculate Emissions Batch endpoint of the Emission Factors API. Costs 1 token per call.", "externalDocs": { "url": "https://dataandapis.com/apis/emission-factors/calculate-emissions-batch" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" }, "example": { "items": [ { "factor": "uk-electricity-electricity-generated-electricity-uk-kwh-kwh", "quantity": 1200 }, { "factor": "uk-electricity-electricity-generated-electricity-uk-kwh-kwh", "quantity": 300, "year": 2025 } ] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "total_kg_co2e": 3896.706, "total_tonnes_co2e": 3.896706, "by_scope": { "Scope 2": 1571.52, "Scope 1": 2325.186 }, "biogenic_kg_co2e": 0, "count": 2, "failed": 0, "items": [ { "ok": true, "factor": "uk-electricity-electricity-generated-electricity-uk-kwh-kwh", "label": "Office electricity", "quantity": 12000, "unit": "kWh", "factor_value": 0.13096, "kg_co2e": 1571.52, "by_gas": { "co2": 1553.1599999999999, "ch4": 8.040000000000001, "n2o": 10.32 }, "scope": "Scope 2", "biogenic": false, "warnings": [], "source": { "set": "defra-2026", "publisher": "UK Department for Energy Security and Net Zero / Defra", "edition_year": 2026, "basis": "published", "gwp_set": "IPCC AR5 (100-year)", "gases_included": [ "CO2", "CH4", "N2O" ], "licence": "Open Government Licence v3.0", "source_url": "https://www.gov.uk/government/publications/greenhouse-gas-reporting-conversion-factors-2026" } }, { "ok": true, "factor": "fuels-liquid-fuels-diesel-average-biofuel-blend-litres", "label": "Fleet diesel", "quantity": 900, "unit": "litres", "factor_value": 2.58354, "kg_co2e": 2325.186, "by_gas": { "co2": 2295.315, "ch4": 0.261, "n2o": 29.61 }, "scope": "Scope 1", "biogenic": false, "warnings": [], "source": { "set": "defra-2026", "publisher": "UK Department for Energy Security and Net Zero / Defra", "edition_year": 2026, "basis": "published", "gwp_set": "IPCC AR5 (100-year)", "gases_included": [ "CO2", "CH4", "N2O" ], "licence": "Open Government Licence v3.0", "source_url": "https://www.gov.uk/government/publications/greenhouse-gas-reporting-conversion-factors-2026" } } ] } } } }, "401": { "description": "Missing or invalid API key" }, "402": { "description": "Subscription past due; the response carries a payment_url" }, "429": { "description": "Monthly token allowance exhausted" } }, "security": [ { "ApiKey": [] } ] } }, "/v1/factors/categories": { "get": { "operationId": "factorCategories", "summary": "Factor Categories", "description": "Factor Categories endpoint of the Emission Factors API. Costs 1 token per call.", "externalDocs": { "url": "https://dataandapis.com/apis/emission-factors/factor-categories" }, "parameters": [ { "name": "publisher", "in": "query", "required": false, "schema": { "type": "string" }, "example": "DEFRA" }, { "name": "scope", "in": "query", "required": false, "schema": { "type": "string" }, "example": "Scope 3" }, { "name": "year", "in": "query", "required": false, "schema": { "type": "string" }, "example": "2026" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "count": 108, "categories": [ { "category": "Bioenergy", "subcategory": "Biofuel", "scope": "Scope 1", "count": 37 }, { "category": "Bioenergy", "subcategory": "Biogas", "scope": "Scope 1", "count": 4 }, { "category": "Bioenergy", "subcategory": "Biomass", "scope": "Scope 1", "count": 8 } ] } } } }, "401": { "description": "Missing or invalid API key" }, "402": { "description": "Subscription past due; the response carries a payment_url" }, "429": { "description": "Monthly token allowance exhausted" } }, "security": [ { "ApiKey": [] } ] } }, "/v1/factors/sets": { "get": { "operationId": "factorSets", "summary": "Factor Sets", "description": "Factor Sets endpoint of the Emission Factors API. Costs 1 token per call.", "externalDocs": { "url": "https://dataandapis.com/apis/emission-factors/factor-sets" }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "count": 5, "sets": [ { "set": "defra-2026", "publisher": "DEFRA", "publisher_full": "UK Department for Energy Security and Net Zero / Defra", "title": "Greenhouse gas reporting: conversion factors 2026", "edition_year": 2026, "region": "UK", "licence": "Open Government Licence v3.0", "gwp_set": "IPCC AR5 (100-year)", "source_url": "https://www.gov.uk/government/publications/greenhouse-gas-reporting-conversion-factors-2026", "file_url": "https://assets.publishing.service.gov.uk/media/6a6c9748862aaf18d9c62ac9/ghg-conversion-factors-2026-flat-format-revised.xlsx", "published_at": "2026-07-31", "retrieved_at": "2026-08-27", "factor_count": 3129, "upstream": { "status": "current", "last_checked": "2026-08-27 13:36:52", "current_file_url": null } }, { "set": "defra-2025", "publisher": "DEFRA", "publisher_full": "UK Department for Energy Security and Net Zero / Defra", "title": "Greenhouse gas reporting: conversion factors 2025", "edition_year": 2025, "region": "UK", "licence": "Open Government Licence v3.0", "gwp_set": "IPCC AR5 (100-year)", "source_url": "https://www.gov.uk/government/publications/greenhouse-gas-reporting-conversion-factors-2025", "file_url": "https://assets.publishing.service.gov.uk/media/6846b6ea57f3515d9611f0dd/ghg-conversion-factors-2025-flat-format.xlsx", "published_at": "2025-06-10", "retrieved_at": "2026-08-27", "factor_count": 3123, "upstream": { "status": "current", "last_checked": "2026-08-27 13:36:52", "current_file_url": null } } ] } } } }, "401": { "description": "Missing or invalid API key" }, "402": { "description": "Subscription past due; the response carries a payment_url" }, "429": { "description": "Monthly token allowance exhausted" } }, "security": [ { "ApiKey": [] } ] } }, "/v1/factors/units": { "get": { "operationId": "factorUnits", "summary": "Factor Units", "description": "Factor Units endpoint of the Emission Factors API. Costs 1 token per call.", "externalDocs": { "url": "https://dataandapis.com/apis/emission-factors/factor-units" }, "parameters": [ { "name": "publisher", "in": "query", "required": false, "schema": { "type": "string" }, "example": "DEFRA" }, { "name": "year", "in": "query", "required": false, "schema": { "type": "string" }, "example": "2026" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "count": 18, "units": [ { "unit": "km", "output_unit": "kg CO2e", "kind": "emission", "count": 702 }, { "unit": "miles", "output_unit": "kg CO2e", "kind": "emission", "count": 617 }, { "unit": "kg", "output_unit": "kg CO2e", "kind": "emission", "count": 398 }, { "unit": "tonnes", "output_unit": "kg CO2e", "kind": "emission", "count": 292 } ] } } } }, "401": { "description": "Missing or invalid API key" }, "402": { "description": "Subscription past due; the response carries a payment_url" }, "429": { "description": "Monthly token allowance exhausted" } }, "security": [ { "ApiKey": [] } ] } }, "/v1/factors/{slug}": { "get": { "operationId": "getFactor", "summary": "Get Factor", "description": "Get Factor endpoint of the Emission Factors API. Costs 1 token per call.", "externalDocs": { "url": "https://dataandapis.com/apis/emission-factors/get-factor" }, "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "example": "uk-electricity-electricity-generated-electricity-uk-kwh-kwh" }, { "name": "publisher", "in": "query", "required": false, "schema": { "type": "string" }, "example": "DEFRA" }, { "name": "year", "in": "query", "required": false, "schema": { "type": "string" }, "example": "2026" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "slug": "uk-electricity-electricity-generated-electricity-uk-kwh-kwh", "label": "UK electricity - Electricity generated - Electricity: UK - kWh", "publisher": "DEFRA", "year": 2026, "region": "UK", "scope": "Scope 2", "category": "UK electricity", "subcategory": "Electricity generated", "activity": "Electricity: UK", "detail": "kWh", "unit": "kWh", "kind": "emission", "value": 0.13096, "output_unit": "kg CO2e", "gases": [ "CO2", "CH4", "N2O" ], "variant": null, "biogenic": false, "co2e": { "total": 0.13096, "unit": "kg CO2e", "per": "kWh", "basis": "published", "gases_included": [ "CO2", "CH4", "N2O" ], "by_gas": { "co2": 0.12943, "ch4": 0.00067, "n2o": 0.00086 } }, "gas_mass": { "unit": "kg", "per": "kWh", "co2": null, "ch4": null, "n2o": null }, "energy": null, "gwp_set": "IPCC AR5 (100-year)", "source": { "set": "defra-2026", "publisher": "UK Department for Energy Security and Net Zero / Defra", "title": "Greenhouse gas reporting: conversion factors 2026", "edition_year": 2026, "licence": "Open Government Licence v3.0", "source_url": "https://www.gov.uk/government/publications/greenhouse-gas-reporting-conversion-factors-2026", "file_url": "https://assets.publishing.service.gov.uk/media/6a6c9748862aaf18d9c62ac9/ghg-conversion-factors-2026-flat-format-revised.xlsx", "published_at": "2026-07-31", "retrieved_at": "2026-08-27", "publisher_row_id": "7_400_4000_5_1,7_400_4000_5_2,7_400_4000_5_3,7_400_4000_5_4" }, "raw": { "ids": [ "7_400_4000_5_1", "7_400_4000_5_2", "7_400_4000_5_3", "7_400_4000_5_4" ], "ghg_units": { "kg CO2e": 0.13096, "kg CO2e of CO2 per unit": 0.12943, "kg CO2e of CH4 per unit": 0.00067, "kg CO2e of N2O per unit": 0.00086 } }, "history": [ { "year": 2026, "value": 0.13096, "unit": "kWh", "basis": "published" }, { "year": 2025, "value": 0.177, "unit": "kWh", "basis": "published" }, { "year": 2024, "value": 0.20705, "unit": "kWh", "basis": "published" }, { "year": 2023, "value": 0.20707428859060403, "unit": "kWh", "basis": "published" } ] } } } }, "401": { "description": "Missing or invalid API key" }, "402": { "description": "Subscription past due; the response carries a payment_url" }, "429": { "description": "Monthly token allowance exhausted" } }, "security": [ { "ApiKey": [] } ] } }, "/v1/factors/gwp": { "get": { "operationId": "globalWarmingPotentials", "summary": "Global Warming Potentials", "description": "Global Warming Potentials endpoint of the Emission Factors API. Costs 1 token per call.", "externalDocs": { "url": "https://dataandapis.com/apis/emission-factors/global-warming-potentials" }, "parameters": [ { "name": "blend", "in": "query", "required": false, "schema": { "type": "string" }, "example": "true" }, { "name": "gas", "in": "query", "required": false, "schema": { "type": "string" }, "example": "R-410A" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "count": 1, "gwp": [ { "gas": "R-410A", "name": "R-410A", "formula": "50% HFC-32 , 50% HFC-125", "gwp_100": 1924, "assessment": "IPCC AR5", "blend": 1 } ] } } } }, "401": { "description": "Missing or invalid API key" }, "402": { "description": "Subscription past due; the response carries a payment_url" }, "429": { "description": "Monthly token allowance exhausted" } }, "security": [ { "ApiKey": [] } ] } }, "/v1/factors": { "get": { "operationId": "listFactors", "summary": "List Factors", "description": "List Factors endpoint of the Emission Factors API. Costs 1 token per call.", "externalDocs": { "url": "https://dataandapis.com/apis/emission-factors/list-factors" }, "parameters": [ { "name": "activity", "in": "query", "required": false, "schema": { "type": "string" }, "example": "Diesel" }, { "name": "biogenic", "in": "query", "required": false, "schema": { "type": "string" }, "example": "false" }, { "name": "category", "in": "query", "required": false, "schema": { "type": "string" }, "example": "Fuels" }, { "name": "gas", "in": "query", "required": false, "schema": { "type": "string" }, "example": "CH4" }, { "name": "kind", "in": "query", "required": false, "schema": { "type": "string" }, "example": "emission" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "string" }, "example": "20" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "string" }, "example": "1" }, { "name": "publisher", "in": "query", "required": false, "schema": { "type": "string" }, "example": "DEFRA" }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, "example": "diesel" }, { "name": "region", "in": "query", "required": false, "schema": { "type": "string" }, "example": "UK" }, { "name": "scope", "in": "query", "required": false, "schema": { "type": "string" }, "example": "Scope 1" }, { "name": "set", "in": "query", "required": false, "schema": { "type": "string" }, "example": "defra-2026" }, { "name": "subcategory", "in": "query", "required": false, "schema": { "type": "string" }, "example": "Liquid fuels" }, { "name": "unit", "in": "query", "required": false, "schema": { "type": "string" }, "example": "litres" }, { "name": "year", "in": "query", "required": false, "schema": { "type": "string" }, "example": "2026" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "total": 23, "page": 1, "limit": 2, "count": 2, "results": [ { "slug": "bioenergy-biofuel-biodiesel-hvo-litres", "label": "Bioenergy - Biofuel - Biodiesel HVO", "publisher": "DEFRA", "year": 2026, "region": "UK", "scope": "Scope 1", "category": "Bioenergy", "subcategory": "Biofuel", "activity": "Biodiesel HVO", "detail": null, "unit": "litres", "kind": "emission", "value": 0.03558, "output_unit": "kg CO2e", "gases": [ "CO2e" ] }, { "slug": "bioenergy-biofuel-biodiesel-me-litres", "label": "Bioenergy - Biofuel - Biodiesel ME", "publisher": "DEFRA", "year": 2026, "region": "UK", "scope": "Scope 1", "category": "Bioenergy", "subcategory": "Biofuel", "activity": "Biodiesel ME", "detail": null, "unit": "litres", "kind": "emission", "value": 0.16751, "output_unit": "kg CO2e", "gases": [ "CO2e" ] } ] } } } }, "401": { "description": "Missing or invalid API key" }, "402": { "description": "Subscription past due; the response carries a payment_url" }, "429": { "description": "Monthly token allowance exhausted" } }, "security": [ { "ApiKey": [] } ] } }, "/v1/factors/random": { "get": { "operationId": "randomFactor", "summary": "Random Factor", "description": "Random Factor endpoint of the Emission Factors API. Costs 1 token per call.", "externalDocs": { "url": "https://dataandapis.com/apis/emission-factors/random-factor" }, "parameters": [ { "name": "amount", "in": "query", "required": false, "schema": { "type": "string" }, "example": "1" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "count": 1, "results": [ { "slug": "wtt-delivery-vehs-and-freight-wtt-vans-class-iii-1-74-to-3-5-tonnes-petrol-tonne-km", "label": "WTT- delivery vehs & freight - WTT- vans - Class III (1.74 to 3.5 tonnes) (Petrol)", "publisher": "DEFRA", "year": 2026, "region": "UK", "scope": "Scope 3", "category": "WTT- delivery vehs & freight", "subcategory": "WTT- vans", "activity": "Class III (1.74 to 3.5 tonnes)", "detail": null, "unit": "tonne.km", "kind": "emission", "value": 0.24164, "output_unit": "kg CO2e", "gases": [ "CO2e" ] } ] } } } }, "401": { "description": "Missing or invalid API key" }, "402": { "description": "Subscription past due; the response carries a payment_url" }, "429": { "description": "Monthly token allowance exhausted" } }, "security": [ { "ApiKey": [] } ] } }, "/v1/factors/updates": { "get": { "operationId": "sourceFreshness", "summary": "Source Freshness", "description": "Source Freshness endpoint of the Emission Factors API. Costs 1 token per call.", "externalDocs": { "url": "https://dataandapis.com/apis/emission-factors/source-freshness" }, "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "string" }, "example": "25" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" }, "example": "revised" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object" }, "example": { "last_checked": "2026-08-27 13:36:52", "editions_needing_reseed": 0, "count": 3, "checks": [ { "checked_at": "2026-08-27 13:36:52", "publisher": "EPA", "edition_year": 2024, "status": "not-tracked", "set_slug": null, "seeded_file_url": null, "discovered_file_url": "https://www.epa.gov/system/files/documents/2024-02/ghg-emission-factors-hub-2024.xlsx", "discovered_published_at": null, "detail": null }, { "checked_at": "2026-08-27 13:36:52", "publisher": "EPA", "edition_year": 2025, "status": "current", "set_slug": "epa-hub-2025", "seeded_file_url": "https://www.epa.gov/system/files/other-files/2025-01/ghg-emission-factors-hub-2025.xlsx", "discovered_file_url": "https://www.epa.gov/system/files/other-files/2025-01/ghg-emission-factors-hub-2025.xlsx", "discovered_published_at": null, "detail": null }, { "checked_at": "2026-08-27 13:36:52", "publisher": "DEFRA", "edition_year": 2027, "status": "unavailable", "set_slug": null, "seeded_file_url": null, "discovered_file_url": null, "discovered_published_at": null, "detail": "no gov.uk publication for 2027" } ] } } } }, "401": { "description": "Missing or invalid API key" }, "402": { "description": "Subscription past due; the response carries a payment_url" }, "429": { "description": "Monthly token allowance exhausted" } }, "security": [ { "ApiKey": [] } ] } } }, "components": { "securitySchemes": { "ApiKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key", "description": "Create a free key at https://dataandapis.com/sign-up. 500 tokens a month on the Free plan; this API costs 1 token per call." } } }, "security": [ { "ApiKey": [] } ] }