Getting Started

Prerequisites

Before using the SDK, ensure you have:

  • Node.js installed

  • Active internet connection

  • An IBMid account. Sign up at the IBMid sign up page.

  • Access to the Emissions API service and the required credentials

  • Read the Introduction page for an overview of the Emissions API

Installation

You can install the SDK using npm or yarn:

Using npm:

npm install emissions-api-sdk

Using yarn:

yarn install emissions-api-sdk

Basic Import

After installation, you can import the SDK in your project:

// Import the entire SDK
const enviziSDK = require('emissions-api-sdk');

// Or using ES modules
import { Client, LocationEmission } from 'emissions-api-sdk';

Authentication

The SDK supports three authentication methods:

  • Personal Access Token (PAT), recommended for most users

  • API key, where the SDK retrieves and refreshes a bearer token

  • Pre-generated JWT token, managed outside the SDK

Using Personal Access Token (PAT)

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

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

Note

When using a PAT token, do not provide orgId.

Using API Key

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

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

Using Pre-generated JWT Token

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

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

First API Call

After initializing the client, you can make your first API call. Here’s a quick start example of calculating location-based emissions:

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

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

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

Example Response

The API returns emission calculation results in JSON format. Here’s an example response:

{
  "transactionId": "95a7efe7-02ae-47a3-a7fd-831bfca7cecd",
  "totalCO2e": 0.20750174,
  "CO2": 0.20681091,
  "CH4": 0.00033022,
  "N2O": 0.00036061,
  "indirectCO2e": 0.01115131,
  "unit": "kgCO2e",
  "description": "The electricity emissions factor used to calculate this result was obtained from the  year 2022 Managed - eGRID & US Climate Leaders factor set for the area United States and the region California."
}

Example Response with Details

When you need more detailed information about the emission factors used in calculations, you can request the response to include the details object. This provides comprehensive information about the factor set and specific factor used:

{
  "transactionId": "29df5ecd-fc3b-4797-b6fd-da03bc007f30",
  "totalCO2e": 5912000,
  "CO2": 5840000,
  "CH4": 2000.0000000000002,
  "N2O": 70000,
  "indirectCO2e": 1340000,
  "unit": "kgCO2e",
  "description": "The Freight - Cargo Ship - Bulk Carrier - 0-9999 dwt emissions factor used to calculate this result was obtained from the DEFRA factor set for the Global region year 2025.",
  "details": {
    "factorSet": {
      "name": "DEFRA",
      "description": "The UK Government and DEFRA publish GHG emission factors covering Scope 1, Scope 2, and selected Scope 3 sources. While primarily intended for UK-based reporting, many organizations apply these factors across European sites—especially for air travel-related emissions.",
      "provider": "His Majesty's Government (United Kingdom of Great Britain and Northern Ireland): Department for Energy Security and Net Zero",
      "sourceUrl": "https://www.gov.uk/government/publications/greenhouse-gas-reporting-conversion-factors-2024"
    },
    "factor": {
      "name": "Bulk carrier - 0–9999 dwt - 2025",
      "description": "Cargo ship - tonne.km",
      "totalCO2e": 0.02956,
      "CO2": 0.0292,
      "CH4": 0.00001,
      "N2O": 0.00035,
      "indirectCO2e": 0.0067,
      "inputUnit": "t-km",
      "unit": "tonne.km",
      "conversionRatio": "1:1",
      "activityType": "Freight - Cargo Ship - Bulk Carrier - 0-9999 dwt",
      "activitySubtype": "Default Factor",
      "factorId": 190405,
      "methodology": "activity-based",
      "scopes": [
        "3.4",
        "3.9"
      ],
      "areaName": "Earth",
      "areaType": "Planet",
      "publishedFrom": "2025-01-01",
      "source": "2025 Greenhouse Gas Reporting: Conversion Factors 2025 (DEFRA) provided by gov.uk, license - https://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/"
    }
  }
}

Response Structure Details

