@emissions-dev/sdk

Official JavaScript/TypeScript SDK for the emissions.dev carbon calculation API.

Installation

npm install @emissions-dev/sdk

Quick Start

import { EmissionsClient } from '@emissions-dev/sdk';

const client = new EmissionsClient({
  apiKey: process.env.EMISSIONS_API_KEY,
});

// Calculate freight emissions
const result = await client.freight.calculate({
  origin_country: 'GB',
  destination_country: 'DE',
  weight: 5000,
  transport_mode: 'road',
});

console.log(result.data.attributes.emissions.co2e); // 156.78 kg CO₂e

Configuration

const client = new EmissionsClient({
  apiKey: 'em_live_xxxx',       // Required
  baseUrl: 'https://api.emissions.dev/v1', // Default
  timeout: 30000,               // Request timeout in ms (default: 30s)
  retries: 2,                   // Retries on 5xx/network errors (default: 2)
});

APIs

Freight

const result = await client.freight.calculate({
  origin_country: 'GB',
  destination_country: 'DE',
  origin_location: 'London',
  destination_location: 'Berlin',
  weight: 5000,
  transport_mode: 'road',       // 'road' | 'rail' | 'sea' | 'air'
  fuel_source: 'diesel',        // 'diesel' | 'electric' | 'hvo' | ...
  equivalents: true,
});

Travel

const result = await client.travel.calculate({
  origin_country: 'GB',
  destination_country: 'FR',
  origin_location: 'London',
  destination_location: 'Paris',
  transport_mode: 'flight',     // 'flight' | 'rail' | 'car' | 'bus' | 'ferry' | 'taxi'
  cabin_class: 'business',      // 'economy' | 'premium_economy' | 'business' | 'first'
  passengers: 2,
  return_trip: true,
});

Hotel

// Calculate emissions
const result = await client.hotel.calculate({
  country: 'GB',
  nights: 3,
  rooms: 1,
});

// List all country factors
const factors = await client.hotel.factors();

// Compare countries
const comparison = await client.hotel.compare({
  countries: ['GB', 'FR', 'DE', 'ES'],
  nights: 5,
});

Electricity

// Calculate emissions
const result = await client.electricity.calculate({
  kwh: 5000,
  country: 'DE',
  state: 'CA',                  // US states (with country: 'US')
  cloud_provider: 'aws',        // 'aws' | 'gcp' | 'azure'
  cloud_region: 'eu-west-1',
  include_wtt: true,
  include_td_losses: false,
});

// List grid intensity data
const grid = await client.electricity.grid();

Fuel

// Calculate emissions
const result = await client.fuel.calculate({
  fuel_type: 'natural_gas',
  amount: 15000,
  unit: 'kwh',
  include_wtt: true,
});

// List all fuel types
const types = await client.fuel.types();

Error Handling

import {
  EmissionsClient,
  UnauthorizedError,
  ValidationError,
  RateLimitError,
  ServerError,
} from '@emissions-dev/sdk';

try {
  const result = await client.freight.calculate({ ... });
} catch (error) {
  if (error instanceof UnauthorizedError) {
    // 401 — Invalid API key
    console.error('Check your API key');
  } else if (error instanceof ValidationError) {
    // 422 — Bad parameters
    console.error(error.message, error.code, error.field);
  } else if (error instanceof RateLimitError) {
    // 429 — Rate limited
    console.error(`Retry after ${error.retryAfter} seconds`);
  } else if (error instanceof ServerError) {
    // 500 — Server error (already retried)
    console.error('Server error after retries');
  }
}

TypeScript

Full type definitions are included. Import specific types as needed:

import type {
  FreightCalculateParams,
  FreightResponse,
  TravelCalculateParams,
  ElectricityCalculateParams,
} from '@emissions-dev/sdk';

Requirements

• Node.js 18+ (uses native fetch)
• An API key from emissions.dev

License

MIT