{
  "openapi": "3.1.0",
  "info": {
    "title": "emissions.dev API",
    "description": "Precise, auditable CO₂e calculations for freight, travel, electricity, fuel, hotel accommodation, and LLM inference. Every response includes a full source trail with emission factors, datasets, and methodology references. GHG Protocol compliant.",
    "version": "1.0.6",
    "contact": { "name": "emissions.dev Support", "email": "support@emissions.dev", "url": "https://emissions.dev" },
    "termsOfService": "https://emissions.dev/terms",
    "license": { "name": "Proprietary", "url": "https://emissions.dev/terms" }
  },
  "servers": [
    { "url": "https://api.emissions.dev/v1", "description": "Production" }
  ],
  "security": [
    { "BearerAuth": [] }
  ],
  "tags": [
    {
      "name": "Freight",
      "description": "Calculate CO₂e emissions for cargo and freight transport across road, rail, sea, and air. GLEC Framework v3.1 compliant."
    },
    { "name": "Travel", "description": "Calculate CO₂e emissions for passenger travel — flights, rail, car, bus, ferry, and taxi." },
    { "name": "Hotel", "description": "Calculate CO₂e emissions for hotel accommodation in 60+ countries." },
    {
      "name": "Electricity",
      "description": "Calculate CO₂e emissions from electricity consumption. Scope 2 reporting with 100+ countries, US states, and cloud regions."
    },
    {
      "name": "Fuel",
      "description": "Calculate CO₂e emissions from direct fuel combustion. Scope 1 reporting with 16 fuel types and gas-by-gas breakdown."
    },
    {
      "name": "Digital",
      "description": "Estimate CO₂e emissions from LLM inference. 80+ models across 12 providers. Beta: energy-per-token estimates may change. Supported models are listed in the docs (https://emissions.dev/docs/api/digital/llm/models)."
    }
  ],
  "paths": {
    "/freight/emissions": {
      "get": {
        "operationId": "calculateFreightEmissions",
        "summary": "Calculate freight emissions",
        "description": "Calculate CO₂e emissions for freight transport between two locations. Supports road, rail, sea, and air with real road routing, sea route waypoints, and GLEC Framework v3.1 emission factors.",
        "tags": ["Freight"],
        "parameters": [
          {
            "name": "origin_country",
            "in": "query",
            "required": true,
            "description": "Origin country code (ISO 3166-1 alpha-2)",
            "schema": { "type": "string", "pattern": "^[A-Z]{2}$", "example": "GB" }
          },
          {
            "name": "destination_country",
            "in": "query",
            "required": true,
            "description": "Destination country code (ISO 3166-1 alpha-2)",
            "schema": { "type": "string", "pattern": "^[A-Z]{2}$", "example": "DE" }
          },
          {
            "name": "weight",
            "in": "query",
            "required": true,
            "description": "Cargo weight in the specified unit",
            "schema": { "type": "number", "minimum": 0.001, "example": 5000 }
          },
          {
            "name": "origin_location",
            "in": "query",
            "description": "Origin city, address, or postcode",
            "schema": { "type": "string", "example": "London" }
          },
          {
            "name": "destination_location",
            "in": "query",
            "description": "Destination city, address, or postcode",
            "schema": { "type": "string", "example": "Berlin" }
          },
          {
            "name": "unit",
            "in": "query",
            "description": "Weight unit",
            "schema": { "type": "string", "enum": ["kg", "g", "lb", "tonne"], "default": "kg" }
          },
          {
            "name": "transport_mode",
            "in": "query",
            "description": "Transport mode. `auto` detects the best mode automatically.",
            "schema": { "type": "string", "enum": ["auto", "road", "rail", "sea", "air"], "default": "auto" }
          },
          {
            "name": "vehicle_type",
            "in": "query",
            "description": "Vehicle class. Options vary by transport mode. Road: small, medium, large, articulated, average. Sea: container_small, container_large, bulk_carrier, average. Air: belly_freight, freighter, average.",
            "schema": { "type": "string", "default": "average" }
          },
          {
            "name": "fuel_source",
            "in": "query",
            "description": "Fuel type for road transport",
            "schema": { "type": "string", "enum": ["diesel", "petrol", "electric", "hybrid", "hvo", "cng", "lng", "hydrogen"], "default": "diesel" }
          },
          {
            "name": "service_type",
            "in": "query",
            "description": "Service type affecting load factor",
            "schema": { "type": "string", "enum": ["shared", "dedicated", "ftl", "ltl"], "default": "shared" }
          },
          {
            "name": "refrigerated",
            "in": "query",
            "description": "Refrigerated transport adds +20% to emissions",
            "schema": { "type": "boolean", "default": false }
          },
          {
            "name": "include_empty_return",
            "in": "query",
            "description": "Include empty return journey in the calculation",
            "schema": { "type": "boolean", "default": false }
          },
          {
            "name": "planned_distance_km",
            "in": "query",
            "description": "Override the calculated distance with a known value in km",
            "schema": { "type": "number", "minimum": 0.1 }
          },
          {
            "name": "equivalents",
            "in": "query",
            "description": "Include real-world equivalents (trees, driving km, etc.)",
            "schema": { "type": "boolean", "default": false }
          },
          {
            "name": "detailed_route",
            "in": "query",
            "description": "Include an encoded polyline for map rendering (road mode only)",
            "schema": { "type": "boolean", "default": false }
          }
        ],
        "responses": {
          "200": {
            "description": "Freight emission calculation",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/FreightEmissionResponse" },
                "example": {
                  "data": {
                    "type": "freight_emission",
                    "id": "28010c75-4b86-4b34-93bb-31c937755b43",
                    "attributes": {
                      "emissions": {
                        "co2e": 711.5,
                        "co2e_unit": "kg",
                        "co2e_calculation_method": "ipcc_ar6_gwp100",
                        "co2e_grams": 711500,
                        "energy_usage_mj": 6590.4,
                        "lifecycle_breakdown": { "unit": "kg", "vehicle_operation": 549.2, "energy_provision": 137.3, "freight_activities": 25 },
                        "ghg_protocol_scopes": {
                          "asset_owner": { "scope_1": 549.2, "scope_2": 0, "scope_3_category_3": 137.3 },
                          "freight_buyer": { "scope_3_category_4": 711.5 }
                        },
                        "equivalents": {
                          "trees_yearly": { "value": 33.88, "label": "trees needed to absorb this CO₂ in a year" },
                          "driving_km": { "value": 4185.3, "label": "km driven in an average car" },
                          "smartphone_charges": { "value": 88938, "label": "smartphone charges" },
                          "netflix_hours": { "value": 11858.3, "label": "hours of Netflix watched" }
                        },
                        "source_trail": [
                          {
                            "data_category": "emission_factor",
                            "name": "Average Road Freight Vehicle",
                            "source": "GLEC",
                            "source_dataset": "Default fuel efficiency and GHG emission intensity values v3.1",
                            "year": "2024",
                            "region": "EU_S_AMERICA",
                            "region_name": "Europe and South America"
                          }
                        ]
                      },
                      "cargo": {
                        "weight_input": 5000,
                        "unit_input": "kg",
                        "weight_normalized_kg": 5000,
                        "service_type": "shared",
                        "cargo_tonnes": 5
                      },
                      "vehicle": {
                        "requested": "average",
                        "class_used": "Average Road Freight Vehicle",
                        "fuel_source": "diesel",
                        "empty_return_included": false
                      },
                      "route": {
                        "type": "direct",
                        "total_distance_km": 1098,
                        "transport_mode": "road",
                        "origin": {
                          "input": "London",
                          "resolved": "Greater London, England, United Kingdom",
                          "country_code": "GB",
                          "lat": 51.50745,
                          "lon": -0.12777,
                          "confidence_score": 0.99
                        },
                        "destination": {
                          "input": "Berlin",
                          "resolved": "Berlin, Germany",
                          "country_code": "DE",
                          "lat": 52.51739,
                          "lon": 13.39513,
                          "confidence_score": 0.96
                        },
                        "waypoints": [
                          { "lat": 51.2858, "lon": 0.57454 },
                          { "lat": 50.91491, "lon": 1.8015 },
                          { "lat": 51.19318, "lon": 3.07442 }
                        ],
                        "duration_seconds": 42979,
                        "duration_formatted": "11h 56m"
                      },
                      "geography": {
                        "origin_country": "GB",
                        "destination_country": "DE",
                        "transit_countries": ["GB", "DE", "FR", "BE", "NL"],
                        "border_crossing": true
                      },
                      "notices": []
                    }
                  },
                  "meta": {
                    "methodology": "GLEC Framework v3.1",
                    "emission_factors_year": 2025,
                    "standards_compliance": {
                      "ISO_14083": "Aligns with default intensity values",
                      "GHG_Protocol": "Scope 1 (TTW), Scope 2 (purchased energy), Scope 3 (upstream)"
                    },
                    "distance_method": "road_routing",
                    "units": "metric",
                    "version": "1.0.6",
                    "calculated_at": "2026-11-19T15:09:11Z"
                  }
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "422": { "$ref": "#/components/responses/ValidationError" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/travel/emissions": {
      "get": {
        "operationId": "calculateTravelEmissions",
        "summary": "Calculate travel emissions",
        "description": "Calculate CO₂e emissions for passenger travel between two locations. Supports flights, rail, car, bus, ferry, and taxi with cabin class multipliers, location-aware EV calculations, and real road routing.",
        "tags": ["Travel"],
        "parameters": [
          {
            "name": "origin_country",
            "in": "query",
            "required": true,
            "description": "Origin country code (ISO 3166-1 alpha-2)",
            "schema": { "type": "string", "pattern": "^[A-Z]{2}$", "example": "GB" }
          },
          {
            "name": "destination_country",
            "in": "query",
            "required": true,
            "description": "Destination country code (ISO 3166-1 alpha-2)",
            "schema": { "type": "string", "pattern": "^[A-Z]{2}$", "example": "FR" }
          },
          {
            "name": "origin_location",
            "in": "query",
            "description": "Origin city, address, or airport code",
            "schema": { "type": "string", "example": "London" }
          },
          {
            "name": "destination_location",
            "in": "query",
            "description": "Destination city, address, or airport code",
            "schema": { "type": "string", "example": "Paris" }
          },
          {
            "name": "passengers",
            "in": "query",
            "description": "Number of passengers (1–10). Required: omitting it returns 422.",
            "schema": { "type": "integer", "minimum": 1, "maximum": 10 },
            "required": true
          },
          {
            "name": "transport_mode",
            "in": "query",
            "description": "Transport mode. `auto` detects the best mode.",
            "schema": { "type": "string", "enum": ["auto", "flight", "rail", "car", "bus", "ferry", "taxi"], "default": "auto" }
          },
          {
            "name": "return_trip",
            "in": "query",
            "description": "Include return journey (doubles emissions)",
            "schema": { "type": "boolean", "default": false }
          },
          {
            "name": "cabin_class",
            "in": "query",
            "description": "Cabin class for flights. Economy (1×), Premium Economy (1.6×), Business (2.9×), First (4×).",
            "schema": { "type": "string", "enum": ["economy", "premium_economy", "business", "first"], "default": "economy" }
          },
          {
            "name": "vehicle_type",
            "in": "query",
            "description": "Car/taxi vehicle. Accepts a size (`small`, `medium`, `large`, `average`) or a powertrain (`petrol`, `diesel`, `hybrid`, `phev`, `bev`). The powertrain is selected through this parameter; there is no separate fuel parameter.",
            "schema": {
              "type": "string",
              "enum": ["small", "medium", "large", "average", "petrol", "diesel", "hybrid", "phev", "bev"],
              "default": "average"
            }
          },
          {
            "name": "distance_km",
            "in": "query",
            "description": "Override calculated distance with a known value in km",
            "schema": { "type": "number", "minimum": 0.1 }
          },
          {
            "name": "equivalents",
            "in": "query",
            "description": "Include real-world equivalents",
            "schema": { "type": "boolean", "default": false }
          }
        ],
        "responses": {
          "200": {
            "description": "Travel emission calculation",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/TravelEmissionResponse" },
                "example": {
                  "data": {
                    "type": "travel_emission",
                    "id": "87a78641-4843-4f58-93f9-dd1503e68beb",
                    "attributes": {
                      "emissions": {
                        "co2e": 706.3,
                        "co2e_unit": "kg",
                        "co2e_calculation_method": "ipcc_ar6_gwp100",
                        "co2e_grams": 706300,
                        "per_passenger_kg": 706.3,
                        "per_passenger_g": 706300,
                        "source_trail": [
                          {
                            "data_category": "emission_factor",
                            "name": "Long-Haul Flight - Economy Class",
                            "source": "DEFRA / ICAO",
                            "source_dataset": "Greenhouse gas reporting: conversion factors 2025",
                            "year": "2025",
                            "region": "GB",
                            "region_name": "United Kingdom"
                          }
                        ]
                      },
                      "direct_emissions": { "co2e": 565.04, "co2e_unit": "kg", "description": "Tank-to-wheel / tailpipe emissions" },
                      "indirect_emissions": { "co2e": 141.26, "co2e_unit": "kg", "description": "Well-to-tank / upstream fuel production emissions" },
                      "journey": { "passengers": 1, "return_trip": false, "mode": "flight", "cabin_class": "economy" },
                      "vehicle": { "requested": "auto", "class_used": "Long-Haul Flight - Economy Class" },
                      "route": {
                        "type": "direct",
                        "total_distance_km": 6035,
                        "transport_mode": "flight",
                        "origin": {
                          "input": "London",
                          "resolved": "Greater London, England, United Kingdom",
                          "country_code": "GB",
                          "lat": 51.50745,
                          "lon": -0.12777,
                          "confidence_score": 0.99,
                          "airport_used": { "code": "LHR", "name": "London Heathrow Airport" }
                        },
                        "destination": {
                          "input": "New York",
                          "resolved": "New York, New York, USA",
                          "country_code": "US",
                          "lat": 40.71273,
                          "lon": -74.00602,
                          "confidence_score": 1,
                          "airport_used": { "code": "LGA", "name": "LaGuardia Airport" }
                        },
                        "includes_radiative_forcing": true,
                        "radiative_forcing_multiplier": 1.7
                      },
                      "geography": { "origin_country": "GB", "destination_country": "US", "transit_countries": ["GB", "US"], "border_crossing": true },
                      "notices": [
                        {
                          "message": "DEFRA emission factors include radiative forcing effects for aviation.",
                          "code": "radiative_forcing_included",
                          "severity": "info"
                        },
                        {
                          "message": "Using UK (DEFRA) emission factors as proxy for this region. Regional factors may vary slightly.",
                          "code": "regional_proxy_factors",
                          "severity": "info"
                        }
                      ]
                    }
                  },
                  "meta": {
                    "methodology": "DEFRA 2025 / ICAO",
                    "emission_factors_year": 2025,
                    "standards_compliance": {
                      "ISO_14083": "Aligns with passenger transport intensity values",
                      "GHG_Protocol": "Scope 3 Category 6 (Business Travel)"
                    },
                    "distance_method": "great_circle_airport",
                    "version": "1.0.6",
                    "calculated_at": "2026-11-19T15:09:46Z"
                  }
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "422": { "$ref": "#/components/responses/ValidationError" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/hotel/emissions": {
      "get": {
        "operationId": "calculateHotelEmissions",
        "summary": "Calculate hotel emissions",
        "description": "Calculate CO₂e emissions for hotel accommodation based on country-specific factors from DEFRA 2025 and the Cornell Hotel Sustainability Benchmarking Index. Covers 60+ countries.",
        "tags": ["Hotel"],
        "parameters": [
          {
            "name": "country",
            "in": "query",
            "required": true,
            "description": "Country code (ISO 3166-1 alpha-2)",
            "schema": { "type": "string", "pattern": "^[A-Z]{2}$", "example": "GB" }
          },
          {
            "name": "nights",
            "in": "query",
            "required": true,
            "description": "Number of nights",
            "schema": { "type": "integer", "minimum": 1, "maximum": 365, "example": 3 }
          },
          {
            "name": "rooms",
            "in": "query",
            "description": "Number of rooms",
            "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 1 }
          },
          {
            "name": "equivalents",
            "in": "query",
            "description": "Include real-world equivalents",
            "schema": { "type": "boolean", "default": false }
          }
        ],
        "responses": {
          "200": {
            "description": "Hotel emission calculation",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/HotelEmissionResponse" },
                "example": {
                  "data": {
                    "type": "hotel_emission",
                    "id": "6b720893-dadf-4820-9daa-c13ec61c58f8",
                    "attributes": {
                      "emissions": {
                        "co2e": 31.2,
                        "co2e_unit": "kg",
                        "co2e_calculation_method": "ipcc_ar6_gwp100",
                        "co2e_grams": 31200,
                        "per_night_kg": 10.4,
                        "per_room_night_kg": 10.4,
                        "breakdown": { "unit": "kg", "electricity": 18.72, "heating_cooling": 7.8, "water": 3.12, "waste": 1.56 },
                        "equivalents": null,
                        "source_trail": [
                          {
                            "data_category": "emission_factor",
                            "name": "Hotel stay - United Kingdom",
                            "source": "DEFRA",
                            "source_dataset": "Greenhouse gas reporting: conversion factors 2025",
                            "original_data": "Cornell Hotel Sustainability Benchmarking Index",
                            "year": "2025",
                            "region": "GB",
                            "region_name": "United Kingdom"
                          }
                        ]
                      },
                      "stay": { "country_code": "GB", "country_name": "United Kingdom", "nights": 3, "rooms": 1, "total_room_nights": 3 },
                      "factor": { "value": 10.4, "unit": "kg CO2e per room per night", "is_estimate": false, "region": "europe" },
                      "notices": []
                    }
                  },
                  "meta": {
                    "methodology": "DEFRA 2025 / Cornell CHSB Index",
                    "emission_factors_year": 2025,
                    "standards_compliance": { "GHG_Protocol": "Scope 3 Category 6 (Business Travel)" },
                    "version": "1.0.6",
                    "calculated_at": "2026-11-19T15:09:13Z"
                  }
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "422": { "$ref": "#/components/responses/ValidationError" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/hotel/factors": {
      "get": {
        "operationId": "listHotelFactors",
        "summary": "List hotel emission factors",
        "description": "Get all available country emission factors for hotel stays, sorted by emissions (lowest first). Covers 60+ countries.",
        "tags": ["Hotel"],
        "parameters": [],
        "responses": {
          "200": {
            "description": "List of country hotel emission factors",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/HotelFactorsResponse" },
                "example": {
                  "data": [
                    {
                      "country_code": "CR",
                      "country_name": "Costa Rica",
                      "factor": 4.7,
                      "unit": "kg CO2e per room per night",
                      "region": "south_america"
                    },
                    {
                      "country_code": "SE",
                      "country_name": "Sweden",
                      "factor": 4.9,
                      "unit": "kg CO2e per room per night",
                      "region": "europe"
                    },
                    {
                      "country_code": "NO",
                      "country_name": "Norway",
                      "factor": 5.2,
                      "unit": "kg CO2e per room per night",
                      "region": "europe"
                    }
                  ],
                  "meta": { "total_countries": 60, "source": "DEFRA 2025 / Cornell CHSB Index", "unit": "kg CO2e per room per night" }
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/hotel/compare": {
      "get": {
        "operationId": "compareHotelEmissions",
        "summary": "Compare hotel emissions across countries",
        "description": "Compare hotel emissions across multiple countries for the same stay duration. Results sorted by total emissions (lowest first).",
        "tags": ["Hotel"],
        "parameters": [
          {
            "name": "country",
            "in": "query",
            "required": true,
            "description": "Comma-separated country codes (2–10 countries). Note: the docs call this parameter `countries`, but the API only accepts `country`.",
            "schema": { "type": "string", "example": "GB,FR,DE,SE" }
          },
          {
            "name": "nights",
            "in": "query",
            "description": "Number of nights",
            "schema": { "type": "integer", "minimum": 1, "maximum": 365, "default": 1 }
          },
          {
            "name": "rooms",
            "in": "query",
            "description": "Number of rooms",
            "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 1 }
          }
        ],
        "responses": {
          "200": {
            "description": "Country comparison results",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/HotelCompareResponse" },
                "example": {
                  "data": [
                    {
                      "country_code": "FR",
                      "country_name": "France",
                      "total_kg": 33.5,
                      "per_room_night_kg": 6.7,
                      "region": "europe",
                      "is_estimate": false,
                      "savings_vs_highest_kg": 33.5,
                      "savings_vs_highest_percent": 50
                    },
                    {
                      "country_code": "GB",
                      "country_name": "United Kingdom",
                      "total_kg": 52,
                      "per_room_night_kg": 10.4,
                      "region": "europe",
                      "is_estimate": false,
                      "savings_vs_highest_kg": 15,
                      "savings_vs_highest_percent": 22.4
                    },
                    {
                      "country_code": "DE",
                      "country_name": "Germany",
                      "total_kg": 67,
                      "per_room_night_kg": 13.4,
                      "region": "europe",
                      "is_estimate": false,
                      "savings_vs_highest_kg": 0,
                      "savings_vs_highest_percent": 0
                    }
                  ],
                  "meta": { "nights": 5, "rooms": 1, "total_room_nights": 5, "lowest_emissions": "FR", "highest_emissions": "DE" }
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "422": { "$ref": "#/components/responses/ValidationError" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/electricity/emissions": {
      "get": {
        "operationId": "calculateElectricityEmissions",
        "summary": "Calculate electricity emissions",
        "description": "Calculate CO₂e emissions from electricity consumption based on grid carbon intensity. Supports 100+ countries, 50 US states, and cloud provider regions (AWS, GCP, Azure). GHG Protocol Scope 2 compliant.",
        "tags": ["Electricity"],
        "parameters": [
          {
            "name": "kwh",
            "in": "query",
            "required": true,
            "description": "Electricity consumed (in units specified by `unit`)",
            "schema": { "type": "number", "minimum": 0.001, "example": 5000 }
          },
          {
            "name": "unit",
            "in": "query",
            "description": "Input unit for the kwh parameter",
            "schema": { "type": "string", "enum": ["kwh", "mwh", "wh"], "default": "kwh" }
          },
          {
            "name": "country",
            "in": "query",
            "description": "Country code (ISO 3166-1 alpha-2). Defaults to GB.",
            "schema": { "type": "string", "pattern": "^[A-Z]{2}$", "default": "GB", "example": "DE" }
          },
          {
            "name": "state",
            "in": "query",
            "description": "US state code (requires country=US)",
            "schema": { "type": "string", "example": "CA" }
          },
          {
            "name": "cloud_provider",
            "in": "query",
            "description": "Cloud provider for data centre emissions",
            "schema": { "type": "string", "enum": ["aws", "gcp", "azure"] }
          },
          {
            "name": "cloud_region",
            "in": "query",
            "description": "Cloud region identifier (e.g., eu-west-1, us-central1, westeurope)",
            "schema": { "type": "string", "example": "eu-west-1" }
          },
          {
            "name": "include_wtt",
            "in": "query",
            "description": "Include Well-to-Tank upstream emissions (Scope 3 Category 3)",
            "schema": { "type": "boolean", "default": true }
          },
          {
            "name": "include_td_losses",
            "in": "query",
            "description": "Include transmission and distribution losses (+8%)",
            "schema": { "type": "boolean", "default": false }
          },
          {
            "name": "equivalents",
            "in": "query",
            "description": "Include real-world equivalents",
            "schema": { "type": "boolean", "default": false }
          }
        ],
        "responses": {
          "200": {
            "description": "Electricity emission calculation",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/ElectricityEmissionResponse" },
                "example": {
                  "data": {
                    "type": "electricity_emission",
                    "id": "0d4db681-9124-4bec-868f-03d77f574884",
                    "attributes": {
                      "emissions": {
                        "co2e": 15222,
                        "co2e_unit": "kg",
                        "co2e_calculation_method": "ipcc_ar6_gwp100",
                        "co2e_grams": 15222000,
                        "lifecycle_breakdown": { "scope_2_location_based": 12900, "scope_3_wtt": 2322, "unit": "kg" },
                        "ghg_protocol_scopes": {
                          "scope_2": {
                            "location_based": 12900,
                            "market_based": null,
                            "method_note": "Market-based requires supplier-specific emission factors or residual mix data. Pass market_based_factor for Scope 2 market-based reporting."
                          },
                          "scope_3_category_3": 2322
                        },
                        "equivalents": null,
                        "source_trail": [
                          {
                            "data_category": "grid_intensity",
                            "name": "Electricity grid carbon intensity — 258 gCO₂e/kWh",
                            "source": "Electricity Maps / Cloud provider disclosures",
                            "source_dataset": "Electricity Maps / Cloud provider disclosures",
                            "year": "2025",
                            "region": "aws/eu-west-1",
                            "region_name": "aws/eu-west-1"
                          },
                          {
                            "data_category": "wtt_factor",
                            "name": "Well-to-Tank upstream emissions factor",
                            "source": "DEFRA",
                            "source_dataset": "Greenhouse gas reporting: conversion factors 2025",
                            "year": "2025",
                            "region": "GB",
                            "region_name": "United Kingdom (global proxy)"
                          }
                        ]
                      },
                      "consumption": { "kwh": 50000, "effective_kwh": 50000, "include_wtt": true, "include_td_losses": false },
                      "grid": {
                        "carbon_intensity": 258,
                        "unit": "gCO2e/kWh",
                        "source": "cloud_region",
                        "resolved_location": "aws/eu-west-1",
                        "is_clean_grid": false,
                        "last_updated": "2026-02-09"
                      },
                      "notices": [
                        {
                          "message": "This is a location-based Scope 2 calculation. For market-based reporting, use your energy supplier's specific emission factor.",
                          "code": "location_based_method",
                          "severity": "info"
                        },
                        {
                          "message": "Grid intensity based on cloud provider region data. Actual emissions may vary based on provider's renewable energy procurement.",
                          "code": "cloud_region_estimate",
                          "severity": "info"
                        }
                      ]
                    }
                  },
                  "meta": {
                    "methodology": "GHG Protocol Scope 2 Guidance",
                    "emission_factors_year": 2025,
                    "standards_compliance": { "GHG_Protocol": "Scope 2 location-based method", "ISO_14064": "Part 1 - Organisation level" },
                    "version": "1.0.6",
                    "calculated_at": "2026-11-19T15:09:14Z"
                  }
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "422": { "$ref": "#/components/responses/ValidationError" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/electricity/grid": {
      "get": {
        "operationId": "listGridIntensity",
        "summary": "List grid carbon intensity factors",
        "description": "Get all available grid carbon intensity factors for 100+ countries, ranked from lowest to highest emissions.",
        "tags": ["Electricity"],
        "parameters": [
          {
            "name": "region",
            "in": "query",
            "description": "Filter by geographic region",
            "schema": { "type": "string", "enum": ["europe", "north_america", "asia", "oceania", "africa", "south_america"] }
          }
        ],
        "responses": {
          "200": {
            "description": "List of grid intensity factors",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/GridIntensityResponse" },
                "example": {
                  "data": [
                    { "country_code": "IS", "country_name": "Iceland", "carbon_intensity": 15, "unit": "gCO2e/kWh", "region": "europe" },
                    { "country_code": "BT", "country_name": "Bhutan", "carbon_intensity": 20, "unit": "gCO2e/kWh", "region": "asia" },
                    { "country_code": "NP", "country_name": "Nepal", "carbon_intensity": 25, "unit": "gCO2e/kWh", "region": "asia" }
                  ],
                  "meta": { "total_countries": 109, "last_updated": "2026-02-09", "version": "1.0.6" }
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/fuel/emissions": {
      "get": {
        "operationId": "calculateFuelEmissions",
        "summary": "Calculate fuel combustion emissions",
        "description": "Calculate CO₂e emissions from direct fuel combustion (Scope 1). Covers 16 fuel types across gaseous, liquid, solid, and biofuel categories with individual CO₂, CH₄, and N₂O breakdown. DEFRA 2025 factors.",
        "tags": ["Fuel"],
        "parameters": [
          {
            "name": "fuel_type",
            "in": "query",
            "required": true,
            "description": "Fuel type identifier",
            "schema": {
              "type": "string",
              "enum": [
                "natural_gas",
                "lpg",
                "cng",
                "biogas",
                "diesel",
                "petrol",
                "kerosene",
                "fuel_oil",
                "red_diesel",
                "biodiesel",
                "hvo",
                "bioethanol",
                "wood_logs",
                "wood_pellets",
                "coal_industrial",
                "coal_domestic"
              ],
              "example": "natural_gas"
            }
          },
          {
            "name": "amount",
            "in": "query",
            "required": true,
            "description": "Quantity of fuel consumed",
            "schema": { "type": "number", "minimum": 0.001, "example": 15000 }
          },
          {
            "name": "unit",
            "in": "query",
            "description": "Unit of measurement. Defaults to the most common unit for the fuel type. Available units vary by fuel.",
            "schema": { "type": "string", "example": "kwh" }
          },
          {
            "name": "include_wtt",
            "in": "query",
            "description": "Include Well-to-Tank upstream emissions (Scope 3 Category 3)",
            "schema": { "type": "boolean", "default": true }
          },
          {
            "name": "equivalents",
            "in": "query",
            "description": "Include real-world equivalents",
            "schema": { "type": "boolean", "default": false }
          }
        ],
        "responses": {
          "200": {
            "description": "Fuel emission calculation",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/FuelEmissionResponse" },
                "example": {
                  "data": {
                    "type": "fuel_emission",
                    "id": "a5c7c528-5730-4887-90da-8ca4bf772a30",
                    "attributes": {
                      "emissions": {
                        "co2e": 3152.47,
                        "co2e_unit": "kg",
                        "co2e_calculation_method": "ipcc_ar6_gwp100",
                        "co2e_grams": 3152470,
                        "breakdown": {
                          "direct_co2e": 2512.1,
                          "direct_co2": 2494.6,
                          "direct_ch4": 0.11,
                          "direct_n2o": 16.4,
                          "wtt_co2e": 640.37,
                          "unit": "kg"
                        },
                        "ghg_protocol_scopes": { "scope_1": 2512.1, "scope_3_category_3": 640.37 },
                        "equivalents": null,
                        "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 (global proxy)"
                          }
                        ]
                      },
                      "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" },
                    "version": "1.0.6",
                    "calculated_at": "2026-11-19T15:09:14Z"
                  }
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "422": { "$ref": "#/components/responses/ValidationError" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/fuel/types": {
      "get": {
        "operationId": "listFuelTypes",
        "summary": "List supported fuel types",
        "description": "Get all 16 supported fuel types with their available units, categories, and default units.",
        "tags": ["Fuel"],
        "parameters": [
          {
            "name": "category",
            "in": "query",
            "description": "Filter by fuel category",
            "schema": { "type": "string", "enum": ["gaseous", "liquid", "solid", "biofuel"] }
          }
        ],
        "responses": {
          "200": {
            "description": "List of fuel types",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/FuelTypesResponse" },
                "example": {
                  "data": [
                    {
                      "fuel_type": "natural_gas",
                      "label": "Natural Gas",
                      "category": "gaseous",
                      "is_biofuel": false,
                      "available_units": ["kwh", "therm", "m3"],
                      "default_unit": "kwh"
                    },
                    {
                      "fuel_type": "lpg",
                      "label": "LPG (Liquefied Petroleum Gas)",
                      "category": "gaseous",
                      "is_biofuel": false,
                      "available_units": ["kwh", "litre", "kg"],
                      "default_unit": "litre"
                    },
                    {
                      "fuel_type": "cng",
                      "label": "CNG (Compressed Natural Gas)",
                      "category": "gaseous",
                      "is_biofuel": false,
                      "available_units": ["kwh", "kg"],
                      "default_unit": "kg"
                    }
                  ],
                  "meta": {
                    "total_fuel_types": 16,
                    "categories": ["gaseous", "liquid", "solid", "biofuel"],
                    "source": "DEFRA 2025 - GHG Conversion Factors",
                    "version": "1.0.6"
                  }
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/digital/llm/emissions": {
      "get": {
        "operationId": "calculateLlmEmissions",
        "summary": "Calculate LLM inference emissions (Beta)",
        "description": "Estimate CO₂e emissions from large language model inference based on provider, model, token counts, and regional grid intensity. Covers 80+ models across 12 providers with automatic reasoning model detection and prompt caching support.",
        "tags": ["Digital"],
        "parameters": [
          {
            "name": "provider",
            "in": "query",
            "description": "LLM provider",
            "schema": {
              "type": "string",
              "enum": [
                "openai",
                "anthropic",
                "google",
                "meta",
                "mistral",
                "cohere",
                "deepseek",
                "xai",
                "azure_openai",
                "aws_bedrock",
                "gcp_vertex",
                "self_hosted"
              ],
              "default": "openai"
            }
          },
          {
            "name": "model",
            "in": "query",
            "description": "Model identifier. Unknown models are auto-classified by name pattern.",
            "schema": { "type": "string", "default": "gpt-5.2", "example": "claude-opus-4.5" }
          },
          {
            "name": "tokens_input",
            "in": "query",
            "description": "Number of input (prompt) tokens",
            "schema": { "type": "integer", "minimum": 0, "default": 0, "example": 5000 }
          },
          {
            "name": "tokens_output",
            "in": "query",
            "description": "Number of output (completion) tokens",
            "schema": { "type": "integer", "minimum": 0, "default": 0, "example": 2000 }
          },
          {
            "name": "tokens_cached",
            "in": "query",
            "description": "Number of cached input tokens (90% energy reduction applied)",
            "schema": { "type": "integer", "minimum": 0, "default": 0 }
          },
          {
            "name": "requests",
            "in": "query",
            "description": "Number of requests to calculate for",
            "schema": { "type": "integer", "minimum": 1, "maximum": 10000000, "default": 1 }
          },
          {
            "name": "reasoning_effort",
            "in": "query",
            "description": "Override thinking ratio for reasoning models: none (1×), low (2×), medium (4×), high (6×), xhigh (10×). Auto-detected if omitted.",
            "schema": { "type": "string", "enum": ["none", "low", "medium", "high", "xhigh"] }
          },
          {
            "name": "region",
            "in": "query",
            "description": "ISO country code or US state code for grid intensity. Defaults to provider's primary country.",
            "schema": { "type": "string", "example": "FR" }
          },
          {
            "name": "equivalents",
            "in": "query",
            "description": "Include real-world equivalents (Google searches, smartphone charges, etc.)",
            "schema": { "type": "boolean", "default": false }
          }
        ],
        "responses": {
          "200": {
            "description": "LLM emission estimate",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/LlmEmissionResponse" },
                "example": {
                  "data": {
                    "type": "llm_emission",
                    "id": "0eb85024-a894-4cec-9309-a7babeedd928",
                    "attributes": {
                      "emissions": {
                        "co2e": 0.7813,
                        "co2e_unit": "g",
                        "co2e_calculation_method": "ipcc_ar6_gwp100",
                        "breakdown": { "operational_co2e": 0.4812, "embodied_co2e": 0.3, "unit": "g" },
                        "energy_usage": {
                          "total_wh": 1.375,
                          "total_kwh": 0.001375,
                          "per_request_wh": 1.375,
                          "breakdown": {
                            "base_energy_wh": 0.5,
                            "input_tokens_wh": 0.25,
                            "output_tokens_wh": 0.5,
                            "reasoning_overhead_wh": 0,
                            "pue_overhead_wh": 0.1375
                          }
                        },
                        "ghg_protocol_scopes": {
                          "scope_2": {
                            "location_based": 0.4812,
                            "method_note": "Based on regional grid intensity for the provider/region. Covers electricity consumed during inference."
                          },
                          "scope_3_category_1": 0.3
                        },
                        "source_trail": [
                          {
                            "data_category": "energy_model",
                            "name": "LLM Energy Consumption — Frontier tier",
                            "source": "Epoch AI / Google / SemiAnalysis",
                            "source_dataset": "Composite: How Much Energy Does ChatGPT Use (2025), Gemini Environmental Report (2025), AI Datacenter Energy (2024)",
                            "year": "2025",
                            "region": "GLOBAL"
                          },
                          {
                            "data_category": "grid_intensity",
                            "name": "US — 350 gCO₂e/kWh",
                            "source": "Ember / Electricity Maps",
                            "source_dataset": "Cloud provider regional grid intensity",
                            "year": "2025",
                            "region": "US"
                          }
                        ]
                      },
                      "inference": {
                        "provider": "openai",
                        "model": "gpt-5.2",
                        "tier": "frontier",
                        "is_known_model": true,
                        "is_reasoning_model": false,
                        "thinking_ratio": 1,
                        "tokens": { "input": 5000, "output": 2000, "cached": 0, "reasoning_estimated": 0, "effective_output": 2000 },
                        "requests": 1
                      },
                      "grid": { "carbon_intensity": 350, "carbon_intensity_unit": "gCO2e/kWh", "region": "US" },
                      "notices": []
                    }
                  },
                  "meta": {
                    "methodology": "Energy-per-token estimation with hardware amortization",
                    "emission_factors_year": 2025,
                    "standards_compliance": {
                      "GHG_Protocol": "Scope 2 (purchased electricity) + Scope 3 Category 1 (embodied hardware)",
                      "ISO_14040": "Lifecycle assessment aligned"
                    },
                    "version": "1.0.6",
                    "calculated_at": "2026-11-19T15:09:15Z"
                  }
                }
              }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "422": { "$ref": "#/components/responses/ValidationError" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "API key with `em_live_` prefix. Get your key at https://emissions.dev/dashboard"
      }
    },
    "responses": {
      "Unauthorized": {
        "description": "Missing or invalid API key",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/ErrorResponse" },
            "example": {
              "error": { "message": "Invalid API key format.", "status": 401 }
            }
          }
        }
      },
      "ValidationError": {
        "description": "Request validation failed",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/ErrorResponse" },
            "example": {
              "error": {
                "code": "validation_error",
                "message": "Freight calculation requires a 'weight'.",
                "field": "weight",
                "status": 422,
                "all_errors": { "weight": ["Freight calculation requires a 'weight'."] }
              }
            }
          }
        }
      },
      "RateLimited": {
        "description": "Too many requests: per-second rate limit or monthly quota exceeded. Responses carry `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-Monthly-Usage` and `X-Monthly-Limit` headers.",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/ErrorResponse" },
            "example": {
              "error": { "message": "Rate limit exceeded. Try again in 1 seconds.", "status": 429 }
            }
          }
        }
      }
    },
    "schemas": {
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string",
                "description": "Machine-readable error code (e.g. `validation_error`, `unauthorized`, `not_found`). Not present on every error: malformed-key 401s and 429s omit it."
              },
              "message": { "type": "string" },
              "field": { "type": "string" },
              "status": { "type": "integer" },
              "all_errors": {
                "type": "object",
                "description": "Validation errors keyed by parameter name (422 only).",
                "additionalProperties": {
                  "type": "array",
                  "items": { "type": "string" }
                }
              },
              "available_modes": {
                "type": "array",
                "items": { "type": "string" },
                "description": "Transport modes that would work for the route (freight `invalid_route` errors only)."
              }
            },
            "required": ["message", "status"]
          }
        }
      },
      "SourceTrailEntry": {
        "type": "object",
        "properties": {
          "data_category": {
            "type": "string",
            "description": "Category of data: emission_factor, grid_intensity, wtt_factor, energy_model, embodied_carbon"
          },
          "name": { "type": "string", "description": "Human-readable name of the factor" },
          "source": { "type": "string", "description": "Data source organisation (e.g., DEFRA, GLEC, Ember)" },
          "source_dataset": { "type": "string", "description": "Specific dataset name" },
          "year": { "type": "string", "description": "Data year" },
          "region": { "type": "string", "description": "Region code the factor applies to" },
          "region_name": { "type": "string", "description": "Human-readable region name" },
          "original_data": {
            "type": "string",
            "description": "Underlying dataset the source derives its factor from, when different (e.g. Cornell Hotel Sustainability Benchmarking Index)."
          }
        }
      },
      "Equivalents": {
        "type": "object",
        "properties": {
          "trees_yearly": {
            "type": "object",
            "properties": {
              "value": { "type": "number" },
              "label": { "type": "string" }
            }
          },
          "driving_km": {
            "type": "object",
            "properties": {
              "value": { "type": "number" },
              "label": { "type": "string" }
            }
          },
          "smartphone_charges": {
            "type": "object",
            "properties": {
              "value": { "type": "number" },
              "label": { "type": "string" }
            }
          },
          "netflix_hours": {
            "type": "object",
            "properties": {
              "value": { "type": "number" },
              "label": { "type": "string" }
            }
          }
        }
      },
      "Notice": {
        "type": "object",
        "properties": {
          "message": { "type": "string" },
          "code": { "type": "string" },
          "severity": { "type": "string", "enum": ["info", "warning"] }
        }
      },
      "FreightEmissionResponse": {
        "type": "object",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "type": { "type": "string", "const": "freight_emission" },
              "id": { "type": "string", "format": "uuid" },
              "attributes": {
                "type": "object",
                "properties": {
                  "emissions": {
                    "type": "object",
                    "properties": {
                      "co2e": { "type": "number", "description": "Total CO₂e in kg" },
                      "co2e_unit": { "type": "string", "const": "kg" },
                      "co2e_calculation_method": { "type": "string" },
                      "co2e_grams": { "type": "integer" },
                      "energy_usage_mj": { "type": "number" },
                      "lifecycle_breakdown": {
                        "type": "object",
                        "properties": {
                          "unit": { "type": "string" },
                          "vehicle_operation": { "type": "number" },
                          "energy_provision": { "type": "number" },
                          "freight_activities": { "type": "number", "description": "Further freight activity emissions (kg). Included in `co2e`, which is the sum of vehicle_operation, energy_provision and freight_activities." }
                        }
                      },
                      "ghg_protocol_scopes": {
                        "type": "object",
                        "properties": {
                          "asset_owner": {
                            "type": "object",
                            "properties": {
                              "scope_1": { "type": "number" },
                              "scope_2": { "type": "number" },
                              "scope_3_category_3": { "type": "number" }
                            }
                          },
                          "freight_buyer": {
                            "type": "object",
                            "properties": {
                              "scope_3_category_4": { "type": "number" }
                            }
                          }
                        }
                      },
                      "equivalents": {
                        "description": "Real-world equivalents. Only populated when `equivalents=true`; otherwise `null` or omitted.",
                        "anyOf": [
                          { "$ref": "#/components/schemas/Equivalents" },
                          { "type": "null" }
                        ]
                      },
                      "source_trail": {
                        "type": "array",
                        "items": { "$ref": "#/components/schemas/SourceTrailEntry" }
                      }
                    }
                  },
                  "cargo": {
                    "type": "object",
                    "properties": {
                      "weight_input": { "type": "number" },
                      "unit_input": { "type": "string" },
                      "weight_normalized_kg": { "type": "number" },
                      "cargo_tonnes": { "type": "number" },
                      "service_type": { "type": "string" }
                    }
                  },
                  "vehicle": {
                    "type": "object",
                    "properties": {
                      "requested": { "type": "string" },
                      "class_used": { "type": "string" },
                      "fuel_source": { "type": "string" },
                      "empty_return_included": { "type": "boolean" }
                    }
                  },
                  "route": {
                    "type": "object",
                    "properties": {
                      "type": { "type": "string" },
                      "total_distance_km": { "type": "number" },
                      "transport_mode": { "type": "string" },
                      "origin": { "$ref": "#/components/schemas/GeocodedLocation" },
                      "destination": { "$ref": "#/components/schemas/GeocodedLocation" },
                      "waypoints": {
                        "type": "array",
                        "items": {
                          "type": "object",
                          "properties": {
                            "lat": { "type": "number" },
                            "lon": { "type": "number" }
                          }
                        }
                      },
                      "duration_seconds": { "type": "number" },
                      "duration_formatted": { "type": "string" },
                      "polyline": { "type": ["string", "null"] },
                      "polyline_precision": { "type": ["integer", "null"] },
                      "attribution": { "type": ["string", "null"] }
                    }
                  },
                  "geography": {
                    "type": "object",
                    "properties": {
                      "origin_country": { "type": "string" },
                      "destination_country": { "type": "string" },
                      "transit_countries": {
                        "type": "array",
                        "items": { "type": "string" }
                      },
                      "border_crossing": { "type": "boolean" }
                    }
                  },
                  "notices": {
                    "type": "array",
                    "items": { "$ref": "#/components/schemas/Notice" }
                  }
                }
              }
            }
          },
          "meta": { "$ref": "#/components/schemas/Meta" }
        }
      },
      "TravelEmissionResponse": {
        "type": "object",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "type": { "type": "string", "const": "travel_emission" },
              "id": { "type": "string", "format": "uuid" },
              "attributes": {
                "type": "object",
                "properties": {
                  "emissions": {
                    "type": "object",
                    "properties": {
                      "co2e": { "type": "number", "description": "Total CO₂e in kg" },
                      "co2e_unit": { "type": "string", "const": "kg" },
                      "co2e_calculation_method": { "type": "string" },
                      "co2e_grams": { "type": "integer" },
                      "per_passenger_kg": { "type": "number" },
                      "per_passenger_g": { "type": "number" },
                      "equivalents": {
                        "description": "Real-world equivalents. Only populated when `equivalents=true`; otherwise `null` or omitted.",
                        "anyOf": [
                          { "$ref": "#/components/schemas/Equivalents" },
                          { "type": "null" }
                        ]
                      },
                      "source_trail": {
                        "type": "array",
                        "items": { "$ref": "#/components/schemas/SourceTrailEntry" }
                      }
                    }
                  },
                  "direct_emissions": {
                    "type": "object",
                    "properties": {
                      "co2e": { "type": "number" },
                      "co2e_unit": { "type": "string" },
                      "description": { "type": "string" }
                    }
                  },
                  "indirect_emissions": {
                    "type": "object",
                    "properties": {
                      "co2e": { "type": "number" },
                      "co2e_unit": { "type": "string" },
                      "description": { "type": "string" }
                    }
                  },
                  "journey": {
                    "type": "object",
                    "properties": {
                      "passengers": { "type": "integer" },
                      "return_trip": { "type": "boolean" },
                      "mode": { "type": "string" },
                      "cabin_class": { "type": "string", "description": "Flights only." }
                    }
                  },
                  "route": {
                    "type": "object",
                    "properties": {
                      "type": { "type": "string" },
                      "total_distance_km": { "type": "number" },
                      "transport_mode": { "type": "string" },
                      "origin": {
                        "allOf": [
                          { "$ref": "#/components/schemas/GeocodedLocation" },
                          {
                            "type": "object",
                            "properties": {
                              "airport_used": {
                                "type": "object",
                                "description": "Airport used for the calculation (flights only).",
                                "properties": {
                                  "code": { "type": "string" },
                                  "name": { "type": "string" }
                                }
                              }
                            }
                          }
                        ]
                      },
                      "destination": {
                        "allOf": [
                          { "$ref": "#/components/schemas/GeocodedLocation" },
                          {
                            "type": "object",
                            "properties": {
                              "airport_used": {
                                "type": "object",
                                "description": "Airport used for the calculation (flights only).",
                                "properties": {
                                  "code": { "type": "string" },
                                  "name": { "type": "string" }
                                }
                              }
                            }
                          }
                        ]
                      },
                      "includes_radiative_forcing": { "type": "boolean", "description": "Flights only." },
                      "radiative_forcing_multiplier": { "type": "number", "description": "Flights only." },
                      "estimated_duration_seconds": { "type": "integer", "description": "Road modes only." },
                      "waypoints": {
                        "type": "array",
                        "items": {
                          "type": "object",
                          "properties": {
                            "lat": { "type": "number" },
                            "lon": { "type": "number" }
                          }
                        }
                      }
                    }
                  },
                  "geography": {
                    "type": "object",
                    "properties": {
                      "origin_country": { "type": "string" },
                      "destination_country": { "type": "string" },
                      "border_crossing": { "type": "boolean" },
                      "transit_countries": {
                        "type": "array",
                        "items": { "type": "string" }
                      }
                    }
                  },
                  "notices": {
                    "type": "array",
                    "items": { "$ref": "#/components/schemas/Notice" }
                  },
                  "vehicle": {
                    "type": "object",
                    "properties": {
                      "requested": { "type": "string" },
                      "class_used": { "type": "string" }
                    }
                  }
                }
              }
            }
          },
          "meta": { "$ref": "#/components/schemas/Meta" }
        }
      },
      "HotelEmissionResponse": {
        "type": "object",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "type": { "type": "string", "const": "hotel_emission" },
              "id": { "type": "string", "format": "uuid" },
              "attributes": {
                "type": "object",
                "properties": {
                  "emissions": {
                    "type": "object",
                    "properties": {
                      "co2e": { "type": "number" },
                      "co2e_unit": { "type": "string", "const": "kg" },
                      "co2e_grams": { "type": "integer" },
                      "per_night_kg": { "type": "number" },
                      "per_room_night_kg": { "type": "number" },
                      "breakdown": {
                        "type": "object",
                        "properties": {
                          "unit": { "type": "string" },
                          "electricity": { "type": "number" },
                          "heating_cooling": { "type": "number" },
                          "water": { "type": "number" },
                          "waste": { "type": "number" }
                        }
                      },
                      "equivalents": {
                        "description": "Real-world equivalents. Only populated when `equivalents=true`; otherwise `null` or omitted.",
                        "anyOf": [
                          { "$ref": "#/components/schemas/Equivalents" },
                          { "type": "null" }
                        ]
                      },
                      "source_trail": {
                        "type": "array",
                        "items": { "$ref": "#/components/schemas/SourceTrailEntry" }
                      },
                      "co2e_calculation_method": { "type": "string" }
                    }
                  },
                  "stay": {
                    "type": "object",
                    "properties": {
                      "country_code": { "type": "string" },
                      "country_name": { "type": "string" },
                      "nights": { "type": "integer" },
                      "rooms": { "type": "integer" },
                      "total_room_nights": { "type": "integer" }
                    }
                  },
                  "factor": {
                    "type": "object",
                    "properties": {
                      "value": { "type": "number" },
                      "unit": { "type": "string" },
                      "is_estimate": { "type": "boolean" },
                      "region": { "type": "string" }
                    }
                  },
                  "notices": {
                    "type": "array",
                    "items": { "$ref": "#/components/schemas/Notice" }
                  }
                }
              }
            }
          },
          "meta": { "$ref": "#/components/schemas/Meta" }
        }
      },
      "HotelFactorsResponse": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "country_code": { "type": "string" },
                "country_name": { "type": "string" },
                "factor": { "type": "number" },
                "unit": { "type": "string" },
                "region": { "type": "string" },
                "is_estimate": { "type": "boolean" }
              }
            }
          },
          "meta": {
            "type": "object",
            "properties": {
              "total_countries": { "type": "integer" },
              "source": { "type": "string" },
              "unit": { "type": "string" }
            }
          }
        }
      },
      "HotelCompareResponse": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "country_code": { "type": "string" },
                "country_name": { "type": "string" },
                "total_kg": { "type": "number" },
                "per_room_night_kg": { "type": "number" },
                "region": { "type": "string" },
                "is_estimate": { "type": "boolean" },
                "savings_vs_highest_kg": { "type": "number" },
                "savings_vs_highest_percent": { "type": "number" }
              }
            }
          },
          "meta": {
            "type": "object",
            "properties": {
              "nights": { "type": "integer" },
              "rooms": { "type": "integer" },
              "lowest_emissions": { "type": "string" },
              "highest_emissions": { "type": "string" },
              "total_room_nights": { "type": "integer" }
            }
          }
        }
      },
      "ElectricityEmissionResponse": {
        "type": "object",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "type": { "type": "string", "const": "electricity_emission" },
              "id": { "type": "string", "format": "uuid" },
              "attributes": {
                "type": "object",
                "properties": {
                  "emissions": {
                    "type": "object",
                    "properties": {
                      "co2e": { "type": "number" },
                      "co2e_unit": { "type": "string", "const": "kg" },
                      "co2e_calculation_method": { "type": "string" },
                      "co2e_grams": { "type": "integer" },
                      "ghg_protocol_scopes": {
                        "type": "object",
                        "properties": {
                          "scope_2": {
                            "type": "object",
                            "properties": {
                              "location_based": { "type": "number" },
                              "market_based": { "type": ["number", "null"] },
                              "method_note": { "type": "string" }
                            }
                          },
                          "scope_3_category_3": { "type": "number" }
                        }
                      },
                      "source_trail": {
                        "type": "array",
                        "items": { "$ref": "#/components/schemas/SourceTrailEntry" }
                      },
                      "equivalents": {
                        "description": "Real-world equivalents. Only populated when `equivalents=true`; otherwise `null` or omitted.",
                        "anyOf": [
                          { "$ref": "#/components/schemas/Equivalents" },
                          { "type": "null" }
                        ]
                      },
                      "lifecycle_breakdown": {
                        "type": "object",
                        "properties": {
                          "scope_2_location_based": { "type": "number" },
                          "scope_3_wtt": { "type": "number" },
                          "unit": { "type": "string" }
                        }
                      }
                    }
                  },
                  "consumption": {
                    "type": "object",
                    "properties": {
                      "kwh": { "type": "number" },
                      "effective_kwh": { "type": "number", "description": "kWh after T&D losses, if `include_td_losses=true`." },
                      "include_wtt": { "type": "boolean" },
                      "include_td_losses": { "type": "boolean" }
                    }
                  },
                  "grid": {
                    "type": "object",
                    "properties": {
                      "carbon_intensity": { "type": "number", "description": "gCO₂e/kWh" },
                      "unit": { "type": "string" },
                      "source": { "type": "string", "description": "How the intensity was resolved, e.g. `country`, `us_state`, `cloud_region`." },
                      "resolved_location": { "type": "string", "description": "e.g. `GB`, `US-CA`, `aws/eu-west-1`" },
                      "is_clean_grid": { "type": "boolean" },
                      "last_updated": { "type": "string", "format": "date" }
                    }
                  },
                  "notices": {
                    "type": "array",
                    "items": { "$ref": "#/components/schemas/Notice" }
                  }
                }
              }
            }
          },
          "meta": { "$ref": "#/components/schemas/Meta" }
        }
      },
      "GridIntensityResponse": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "country_code": { "type": "string" },
                "country_name": { "type": "string" },
                "carbon_intensity": { "type": "number", "description": "gCO₂e/kWh" },
                "unit": { "type": "string" },
                "region": { "type": "string" }
              }
            }
          },
          "meta": {
            "type": "object",
            "properties": {
              "total_countries": { "type": "integer" },
              "last_updated": { "type": "string", "format": "date" },
              "version": { "type": "string" }
            }
          }
        }
      },
      "FuelEmissionResponse": {
        "type": "object",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "type": { "type": "string", "const": "fuel_emission" },
              "id": { "type": "string", "format": "uuid" },
              "attributes": {
                "type": "object",
                "properties": {
                  "emissions": {
                    "type": "object",
                    "properties": {
                      "co2e": { "type": "number" },
                      "co2e_unit": { "type": "string", "const": "kg" },
                      "co2e_calculation_method": { "type": "string" },
                      "co2e_grams": { "type": "integer" },
                      "breakdown": {
                        "type": "object",
                        "properties": {
                          "direct_co2e": { "type": "number" },
                          "direct_co2": { "type": "number" },
                          "direct_ch4": { "type": "number" },
                          "direct_n2o": { "type": "number" },
                          "wtt_co2e": { "type": "number" },
                          "unit": { "type": "string" }
                        }
                      },
                      "ghg_protocol_scopes": {
                        "type": "object",
                        "properties": {
                          "scope_1": { "type": "number" },
                          "scope_3_category_3": { "type": "number" }
                        }
                      },
                      "equivalents": {
                        "description": "Real-world equivalents. Only populated when `equivalents=true`; otherwise `null` or omitted.",
                        "anyOf": [
                          { "$ref": "#/components/schemas/Equivalents" },
                          { "type": "null" }
                        ]
                      },
                      "source_trail": {
                        "type": "array",
                        "items": { "$ref": "#/components/schemas/SourceTrailEntry" }
                      }
                    }
                  },
                  "fuel": {
                    "type": "object",
                    "properties": {
                      "fuel_type": { "type": "string" },
                      "fuel_label": { "type": "string" },
                      "fuel_category": { "type": "string" },
                      "is_biofuel": { "type": "boolean" },
                      "amount": { "type": "number" },
                      "unit": { "type": "string" },
                      "emission_factor": { "type": "number" },
                      "emission_factor_unit": { "type": "string" },
                      "include_wtt": { "type": "boolean" }
                    }
                  },
                  "notices": {
                    "type": "array",
                    "items": { "$ref": "#/components/schemas/Notice" }
                  }
                }
              }
            }
          },
          "meta": { "$ref": "#/components/schemas/Meta" }
        }
      },
      "FuelTypesResponse": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "fuel_type": { "type": "string" },
                "label": { "type": "string" },
                "category": { "type": "string" },
                "is_biofuel": { "type": "boolean" },
                "available_units": {
                  "type": "array",
                  "items": { "type": "string" }
                },
                "default_unit": { "type": "string" }
              }
            }
          },
          "meta": {
            "type": "object",
            "properties": {
              "total_fuel_types": { "type": "integer" },
              "categories": {
                "type": "array",
                "items": { "type": "string" }
              },
              "source": { "type": "string" },
              "version": { "type": "string" }
            }
          }
        }
      },
      "LlmEmissionResponse": {
        "type": "object",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "type": { "type": "string", "const": "llm_emission" },
              "id": { "type": "string", "format": "uuid" },
              "attributes": {
                "type": "object",
                "properties": {
                  "emissions": {
                    "type": "object",
                    "properties": {
                      "co2e": { "type": "number", "description": "Total CO₂e in grams" },
                      "co2e_unit": { "type": "string", "const": "g", "description": "Note: this endpoint reports in grams, not kg" },
                      "co2e_calculation_method": { "type": "string" },
                      "breakdown": {
                        "type": "object",
                        "properties": {
                          "operational_co2e": { "type": "number" },
                          "embodied_co2e": { "type": "number" },
                          "unit": { "type": "string" }
                        }
                      },
                      "energy_usage": {
                        "type": "object",
                        "properties": {
                          "total_wh": { "type": "number" },
                          "total_kwh": { "type": "number" },
                          "per_request_wh": { "type": "number" },
                          "breakdown": {
                            "type": "object",
                            "properties": {
                              "base_energy_wh": { "type": "number" },
                              "input_tokens_wh": { "type": "number" },
                              "output_tokens_wh": { "type": "number" },
                              "reasoning_overhead_wh": { "type": "number" },
                              "pue_overhead_wh": { "type": "number" }
                            }
                          }
                        }
                      },
                      "ghg_protocol_scopes": {
                        "type": "object",
                        "properties": {
                          "scope_2": {
                            "type": "object",
                            "properties": {
                              "location_based": { "type": "number" },
                              "method_note": { "type": "string" }
                            }
                          },
                          "scope_3_category_1": { "type": "number" }
                        }
                      },
                      "source_trail": {
                        "type": "array",
                        "items": { "$ref": "#/components/schemas/SourceTrailEntry" }
                      }
                    }
                  },
                  "inference": {
                    "type": "object",
                    "properties": {
                      "provider": { "type": "string" },
                      "model": { "type": "string" },
                      "tier": { "type": "string", "enum": ["frontier", "large", "medium", "small"] },
                      "is_known_model": { "type": "boolean" },
                      "is_reasoning_model": { "type": "boolean" },
                      "thinking_ratio": { "type": "number" },
                      "tokens": {
                        "type": "object",
                        "properties": {
                          "input": { "type": "integer" },
                          "output": { "type": "integer" },
                          "cached": { "type": "integer" },
                          "reasoning_estimated": { "type": "integer" },
                          "effective_output": { "type": "integer" }
                        }
                      },
                      "requests": { "type": "integer" }
                    }
                  },
                  "grid": {
                    "type": "object",
                    "properties": {
                      "carbon_intensity": { "type": "number" },
                      "carbon_intensity_unit": { "type": "string" },
                      "region": { "type": "string" }
                    }
                  },
                  "notices": {
                    "type": "array",
                    "items": { "$ref": "#/components/schemas/Notice" }
                  }
                }
              }
            }
          },
          "meta": { "$ref": "#/components/schemas/Meta" }
        }
      },
      "GeocodedLocation": {
        "type": "object",
        "properties": {
          "input": { "type": "string" },
          "resolved": { "type": "string" },
          "country_code": { "type": "string" },
          "lat": { "type": "number" },
          "lon": { "type": "number" },
          "confidence_score": { "type": "number" }
        }
      },
      "Meta": {
        "type": "object",
        "properties": {
          "methodology": { "type": "string" },
          "emission_factors_year": { "type": "integer" },
          "standards_compliance": {
            "type": "object",
            "description": "Standards the calculation aligns with, keyed by standard (e.g. `GHG_Protocol`, `ISO_14083`, `ISO_14064`). Values are descriptive strings.",
            "additionalProperties": { "type": "string" }
          },
          "distance_method": { "type": "string" },
          "calculated_at": { "type": "string", "format": "date-time" },
          "version": { "type": "string" },
          "units": { "type": "string", "description": "Unit system used (e.g. `metric`). Returned by freight." }
        }
      }
    }
  }
}