The response includes the following key components:

Top-level Fields:

  • transactionId: Unique identifier for the calculation

  • totalCO2e: Total CO2 equivalent emissions

  • CO2: Carbon dioxide emissions

  • CH4: Methane emissions

  • N2O: Nitrous oxide emissions

  • indirectCO2e: Indirect CO2 equivalent emissions

  • unit: Unit of measurement (typically kgCO2e)

  • description: Human-readable description of the calculation

Details Object (when requested):

The details object provides comprehensive information about the emission factors:

Factor Set Information:

  • name: Name of the factor set (e.g., DEFRA, EPA)

  • description: Detailed description of the factor set

  • provider: Organization that provides the factor set

  • sourceUrl: URL to the source documentation

Factor Information:

  • name: Specific name of the emission factor

  • description: Description of the factor

  • totalCO2e, CO2, CH4, N2O, indirectCO2e: Emission values per unit

  • inputUnit: Unit for input values

  • unit: Unit of the factor

  • conversionRatio: Conversion ratio applied

  • activityType: Type of activity (e.g., transportation, energy)

  • activitySubtype: Subtype classification

  • factorId: Unique identifier for the factor

  • methodology: Calculation methodology used

  • scopes: Applicable GHG Protocol scopes

  • areaName: Geographic area name

  • areaType: Type of geographic area

  • publishedFrom: Date from which the factor is valid

Currency Conversion Support

Overview

The SDK supports automatic currency conversion for API methods that accept monetary values. This feature allows you to input values in your preferred currency, and the system will automatically convert them to the appropriate base currency for emissions calculations.

Supported Methods

Currency conversion is available for the following calculation methods:

  • EconomicActivity.calculate()

  • RealEstate.calculate()

  • PhysicalActivity.calculate()

Supported Currencies

The SDK supports conversion for 170 currencies:

Currency Name

Symbol

ADB Unit of Account

XUA

Afghani

AFN

Algerian Dinar

DZD

Arab Accounting Dinar

XAD

Argentine Peso

ARS

Armenian Dram

AMD

Aruban Florin

AWG

Australian Dollar

AUD

Azerbaijan Manat

AZN

Bahamian Dollar

BSD

Bahraini Dinar

BHD

Baht

THB

Balboa

PAB

Barbados Dollar

BBD

Belarusian Ruble

BYN

Belize Dollar

BZD

Bermudian Dollar

BMD

Boliviano

BOB

Bolívar Soberano

VED

Bolívar Soberano

VES

Brazilian Real

BRL

Brunei Dollar

BND

Bulgarian Lev

BGN

Burundi Franc

BIF

Cabo Verde Escudo

CVE

Canadian Dollar

CAD

Caribbean Guilder

XCG

Cayman Islands Dollar

KYD

CFA Franc BCEAO

XOF

CFA Franc BEAC

XAF

CFP Franc

XPF

Chilean Peso

CLP

Colombian Peso

COP

Comorian Franc

KMF

Congolese Franc

CDF

Convertible Mark

BAM

Cordoba Oro

NIO

Costa Rican Colon

CRC

Cuban Peso

CUP

Czech Koruna

CZK

Dalasi

GMD

Danish Krone

DKK

Denar

MKD

Djibouti Franc

DJF

Dobra

STN

Dominican Peso

DOP

Dong

VND

East Caribbean Dollar

XCD

Egyptian Pound

EGP

El Salvador Colon

SVC

Ethiopian Birr

ETB

Euro

EUR

Falkland Islands Pound

FKP

Fiji Dollar

FJD

Forint

HUF

Ghana Cedi

GHS

Gibraltar Pound

GIP

Gourde

HTG

Guarani

PYG

Guinean Franc

GNF

Guyana Dollar

GYD

Hong Kong Dollar

HKD

Hryvnia

UAH

Iceland Krona

ISK

Indian Rupee

INR

Iranian Rial

IRR

Iraqi Dinar

