Changelog

All notable changes to the emissions.dev API.

[1.0.6] - 2026-02-12

Added

  • LLM Emissions API (Beta) — Estimate CO₂e emissions from large language model inference (/v1/digital/llm/emissions)
  • 80+ models classified across 4 energy tiers (frontier, large, medium, small)
  • 12 providers supported: OpenAI, Anthropic, Google, Meta, Mistral, DeepSeek, xAI, Cohere, AWS Bedrock, GCP Vertex, Azure OpenAI, self-hosted
  • Automatic reasoning model detection with thinking token overhead (o3, o1, DeepSeek R1, Gemini Deep Think)
  • Prompt caching support — 90% energy reduction on cached input tokens
  • Batch calculation support — estimate emissions for up to 10,000,000 requests in a single call
  • Freight API: detailed_route parameter — Optional encoded polyline for road route visualization (detailed_route=true)
  • Google-format polyline (precision 5) compatible with Leaflet, Google Maps, Mapbox, and all standard mapping libraries
  • Route duration included in response (duration_seconds, duration_formatted)
  • Sampled waypoints array always returned for lightweight map rendering (4–20 points scaled to distance)

Changed

  • API root endpoint (GET /) now lists all five production APIs (freight, travel, hotel, electricity, fuel)
  • API root response now includes api_version (API contract) and release (deployment version) as separate fields
  • All API timestamps now use Zulu format (2026-02-12T10:15:40Z) instead of +00:00 offset

Notes

  • LLM endpoint reports in grams (not kg) due to sub-gram per-request emissions — check co2e_unit when parsing
  • This endpoint is in beta — energy-per-token estimates are based on published research and may change as better data becomes available
  • Response format follows the standard emissions.dev envelope (data.type, data.id, data.attributes.emissions)

[1.0.5] - 2026-02-11

Added

  • Panama Canal seaports (Balboa, Cristóbal, Manzanillo) for accurate sea freight routing
  • Central American countries added to land route network (Guatemala, Belize, El Salvador, Honduras, Nicaragua, Costa Rica, Panama)

Changed

  • Flight emission factors now use distance-based haul categories for all countries — domestic, short-haul, and long-haul factors are correctly applied regardless of origin/destination, not just for UK flights
  • Electric vehicle (BEV) emission breakdowns now correctly report 100% indirect emissions for all recognised BEV identifiers (electric, bev, battery_electric)

Fixed

  • US domestic flights previously received international emission factors instead of domestic/short-haul factors
  • battery_electric vehicle type was not recognised as a BEV in emission breakdown calculations
  • Sea freight routing for Asia→US East Coast now correctly routes via Panama Canal
  • US coastal region detection no longer incorrectly assigned multiple regions, which caused wrong route selection
  • Multimodal freight responses now show correct fuel source for dominant transport mode (e.g. hfo for sea) instead of defaulting to diesel

[1.0.4] - 2026-02-09

Changed

  • US electricity grid factors updated to EPA eGRID2023 rev2 — all 50 states recalculated from state-level CO₂e output emission rates
  • US national average: 379 → 350 gCO₂e/kWh
  • 24 states corrected by >15% — coal states were underestimated (WV 750→893, WY 720→832, KY 670→792), wind/solar states overestimated (SD 320→152, NM 512→351, IA 390→288)
  • All US cloud regions (AWS, GCP, Azure) realigned to match eGRID2023 host-state values (e.g. us-east-1 379→245, us-central1 494→288)
  • Grid intensity data boundary clarified as generation-based (excludes T&D losses), consistent with GHG Protocol Scope 2

Fixed

  • Cloud-only requests (cloud_provider + cloud_region without country) no longer return 422 validation error — country is now optional when cloud parameters are provided

[1.0.3] - 2026-02-08

