Reference¶

class Client(token, config, isUserProvidedToken=false)¶

exported from Client

Arguments:

token (string)
config (ClientConfig)
isUserProvidedToken (boolean)

Client.getAuthHeader()¶

Returns the authorization header object with the Bearer token.

Returns:: Record<string, string> – An object containing the Authorization header with the Bearer token

Example

const client = Client.getInstance();
const headers = {
  'Content-Type': 'application/json',
  ...client.getAuthHeader()
};
// headers = { 'Content-Type': 'application/json', 'Authorization': 'Bearer token...' }

Client.getClientId()¶

Returns the client ID configured for this client instance.

Returns:: string – The client ID string

Example

const client = Client.getInstance();
const clientId = client.getClientId();
console.log(clientId); // e.g., 'client123'

Client.getClientSource()¶

Returns the client source identifier for this client instance.

Returns:: string – The client source string

Example

const client = Client.getInstance();
const source = client.getClientSource();
console.log(source); // e.g., 'web', 'mobile', 'sdk'

Client.getDomain()¶

Returns the domain URL configured for the client.

Returns:: string – The domain URL string

Example

const client = Client.getInstance();
const apiDomain = client.getDomain();
console.log(apiDomain); // e.g., 'https://api.example.com'

async Client.refreshToken()¶

Refreshes the authentication token if it’s about to expire. Only refreshes if the token was not provided by the user and is expiring within 60 seconds.

Returns:: Promise<void> – A promise that resolves when the token refresh is complete

Example

const client = Client.getInstance();
// Ensure token is fresh before making API requests
await client.refreshToken();
// Proceed with API requests...

static async Client.getClient(config)¶

Initializes and returns a Client instance with the provided configuration.

Arguments:

config (ClientConfig) – The client configuration object

Returns:

Promise<void> – A promise that resolves when the client is initialized

Example

// Initialize with authentication URL
await Client.getClient({
  host: 'https://api.example.com',
  authUrl: 'https://auth.example.com',
  clientId: 'client123',
  orgId: 'org456'
});

// Initialize with existing token
await Client.getClient({
  token: 'existing-jwt-token',
  clientId: 'client123'
});

// Initialize with API key
await Client.getClient({
  apiKey: 'your-api-key',
  clientId: 'client123',
  orgId: 'org456'
});

// Initialize with PAT token
await Client.getClient({
  patToken: 'your-personal-access-token',
  clientId: 'client123'
});

static Client.getInstance()¶

Returns the singleton instance of the Client.

Returns:: Client – The singleton Client instance

Example

// First initialize the client
await Client.getClient({
  clientId: 'client123',
  orgId: 'org456'
});

// Then get the instance
const client = Client.getInstance();
// Use the client...

async request.makeApiRequest<T>(config)¶

Makes an API request with standardized headers and token refresh.

Type parameters:

T – The expected response data type

Arguments:

config (RequestConfig) – The request configuration including method, URL, data, params, and optional headers

Returns:

Promise<T> – A promise that resolves to the response data of type T

Example

interface UserData {
  id: string;
  name: string;
  email: string;
}

const userData = await makeApiRequest<UserData>({
  method: 'GET',
  url: 'https://api.example.com/users/123',
  headers: { 'X-Custom-Header': 'value' }
});
console.log(userData.name); // Typed access to the response data

utils.findExpiryTime(token)¶

Extracts the expiration time from a JWT token and give the token expiry time.

Arguments:

token (string) – The JWT token to extract the expiration time from

Returns:

any – The expiration time value from the token’s payload

Example

const jwtToken = 'your-token';
const expiryTime = findExpiryTime(jwtToken);
console.log(new Date(expiryTime * 1000).toISOString()); // Convert to date if it's a Unix timestamp

API¶

async Factor.retrieveFactor(payload)¶

Retrieves a factor details by making a POST request to the factor API endpoint.

Arguments:

payload (FactorRequest) – The factor request data to be sent to the API

Returns:

Promise<FactorResponse> – A promise that resolves to the FactorResponse returned by the API

