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.
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.
npm install emissions-api-sdk
# or
yarn install emissions-api-sdkimport { 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"
}
});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 typeSupported endpoints: calculation, location, stationary, mobile, fugitive, factor, search, transportation-and-distribution, economic-activity, real-estate
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
}
});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"
}
});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);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 });The SDK supports three authentication methods:
await Client.getClient({
patToken: process.env.ENVIZI_PAT_TOKEN,
clientId: process.env.ENVIZI_CLIENT_ID
});Note: When using PAT token, do not provide orgId.
await Client.getClient({
apiKey: process.env.ENVIZI_API_KEY,
clientId: process.env.ENVIZI_CLIENT_ID,
orgId: process.env.ENVIZI_ORG_ID
});await Client.getClient({
token: process.env.JWT_TOKEN,
clientId: process.env.ENVIZI_CLIENT_ID
});For detailed documentation, see:
Other resources:
- APIHub - API documentation (OpenAPI)
- Tutorials & Sample Applications
- IBM Envizi for Excel - Emissions API Excel Add-in.
This project is licensed under the terms of the LICENSE file.