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-nodejs-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
});

Submit Emissions Data

// Submit electricity usage
const emission = await client.emissions.submit({
  scope: 1,
  source: 'electricity',
  value: 1500,
  unit: 'kWh',
  activity_date: '2026-01-07',
  location: 'Mumbai, India'
});

console.log(`Emission recorded: ${emission.value_tco2e} tCO2e`);

API Reference

Complete list of available methods

Emissions

client.emissions.submit(data)

Submit new emissions data

Parameters:

scope - Emission scope (1, 2, or 3)
source - Emission source (electricity, gas, etc.)
value - Activity value
unit - Unit of measurement
activity_date - Date of activity (YYYY-MM-DD)
location - Location (optional)

client.emissions.list(options)

Retrieve emissions data

Options:

start_date - Start date filter
end_date - End date filter
scope - Filter by scope

client.emissions.get(id)

Get a specific emission by ID

Analytics

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 Documentation Contact Support