Example

const factorRequest = {
   "activity": {
     "factorId": 12345
   }
 };

 OR

 const factorRequest = {
   "time" : {
     "date": "2025-01-04"
   },
   "location": {
     "country": "usa",
     "stateProvince": "new york"
   },
   "activity": {
     "type":"natural gas"
   },
   "includeDetails": true
 };
const factor = await retrieveFactor(factorRequest);

async Factor.search(payload)¶

Performs a search operation by making a POST request to the search API endpoint.

Arguments:

payload (SearchRequest) – The search request data to be sent to the API

Returns:

Promise<SearchResponse> – A promise that resolves to the search results returned by the API

Example

// Basic search
const searchRequest = {
   "time":{
     "date": "2020-06-10"
   },
   "activity": {
     "search" : "travel"
   },
   "location": {
     "country": "USA"
   }
 };
const results = await search(searchRequest);

Example

// Search without cross-encoder reranking
const searchWithoutReranker = {
   "time":{
     "date": "2020-06-10"
   },
   "activity": {
     "search" : "travel"
   },
   "location": {
     "country": "USA"
   },
   "enableReranker": false
 };
const results = await search(searchWithoutReranker);

Example

// Search with optional unit parameter
const searchWithUnit = {
   "time":{
     "date": "2020-06-10"
   },
   "activity": {
     "search": "electricity",
     "unit": "kWh"
   },
   "location": {
     "country": "USA"
   }
 };
const results = await search(searchWithUnit);

Example

// Search with optional scope parameter
const searchWithScope = {
   "time":{
     "date": "2020-06-10"
   },
   "activity": {
     "search": "natural gas",
     "scope": "1"
   },
   "location": {
     "country": "USA"
   }
 };
const results = await search(searchWithScope);

Example

// Search with both unit and scope parameters
const searchWithBoth = {
   "time":{
     "date": "2020-06-10"
   },
   "activity": {
     "search": "electricity",
     "unit": "MWh",
     "scope": "2"
   },
   "location": {
     "country": "USA",
     "stateProvince": "california"
   }
 };
const results = await search(searchWithBoth);

async Fugitive.calculate(payload)¶

Performs scope 1 fugitve emission calculations by making a POST request to the fugitive API endpoint.

Arguments:

payload (CommonRequest) – The request data to be sent to the API

Returns:

Promise<EmissionResponse | EmissionResponseWithDetails> – A promise that resolves to the emission calculation result. Returns EmissionResponseWithDetails if includeDetails is true, otherwise EmissionResponse

Example

const request = {
   "time": {
     "date": "2025-01-04"
   },
   "location": {
     "country": "usa"
   },
   "activity": {
     "type": "R134A",
     "value": 150,
     "unit": "kg"
   },
   "includeDetails": false
 };
const result = await calculate(request);

async Calculation.calculate(payload)¶

Performs emission calculations by making a POST request to the generic calculation API endpoint.

Arguments:

payload (CalculationRequest) – The calculation request data to be sent to the API

Returns:

Example

const calculationRequest = {
   "time" : {
     "date": "2025-01-04"
   },
   "location": {
     "country": "usa",
     "stateProvince": "new york"
   },
   "activity": {
     "type":"Waste Combusted - Steel Cans:Default factor",
     "unit": "kg",
     "value": 1223123.121
   },
   "includeDetails": true
 };
const result = await calculate(calculationRequest);

async Location.calculate(payload)¶

Performs scope 2 purchased energy Emission calculations by making a POST request to the location API endpoint.

Arguments:

payload (LocationRequest) – The location request data to be sent to the API

Returns:

Example

const calculationRequest = {
   "time" : {
     "date": "2025-01-04"
   },
   "location": {
     "country": "usa",
     "stateProvince": "new york"
   },
   "activity": {
     "type":"electricity",
     "unit": "kwh",
     "value": 14123143
   },
   "includeDetails": true
 };
const result = await calculate(calculationRequest);

async Mobile.calculate(payload)¶