IQD

Jamaican Dollar

JMD

Jordanian Dinar

JOD

Kenyan Shilling

KES

Kina

PGK

Kuwaiti Dinar

KWD

Kwanza

AOA

Kyat

MMK

Lao Kip

LAK

Lari

GEL

Lebanese Pound

LBP

Lek

ALL

Lempira

HNL

Leone

SLE

Liberian Dollar

LRD

Libyan Dinar

LYD

Lilangeni

SZL

Loti

LSL

Malagasy Ariary

MGA

Malawi Kwacha

MWK

Malaysian Ringgit

MYR

Mauritius Rupee

MUR

Mexican Peso

MXN

Mexican Unidad de Inversion (UDI)

MXV

Moldovan Leu

MDL

Moroccan Dirham

MAD

Mozambique Metical

MZN

Mvdol

BOV

Naira

NGN

Nakfa

ERN

Namibia Dollar

NAD

Nepalese Rupee

NPR

Netherlands Antillean Guilder

ANG

New Israeli Sheqel

ILS

New Taiwan Dollar

TWD

New Zealand Dollar

NZD

Ngultrum

BTN

North Korean Won

KPW

Norwegian Krone

NOK

Ouguiya

MRU

Pa’anga

TOP

Pakistan Rupee

PKR

Pataca

MOP

Peso Uruguayo

UYU

Philippine Peso

PHP

Pound Sterling

GBP

Pula

BWP

Qatari Rial

QAR

Quetzal

GTQ

Rand

ZAR

Rial Omani

OMR

Riel

KHR

Romanian Leu

RON

Rufiyaa

MVR

Rupiah

IDR

Russian Ruble

RUB

Rwanda Franc

RWF

Saint Helena Pound

SHP

Saudi Riyal

SAR

SDR (Special Drawing Right)

XDR

Serbian Dinar

RSD

Seychelles Rupee

SCR

Singapore Dollar

SGD

Sol

PEN

Solomon Islands Dollar

SBD

Som

KGS

Somali Shilling

SOS

Somoni

TJS

South Sudanese Pound

SSP

Sri Lanka Rupee

LKR

Sucre

XSU

Sudanese Pound

SDG

Surinam Dollar

SRD

Swedish Krona

SEK

Swiss Franc

CHF

Syrian Pound

SYP

Taka

BDT

Tala

WST

Tanzanian Shilling

TZS

Tenge

KZT

Trinidad and Tobago Dollar

TTD

Tugrik

MNT

Tunisian Dinar

TND

Turkish Lira

TRY

Turkmenistan New Manat

TMT

UAE Dirham

AED

Uganda Shilling

UGX

Unidad de Fomento

CLF

Unidad de Valor Real

COU

Unidad Previsional

UYW

United States dollar

USD

Uruguay Peso en Unidades Indexadas (UI)

UYI

US Dollar (Next day)

USN

Uzbekistan Sum

UZS

Vatu

VUV

WIR Euro

CHE

WIR Franc

CHW

Won

KRW

Yemeni Rial

YER

Yen

JPY

Yuan Renminbi

CNY

Zambian Kwacha

ZMW

Zimbabwe Gold

ZWG

Zloty

PLN

Exchange Rate Data

Data Source

Exchange rates are sourced from the U.S. Department of the Treasury’s Fiscal Data API, which provides official exchange rates used by the U.S. government for accounting and reporting purposes.

Historical Coverage

Exchange rate data is available from March 31, 2001 onwards. If you specify a date earlier than this, the system will use the earliest available rate.

Data Updates

The exchange rate database is automatically synchronized with the Treasury API to ensure you always have access to the most current rates. Updates are captured as soon as they become available from the Treasury.

  • Update Frequency: The U.S. Treasury typically publishes exchange rates on a quarterly basis

  • Amendment Policy: If current rates deviate from the published rates by 10% or more, Treasury will issue amendments to the quarterly report

  • source: Source citation and license information