Making Requests

All emissions.dev API endpoints accept GET requests with query parameters.

Request Format

Base URL

https://api.emissions.dev/v1

Headers

Header Required Description
Authorization Yes Your API key: Bearer em_live_xxxx
Accept No Always returns application/json

Example Request

curl "https://api.emissions.dev/v1/freight/emissions?\
origin_country=GB&\
destination_country=DE&\
weight=5000" \
  -H "Authorization: Bearer em_live_xxxxxxxxxxxx"

Response Format

All responses follow JSON:API-style formatting:

{
  "data": {
    "type": "freight_emission",
    "id": "uuid-here",
    "attributes": {
      "emissions": { ... },
      "route": { ... },
      "cargo": { ... }
    }
  },
  "meta": {
    "methodology": "GLEC Framework v3.1",
    "calculated_at": "2026-02-07T12:00:00Z"
  }
}

Response Fields

Field Description
data.type Resource type (freight_emission, travel_emission, hotel_emission)
data.id Unique identifier for this calculation
data.attributes The calculated emissions and related data
meta Methodology, version, and timing information

Common Parameters

These parameters are available across multiple endpoints:

Location Parameters

Parameter Type Description
origin_country string ISO 3166-1 alpha-2 country code (e.g., GB)
destination_country string ISO 3166-1 alpha-2 country code
origin_location string City, address, or postcode
destination_location string City, address, or postcode

Output Options

Parameter Type Description
equivalents boolean Include real-world equivalents (trees, driving km)

Units

All emissions values are returned in kilograms of CO2 equivalent (kg CO2e).

For convenience, we also return:

  • co2e_grams - Total in grams
  • per_passenger_kg - Per-passenger values (Travel API)
  • per_room_night_kg - Per room-night values (Hotel API)

Best Practices

Cache responses

Emission calculations for the same route don't change frequently. Consider caching responses:

const cacheKey = `emissions:${origin}:${destination}:${weight}`;
const cached = await redis.get(cacheKey);

if (cached) {
  return JSON.parse(cached);
}

const result = await client.freight.calculate({ ... });
await redis.setex(cacheKey, 86400, JSON.stringify(result)); // 24h cache
return result;

Use specific locations

More specific locations = more accurate distances:

# Less accurate
origin_location=UK

# More accurate
origin_location=Sheffield&origin_country=GB