Performs Scope 1 mobile emissions related calculations by making a POST request to the mobile API endpoint.

Arguments:

payload (CommonRequest) – The request data to be sent to the mobile API

Returns:

Example

const request = {
   "time": {
     "date": "2022-01-01"
   },
   "location": {
     "country": "USA",
     "stateProvince": "new york"
   },
   "activity": {
     "type": "Diesel Fuel",
     "value": 1500000,
     "unit": "l"
   },
   "includeDetails": false
 };
const result = await calculate(request);

async Stationary.calculate(payload)¶

Performs Scope 1 stationary calculations by making a POST request to the stationary API endpoint.

Arguments:

payload (CommonRequest) – The request data to be sent to the stationary API

Returns:

Example

const request = {
   "time" : {
     "date": "2025-01-04"
   },
   "location": {
     "country": "usa",
     "stateProvince": "new york"
   },
   "activity": {
     "type":"Coal - Lignite",
     "unit": "KJ",
     "value": 3
   },
   "includeDetails": true
 };
const result = await calculate(request);

async TransportationAndDistribution.calculate(payload)¶

Performs Scope 3 transportation and distribution emission calculations by making a POST request to the transportation and distribution API endpoint.

Arguments:

payload (CalculationRequest) – The calculation request data for transportation and distribution operations

Returns:

Example

const request = {
   "time" : {
     "date": "2025-01-04"
   },
   "location": {
     "country": "usa"
   },
   "activity": {
     "type": "Freight - Cargo Ship - Bulk Carrier - 0-9999 dwt",
     "unit": ["t","km"],
     "value": [1.0,1.0]
   },
   "includeDetails": true
 };
const result = await calculate(request);

async RealEstate.calculate(payload)¶

Performs scope 3 Real estate emission calculations by making a POST request to the real estate API endpoint.

Arguments:

payload (CommonRequest) – The request data to be sent to the API

Returns:

Example

// Basic request without attribution
const request = {
   "time": {
     "date": "2025-01-04"
   },
   "location": {
     "country": "usa"
   },
   "activity": {
     "type": "Commercial Real Estate:Industrial distribution warehouse",
     "value": 17000.123,
     "unit": "m2"
   },
   "includeDetails": false
 };
const result = await calculate(request);

Example

// Request with attribution (property value based)
const requestWithAttribution = {
   "time": {
     "date": "2022-01-01"
   },
   "location": {
     "country": "usa",
     "stateProvince": "new york"
   },
   "activity": {
     "type": "Commercial Real Estate:Office",
     "value": 123456.0,
     "unit": "m2"
   },
   "attribution": {
     "outstandingAmount": 1000000.0,
     "propertyValue": 5000000.0
   },
   "includeDetails": true
 };

async EconomicActivity.calculate(payload)¶

Performs scope 3 Spend based emission calculations by making a POST request to the economic activity API endpoint. Supports optional attribution with revenue for proportional allocation.

Arguments:

payload (CommonRequest) – The request data to be sent to the API

Returns:

Example

// Basic economic activity request
const request = {
   "time": {
     "date": "2025-01-04"
   },
   "location": {
     "country": "usa"
   },
   "activity": {
     "type": "accomodation",
     "value": 1500.12,
     "unit": "usd"
   },
   "includeDetails": false
 };
const result = await calculate(request);

Example

// Economic activity request with revenue attribution
const requestWithAttribution = {
   "time": {
     "date": "2025-01-04"
   },
   "location": {
     "country": "usa"
   },
   "activity": {
     "type": "accomodation",
     "value": 1500.12,
     "unit": "usd"
   },
   "attribution": {
     "outstandingAmount": 500000.0,
     "revenue": 2000000.0
   },
   "includeDetails": true
 };
const resultWithAttribution = await calculate(requestWithAttribution);

Type Recommender API¶

async TypeRecommender.search(payload)¶

Search for activity types using semantic search with location, time, and license context. Supports pagination and optional reranker control.

Arguments:

payload (SearchRequest) – The search request data to be sent to the API

Returns:

