Getting Started

Welcome! The emissions.dev API gives you precise, auditable CO₂e calculations for freight, travel, electricity, fuel, and accommodation — all from a single REST endpoint. Every response includes a full source trail so your numbers stand up to scrutiny.

Base URL

All API requests are made to:

https://api.emissions.dev/v1

Authentication

Every operation on our REST API requires authentication using an API key. Get your API key from the Dashboard (it's free to join if you haven't already).

curl https://api.emissions.dev/v1/freight/emissions \
  -H "Authorization: Bearer em_live_xxxx"

Alternative: Query String (for testing only)

curl "https://api.emissions.dev/v1/freight/emissions?api_key=em_live_xxxx&..."
<div class="admonition admonition-warning"><span class="admonition-icon">⚠️</span><div class="admonition-content"><p>Query string authentication exposes your API key in URLs and logs. Use header authentication in production.</p> </div></div> <div class="admonition admonition-tip"><span class="admonition-icon">💡</span><div class="admonition-content"><p>Never expose your API key in client-side code. Always make API calls from your backend server.</p> </div></div> ## Quick Start

Calculate freight emissions with a single request:

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

Response:

{
  "data": {
    "type": "freight_emission",
    "id": "f33ee387-c1b3-4941-b5f1-9a61f144e1f2",
    "attributes": {
      "emissions": {
        "co2e": 45.23,
        "co2e_unit": "kg",
        "co2e_calculation_method": "ipcc_ar6_gwp100"
      },
      "route": {
        "total_distance_km": 456,
        "transport_mode": "road"
      }
    }
  }
}

Available APIs

API Description Use Case
Fuel API Calculate emissions from fuel combustion Heating, generators, fleet fuel, Scope 1
Electricity API Calculate emissions from electricity consumption Office reporting, data centers, Scope 2
Travel API Calculate emissions for passenger travel Business travel, booking platforms
Hotel API Calculate emissions for accommodation Travel planning, corporate travel
Freight API Calculate emissions for cargo transport Logistics, supply chain, e-commerce

Key Features

  • Location-Aware Calculations - For electric vehicles, we use local grid carbon intensity data for 110+ countries.
  • Real Road Routing - Unlike simple straight-line calculations, we use actual road routing data to calculate accurate driving distances.
  • Full Audit Trail - Every response includes a source_trail with the exact emission factors used, their source, dataset, year, and region.
  • GHG Protocol Compliant - All calculations follow the Greenhouse Gas Protocol methodology, with proper scope categorization.

Rate Limits

Plan Requests/month Rate
Free 500 2/min
Starter 10,000 10/min
Growth 50,000 15/min
Scale 200,000 25/min
Enterprise Custom Custom

Enterprise plans include dedicated rate limits, SLAs, and priority support. Contact us for details.

Versioning

The API version is returned in every response under meta.version. All endpoints currently use the v1 prefix. See the Changelog for release history.

Need Help?