IBM Envizi - Emissions API Node.js SDK

IBM Envizi - Emissions API (Emissions API) is a managed factor database and calculation engine for embedding greenhouse gas (GHG) emissions calculations into operational decision making.

The emissions-api-sdk is a Node.js SDK for using Emissions API in your projects.

Sign up

To get started with the Emissions API follow these steps:

• Sign up at the IBMid sign up page.
• You will be sent an invite email to join to create an account.
• Read the Introduction page to get an overview of the Emissions API.

Installation

npm install emissions-api-sdk
# or
yarn install emissions-api-sdk

Quick Start

import { Client, LocationEmission } from 'emissions-api-sdk';

// Initialize client
await Client.getClient({
  patToken: process.env.ENVIZI_PAT_TOKEN,
  clientId: process.env.ENVIZI_CLIENT_ID
});

// Calculate emissions
const result = await LocationEmission.calculate({
  "location": {
    "country": "USA",
    "stateProvince": "california"
  },
  "activity": {
    "type": "electricity",
    "value": 1,
    "unit": "kWh"
  }
});

Metadata APIs

The Metadata API provides a unified way to query metadata for any endpoint:

import { Metadata } from 'emissions-api-sdk';

// Get types for any endpoint (defaults to 'calculation')
const allTypes = await Metadata.getTypes();
const locationTypes = await Metadata.getTypes('location');
const stationaryTypes = await Metadata.postTypes('stationary');

// Get areas for any endpoint
const allAreas = await Metadata.getArea();
const mobileAreas = await Metadata.getArea('mobile');
const fugitiveAreas = await Metadata.postArea('fugitive');

// Get units for any type
const allUnits = await Metadata.getUnits(); // All units
const typeUnits = await Metadata.getUnits('Natural Gas'); // Units for specific type

Supported endpoints: calculation, location, stationary, mobile, fugitive, factor, search, transportation-and-distribution, economic-activity, real-estate

Type Recommender API

Search for activity types using semantic search with optional unit and scope filtering. Reranking is enabled by default; set enableReranker to false to use semantic similarity ordering without cross-encoder reranking. Type results can include scope, the distinct GHG Protocol scopes associated with each activity type.

import { TypeRecommender } from 'emissions-api-sdk';

// Basic search with natural language
const types = await TypeRecommender.search({
  "location": {
    "country": "usa"
  },
  "activity": {
    "search": "employee travelled by electric vehicle"
  }
});

// Search with unit filter
const typesWithUnit = await TypeRecommender.search({
  "location": {
    "country": "usa"
  },
  "activity": {
    "search": "office consumed electricity",
    "unit": "kWh"
  }
});

// Search without cross-encoder reranking
const typesWithoutReranker = await TypeRecommender.search({
  "location": {
    "country": "usa"
  },
  "activity": {
    "search": "office consumed electricity"
  },
  "enableReranker": false
});

// Search with scope filter
const typesWithScope = await TypeRecommender.search({
  "location": {
    "country": "usa"
  },
  "activity": {
    "search": "heating with natural gas",
    "scope": "1"
  }
});

// Search with pagination and filters
const typesWithAll = await TypeRecommender.search({
  "location": {
    "country": "usa",
    "stateProvince": "california"
  },
  "time": {
    "date": "2025-06-10"
  },
  "activity": {
    "search": "purchased electricity for data center",
    "unit": "MWh",
    "scope": "2"
  },
  "pagination": {
    "page": 1,
    "size": 10
  }
});

Factor Search API

Search for emission factors with optional unit and scope filtering. Reranking is enabled by default; set enableReranker to false to use semantic similarity ordering without cross-encoder reranking.

import { Factor } from 'emissions-api-sdk';

// Basic search with natural language
const results = await Factor.search({
  "time": {
    "date": "2020-06-10"
  },
  "activity": {
    "search": "employee business travel by air"
  },
  "location": {
    "country": "USA"
  }
});

// Search with unit filter
const resultsWithUnit = await Factor.search({
  "activity": {
    "search": "office electricity consumption",
    "unit": "kWh"
  },
  "location": {
    "country": "USA"
  }
});

// Search without cross-encoder reranking
const resultsWithoutReranker = await Factor.search({
  "activity": {
    "search": "employee business travel by air"
  },
  "location": {
    "country": "USA"
  },
  "enableReranker": false
});

// Search with scope filter
const resultsWithScope = await Factor.search({
  "activity": {
    "search": "facility heating with natural gas",
    "scope": "1"
  },
  "location": {
    "country": "USA"
  }
});

// Search with both unit and scope
const resultsWithBoth = await Factor.search({
  "activity": {
    "search": "purchased electricity for manufacturing",
    "unit": "MWh",
    "scope": "2"
  },
  "location": {
    "country": "USA",
    "stateProvince": "california"
  }
});

Get Organization Usage

import { Usage } from 'emissions-api-sdk';

// Retrieves current billing period or historical usage data for the Organization
// History Flag to retrieve current billing or historical usage data.
const usage = await Usage.getUsage(true);

Audit Log API

Controls whether the organization's API requests and responses are stored for auditing. Organizations can disable storage if they don't need their API calls to be audited.

import { AuditLog } from 'emissions-api-sdk';

// Get current configuration
const config = await AuditLog.getConfig();
console.log(config); // { logRequest: true, logResponse: true }

// Disable storage
await AuditLog.update({ logRequest: false, logResponse: false });

// Enable only request storage
await AuditLog.update({ logRequest: true, logResponse: false });

Audit Export API

Admin users can export audit data for a date range. The export is asynchronous: submit the request, poll until it is complete, then download the ZIP archive. All three endpoints require an admin JWT token.

import { AuditExport } from 'emissions-api-sdk';

const auditExport = await AuditExport.trigger({
  fromDate: '2025-01-01',
  toDate: '2025-03-31',
  apiName: 'location'
});

// Repeat this request until status is COMPLETED.
const status = await AuditExport.getStatus(auditExport.requestId);

if (status.status === 'COMPLETED') {
  const auditExportZip = await AuditExport.download(auditExport.requestId);
}

The request dates use yyyy-MM-dd. fromDate must be on or after 2025-01-01, toDate must be no later than the previous calendar day, and apiName is an optional case-insensitive endpoint filter. A completed export is available for seven days. See the Audit Export API reference for the request and response details.

Authentication

The SDK supports three authentication methods:

Personal Access Token (PAT) (Recommended)

await Client.getClient({
  patToken: process.env.ENVIZI_PAT_TOKEN,
  clientId: process.env.ENVIZI_CLIENT_ID
});

Note: When using PAT token, do not provide orgId.

API Key

await Client.getClient({
  apiKey: process.env.ENVIZI_API_KEY,
  clientId: process.env.ENVIZI_CLIENT_ID,
  orgId: process.env.ENVIZI_ORG_ID
});

Pre-generated JWT Token

await Client.getClient({
  token: process.env.JWT_TOKEN,
  clientId: process.env.ENVIZI_CLIENT_ID
});

Documentation

For detailed documentation, see:

• Getting Started
• Authentication
• Client Configuration
• API Reference

Other resources:

• APIHub - API documentation (OpenAPI)
• Tutorials & Sample Applications
• IBM Envizi for Excel - Emissions API Excel Add-in.

License

This project is licensed under the terms of the LICENSE file.