Promise<TypeRecommenderResponse> – A promise that resolves to the activity types returned by the API

Example

// Basic search
const result = await search({
   "location": {
     "country": "usa"
   },
   "activity": {
     "search": "electricity"
   }
 });

Example

// Search with time and pagination
const result = await search({
   "location": {
     "country": "usa",
     "stateProvince": "california"
   },
   "time": {
     "date": "2025-06-10"
   },
   "activity": {
     "search": "electricity"
   },
   "pagination": {
     "page": 1,
     "size": 10
   }
 });

Example

// Search with power grid
const result = await search({
   "location": {
     "country": "usa",
     "powerGrid": "WECC"
   },
   "activity": {
     "search": "renewable energy"
   }
 });

Example

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

Example

// Search with optional unit parameter
const result = await search({
   "location": {
     "country": "usa"
   },
   "activity": {
     "search": "electricity",
     "unit": "kWh"
   }
 });

Example

// Search with optional scope parameter
const result = await search({
   "location": {
     "country": "usa"
   },
   "activity": {
     "search": "natural gas",
     "scope": "1"
   }
 });

Example

// Search with both unit and scope parameters
const result = await search({
   "location": {
     "country": "usa",
     "stateProvince": "california"
   },
   "time": {
     "date": "2025-06-10"
   },
   "activity": {
     "search": "electricity",
     "unit": "MWh",
     "scope": "2"
   },
   "pagination": {
     "page": 1,
     "size": 10
   }
 });

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.

async AuditLog.getAuditConfig()¶

Retrieves the audit log configuration for the organization.

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

Returns:: Promise<AuditLogResponse> – Current audit log configuration

Example

const config = await getConfig();
// Output: { logRequest: true, logResponse: false }

async AuditLog.updateAuditConfig(payload)¶

Updates the audit log configuration for the organization.

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

Note: If the configuration is already set to the requested values, the API will return a 409 Conflict status with a message indicating no change was made. This is handled gracefully and the current configuration is returned.

Arguments:

payload (AuditLogRequest) – Audit log configuration

Returns:

Promise<AuditLogResponse> – Updated configuration or current configuration if no change

Example

const result = await update({ logRequest: false, logResponse: false });
// If already set to these values:
// { logRequest: false, logResponse: false, message: "No change in audit log configuration" }

Global Metadata API¶

The global Metadata API provides a unified way to query metadata across different endpoints without calling endpoint-specific methods.

getTypes/postTypes and getArea/postArea: Accept an optional endpoint parameter to query metadata for specific endpoints
getUnits/postUnits: Accept an optional type parameter to query units for specific emission types

Supported endpoints (for getTypes/postTypes and getArea/postArea): calculation, location, stationary, mobile, fugitive, factor, search, transportation-and-distribution, economic-activity, real-estate

getTypes¶

async Metadata.getTypes(endpoint)¶

Retrieves available emission source types for a specific endpoint using GET request.

Arguments:

endpoint (string) – The endpoint name to retrieve types for. Defaults to ‘calculation’ if not provided.

Returns:

Promise<TypeResponse> – A promise that resolves to a TypeResponse containing the available types

Example

// Get types for calculation endpoint (default)
const types = await getTypes();

// Get types for a specific endpoint
const locationTypes = await getTypes('location');

async Metadata.postTypes(endpoint)¶

Retrieves available emission source types for a specific endpoint using POST request.

Arguments:

endpoint (string) – The endpoint name to retrieve types for. Defaults to ‘calculation’ if not provided.

Returns:

Promise<TypeResponse> – A promise that resolves to a TypeResponse containing the available types

Example

// Get types for calculation endpoint (default)
const types = await postTypes();

// Get types for a specific endpoint
const stationaryTypes = await postTypes('stationary');

getArea¶

async Metadata.getArea(endpoint)¶

Retrieves available geographic locations for a specific endpoint using GET request.

Arguments:

endpoint (string) – The endpoint name to retrieve locations for. Defaults to ‘calculation’ if not provided.

Returns:

Promise<AreaResponse> – A promise that resolves to an AreaResponse containing the available locations

