OpenElectricity TypeScript Client

[!WARNING] This project and the v4 API are currently under active development.

A TypeScript client for the OpenElectricity API, providing access to electricity network data and metrics.

[!NOTE] API key signups are currently waitlisted and will be released gradually.

To obtain an API key visit platform.openelectricity.org.au

For documentation visit docs.openelectricity.org.au

The alternative Python client is available at github.com/openelectricity/openelectricity-python

Features

Full TypeScript support with comprehensive type definitions
Browser and Node.js compatible
Built-in data analysis tools with DataTable interface
Modern ESM and CommonJS module support
Timezone-aware datetime utilities for handling network-specific times

Installation

npm install openelectricity
# or
yarn add openelectricity
# or
bun add openelectricity

Usage

Basic Usage

Setup your API key in the environment variable OPENELECTRICITY_API_KEY.

export OPENELECTRICITY_API_KEY=<your-api-key>

import { OpenElectricityClient } from "openelectricity"

// Initialize client
const client = new OpenElectricityClient({
  // apiKey will be read from OPENELECTRICITY_API_KEY environment variable
  // baseUrl defaults to https://api.openelectricity.org.au/v4
})

// Get per-interval energy data for each fueltech for each region (returns DataTable)
const { response, datatable } = await client.getNetworkData("NEM", ["energy"], {
  interval: "5m",
  dateStart: "2024-01-01T00:00:00",
  dateEnd: "2024-01-02T00:00:00",
  primaryGrouping: "network_region",
  secondaryGroupings: ['fueltech_group']
})

// Get hourly price and demand data for each network region (returns DataTable)
const { response, datatable } = await client.getMarket("NEM", ["price", "demand"], {
  interval: "1h",
  dateStart: "2024-01-01T00:00:00",
  dateEnd: "2024-01-02T00:00:00",
  primaryGrouping: "network_region"
})

// Get facility-specific data (returns DataTable)
const { response, datatable } = await client.getFacilityData("NEM", "BANGOWF", ["energy", "market_value"], {
  interval: "1d",
  dateStart: "2024-01-01T00:00:00",
  dateEnd: "2024-01-02T00:00:00"
})

// Get all facilities and their units (returns RecordTable)
const { response, table } = await client.getFacilities({
  status_id: ["operating"],
  fueltech_id: ["coal_black", "coal_brown"]
})

Datetime Utilities

The client provides utilities for handling network-specific timezones and datetime operations:

import {
  isAware,
  makeAware,
  stripTimezone,
  getLastCompleteInterval,
  getNetworkTimezone,
} from "openelectricity"

// Check if a date string has timezone information
isAware("2024-01-01T00:00:00+10:00") // true
isAware("2024-01-01T00:00:00") // false

// Add network timezone information to a date
makeAware("2024-01-01T00:00:00", "NEM") // "2024-01-01T00:00:00+10:00"
makeAware("2024-01-01T00:00:00", "WEM") // "2024-01-01T00:00:00+08:00"

// Remove timezone information from a date string
stripTimezone("2024-01-01T00:00:00+10:00") // "2024-01-01T00:00:00"

// Get the last complete 5-minute interval for a network
getLastCompleteInterval("NEM") // Returns the last complete 5-minute interval in AEST

// Get timezone offset for a network (in hours)
getNetworkTimezone("NEM") // Returns 10 (AEST/UTC+10)
getNetworkTimezone("WEM") // Returns 8 (AWST/UTC+8)

Available Metrics

The client supports three types of data:

Network Data (getNetworkData):
- power: Instantaneous power output (MW)
- energy: Energy generated (MWh)
- emissions: CO2 equivalent emissions (tCO2e)
- market_value: Market value ($)
Market Data (getMarket):
- price: Spot price ($/MWh)
- demand: Demand (MW)
- demand_energy: Energy demand (MWh)
Facility Data (getFacilityData):
- Supports the same metrics as Network Data
- Data is specific to a single facility

Available Groupings

Queries for network data and market data support groupings. These groupings are all returned as columns in the data table.

Primary grouping (primaryGrouping)
- network - Group by network (default)
- network_region - Group by network region

Further, getNetworkData supports secondary groupings:

Secondary groupings (secondaryGroupings) - fueltech - All the core fueltechs - fueltech_group - Simplified list of fueltechs - renewable - Group by renewable

Data Tables

The client provides two types of data tables for different use cases:

DataTable - For time series data (returned by getNetworkData, getMarket, and getFacilityData)

// Filter rows
const filtered = datatable.filter(row => row.network_region === "NSW1")

// Group by columns
const grouped = datatable.groupBy(["network_region"], "sum")

// Sort by values
const sorted = datatable.sortBy(["energy"], false)

// Get summary statistics
const stats = datatable.describe()

RecordTable - For record-style data like facilities (returned by getFacilities)

// Get all records
const records = table.getRecords()

// Filter records
const coalUnits = table.filter(record => record.unit_fueltech?.includes("coal"))

// Select specific columns
const summary = table.select(["facility_name", "unit_code", "unit_capacity"])

// Sort by capacity
const largest = table.sortBy(["unit_capacity"], false)

// Get unique values
const regions = table.unique("facility_region")

Examples

Check out the examples directory for more detailed examples:

basic.ts: Simple data fetching
analysis.ts: Data analysis features
energy_renewable_daily.ts: Renewable energy analysis
power_latest.ts: Recent power generation analysis
emission_factor.ts: Emission factor calculations
facility_data.ts: Example querying a facility

Development

# Install dependencies
bun install

# Run tests
bun test

# Build
bun run build

# Lint
bun run lint

License

MIT