Added

  • Electricity API — Calculate Scope 2 emissions from electricity consumption (/v1/electricity/emissions)
  • Grid Intensity Lookup — Query carbon intensity for any country or all countries ranked cleanest-first (/v1/electricity/grid)
  • Fuel Combustion API — Calculate Scope 1 emissions from 16 fuel types across 4 categories (/v1/fuel/emissions)
  • Fuel Types Lookup — List all supported fuels with available units, filterable by category (/v1/fuel/types)
  • Unit conversion support on Electricity endpoint (unit=mwh, unit=wh)
  • US state-level grid intensity via EPA eGRID 2023 (e.g. country=US&state=CA)
  • Cloud provider region support for data centre emissions (AWS, GCP, Azure)
  • GHG Protocol dual reporting structure (location-based and market-based) on Electricity endpoint
  • Well-to-Tank (WTT) emissions separated as Scope 3 Category 3 across Electricity and Fuel endpoints
  • Individual gas breakdown (CO₂, CH₄, N₂O) on all Fuel endpoint responses
  • Clean grid (<100 gCO₂e/kWh) and dirty grid (>500 gCO₂e/kWh) notices on Electricity endpoint
  • Biofuel support with biogenic carbon handling (biodiesel, HVO, bioethanol, wood pellets, wood logs, biogas)
  • Coal high-carbon warning notice on Fuel endpoint

Changed

  • Updated European grid carbon intensity factors to Ember Global Electricity Review 2025
  • Added 6 new European countries: Bosnia & Herzegovina, Serbia, Montenegro, North Macedonia, Kosovo, Ukraine
  • Cloud region emission factors updated to match Ember 2025 for all European data centres
  • Europe regional average updated from 276 to 240 gCO₂e/kWh
  • Emissions precision standardised to 3 decimal places (gram-level accuracy) across all endpoints
  • co2e and co2e_grams now always mathematically agree (grams as source of truth)
  • WTT source trail now shows "United Kingdom (global proxy)" for non-UK requests

Fixed

  • Emissions rounding inconsistency where co2e and co2e_grams could disagree (e.g. 0.13 kg vs 126g)
  • per_passenger_kg and per_passenger_g now derive from the same normalised value on Travel endpoint

[1.0.2] - 2026-02-07

Added

  • Hotel API — Calculate accommodation emissions for 60+ countries
  • Location-aware EV calculations — Uses local grid carbon intensity
  • Real road routing — Actual driving distances via OpenRouteService
  • Standardized coordinate format (lat/lon) across all endpoints

Changed

  • Travel API now uses DEFRA 2025 emission factors
  • Radiative forcing built into DEFRA flight factors

Fixed

  • Coordinate precision standardized to 6 decimal places

[1.0.1] - 2026-01-15

Added

  • equivalents parameter for real-world comparisons
  • source_trail in all responses for audit compliance
  • Return trip support for Travel API

Changed

  • Updated GLEC emission factors to v3.1
  • Improved multimodal route detection

Fixed

  • Sea route waypoints for Asia-Europe routes
  • Distance calculation for ferry routes

[1.0.0] - 2025-12-01

Added

  • Freight API — Calculate cargo transport emissions
  • Travel API — Calculate passenger travel emissions
  • GHG Protocol scope categorization
  • ISO 14083 compliance

Migration Guides

v1.0.1 to v1.0.2

Coordinate format change:

The API now returns lat/lon instead of latitude/longitude:

{
  "origin": {
    "lat": 51.5074,
    "lon": -0.1278
  }
}

Radiative forcing:

DEFRA 2025 factors already include radiative forcing. Remove any manual multipliers:

// Before
const emissions = result.co2e * 1.9;

// After
const emissions = result.co2e;

v1.0.2 to v1.0.3

Emissions precision change:

co2e now returns 3 decimal places (gram-level) instead of 2. If you parse or display emissions, update formatting:

// Before: 0.13
// After:  0.126
const display = result.co2e.toFixed(2); // If you want 2dp display

New endpoints available:

GET /v1/electricity/emissions?kwh=5000&country=GB
GET /v1/electricity/grid?country=DE
GET /v1/fuel/emissions?fuel_type=natural_gas&amount=15000&unit=kwh
GET /v1/fuel/types

Versioning

We follow Semantic Versioning:

  • MAJOR — Breaking changes
  • MINOR — New features, backwards compatible
  • PATCH — Bug fixes

Current API version: v1

We maintain backwards compatibility within major versions for at least 12 months.