Example

// Get areas for calculation endpoint (default)
const areas = await getArea();

// Get areas for a specific endpoint
const mobileAreas = await getArea('mobile');

async Metadata.postArea(endpoint)¶

Retrieves available geographic locations for a specific endpoint using POST request.

Arguments:

endpoint (string) – The endpoint name to retrieve locations for. Defaults to ‘calculation’ if not provided.

Returns:

Promise<AreaResponse> – A promise that resolves to an AreaResponse containing the available locations

Example

// Get areas for calculation endpoint (default)
const areas = await postArea();

// Get areas for a specific endpoint
const fugitiveAreas = await postArea('fugitive');

getUnits¶

async Metadata.getUnits(type)¶

Retrieves available measurement units for a specific type using GET request.

Arguments:

type (string) – The emission source type to retrieve units for. If not provided, returns the full UOM table.

Returns:

Promise<UnitResponse> – A promise that resolves to a UnitResponse containing the available units

Example

// Get all units
const allUnits = await getUnits();

// Get units for a specific type
const naturalGasUnits = await getUnits('Natural Gas');

async Metadata.postUnits(type)¶

Retrieves available measurement units for a specific type using POST request.

Arguments:

type (string) – The emission source type to retrieve units for. If not provided, returns the full UOM table.

Returns:

Promise<UnitResponse> – A promise that resolves to a UnitResponse containing the available units

Example

// Get all units
const allUnits = await postUnits();

// Get units for a specific type
const jetKeroseneUnits = await postUnits('Jet Kerosene');

Usage API¶

async Usage.getUsage(history=false)¶

Retrieves current billing period or historical usage data for the user by making a GET request to the API endpoint.

Arguments:

history (boolean) – Flag to retrieve current billing or historical usage data.

Returns:

Promise<UsageResponse> – A promise that resolves to a UsageResponse containing the organization’s usage data

Example

const usage = await getUsage();

Interfaces¶

interface Api.LocationRequestWithoutFactorId¶

Request parameters for location-based calculations without specifying a factor ID. Used for calculating emissions or other metrics based on location data.

LocationRequestWithoutFactorId

exported from interfaces.Api

interface Api.LocationRequestWithFactorId¶

Request parameters for location-based calculations with a specific factor ID. Used when the emission factor is already known and doesn’t need to be determined by location.

LocationRequestWithFactorId

exported from interfaces.Api

interface Api.CommonRequestWithoutFactorId¶

Common request parameters for calculations without specifying a factor ID. Used for general-purpose calculations based on location, time, and activity data.

CommonRequestWithoutFactorId

exported from interfaces.Api

interface Api.CommonRequestWithFactorId¶

Common request parameters for calculations with a specific factor ID. Used when the emission factor is already known and doesn’t need to be determined by location.

CommonRequestWithFactorId

exported from interfaces.Api

interface Api.GenericCalculationRequestWithoutFactorId¶

Request parameters for generic calculations without specifying a factor ID. Used for calculations that may involve multiple units or complex activity data.

GenericCalculationRequestWithoutFactorId

exported from interfaces.Api

interface Api.GenericCalculationRequestWithFactorId¶

Request parameters for generic calculations with a specific factor ID. Used for complex calculations where the emission factor is already known.

GenericCalculationRequestWithFactorId

exported from interfaces.Api

interface Api.FactorRequestWithoutFactorId¶

Request parameters for retrieving factor information without specifying a factor ID. Used to look up appropriate emission factors based on location, time, and activity type.

FactorRequestWithoutFactorId

exported from interfaces.Api

interface Api.FactorRequestWithFactorId¶

Request parameters for retrieving specific factor information by ID. Used when the exact factor to retrieve is already known.

FactorRequestWithFactorId

exported from interfaces.Api

interface Api.SearchRequest¶

Request parameters for searching factors or activities. Used to find relevant factors or activities based on location, time, and search criteria.

SearchRequest

exported from interfaces.Api

interface common.Location¶

Represents a geographical location.: Location