←Back to API DocsZeroCarbon Logo
Official SDK

Node.js SDK

Official Node.js SDK for ZeroCarbon API. Build powerful carbon tracking applications with TypeScript support.

npm install @zerocarbon/sdk
View on GitHub

Installation

Install via npm, yarn, or pnpm

npm

npm i zerocarbon-sdk

yarn

yarn add @zerocarbon/sdk

pnpm

pnpm add @zerocarbon/sdk

Quick Start

Initialize the SDK and start tracking emissions

Initialize the Client

import { ZeroCarbon } from '@zerocarbon/sdk';

// Initialize with your API key
const client = new ZeroCarbon({
  apiKey: process.env.ZEROCARBON_API_KEY
});

Record Emissions

// Record Scope 1 emissions (diesel generator)
const result = await client.emissions.create({
  scope: 1,
  source: 'diesel_generator',
  activity_value: 500,
  activity_unit: 'liters',
  period: 'January 2026',
  activity_date: '2026-01-15',
  data_quality: 'measured',
  notes: 'Backup generator usage'
});

console.log(`Recorded: ${result.emission.value_tco2e} tCO2e`);
console.log(`ID: ${result.emission.id}`);

API Reference

Complete list of available methods

Emissions

client.emissions.create(data)

Record new emissions data with detailed tracking

Parameters:

  • scope - Emission scope (1, 2, or 3)
  • source - Emission source (diesel_generator, electricity_grid, etc.)
  • activity_value - Activity quantity
  • activity_unit - Unit of measurement
  • activity_date - Date of activity (YYYY-MM-DD)
  • period - Reporting period
  • data_quality - measured, estimated, calculated (optional)
  • notes - Additional notes (optional)

client.emissions.list(options)

Retrieve emissions records with filters

Options:

  • scope - Filter by scope
  • from_date - Start date filter
  • to_date - End date filter
  • page - Page number
  • limit - Results per page

Calculate

client.calculate.electricity(options)

Calculate emissions from electricity consumption

Parameters:

  • amount_kwh - Electricity consumed in kWh
  • country - Country code (IN, US, UK, etc.)
  • state - State/region (optional)
  • renewable_percentage - Renewable energy % (optional)

client.calculate.flight(options)

Calculate flight emissions by route

Parameters:

  • origin - Origin airport code (IATA)
  • destination - Destination airport code
  • cabin_class - economy, business, first
  • passengers - Number of passengers (optional)

client.calculate.fuel(options)

Calculate emissions from fuel combustion

Parameters:

  • amount - Fuel quantity
  • fuel_type - diesel, petrol, natural_gas, etc.
  • unit - liters, gallons, cubic_meters

client.calculate.spend(options)

Calculate Scope 3 emissions using spend-based method

Parameters:

  • amount - Spend amount
  • currency - INR, USD, EUR, GBP
  • category - Spend category (transportation, materials, services)
  • description - Description for ML matching (optional)

client.analytics.get()

Get comprehensive emissions analytics

client.analytics.byScope()

Get emissions breakdown by scope

client.analytics.trend(period)

Get emissions trend over time

More Examples

Common use cases and patterns

Bulk Submit

const emissions = await Promise.all([
  client.emissions.submit({
    scope: 1,
    source: 'electricity',
    value: 1500,
    unit: 'kWh'
  }),
  client.emissions.submit({
    scope: 2,
    source: 'travel',
    value: 250,
    unit: 'km'
  })
]);

Error Handling

try {
  const emission = await client
    .emissions.submit(data);
  console.log('Success:', emission);
} catch (error) {
  if (error.code === 'RATE_LIMIT') {
    console.log('Rate limit exceeded');
  }
  console.error(error);
}

Get Analytics

const analytics = await client
  .analytics.get();

console.log(`Total: ${
  analytics.total_emissions
} tCO2e`);
console.log(`By Scope:`, 
  analytics.by_scope
);

Filter by Date Range

const emissions = await client
  .emissions.list({
    start_date: '2026-01-01',
    end_date: '2026-01-31',
    scope: 1
  });

console.log(`Found ${
  emissions.length
} emissions`);

TypeScript Support

Fully typed with IntelliSense support

import { 
  ZeroCarbon, 
  EmissionData, 
  EmissionResponse 
} from '@zerocarbon/sdk';

const client = new ZeroCarbon({
  apiKey: process.env.ZEROCARBON_API_KEY
});

const data: EmissionData = {
  scope: 1,
  source: 'electricity',
  value: 1500,
  unit: 'kWh',
  activity_date: '2026-01-07'
};

const response: EmissionResponse = 
  await client.emissions.submit(data);

Need Help?

Check out our full API documentation or reach out to our support team

API DocumentationContact Support