Client Initialization

import { OpenElectricityClient } from 'openelectricity'

const client = new OpenElectricityClient({
  apiKey?: string,    // Optional: API key (recommended to use OPENELECTRICITY_API_KEY env var)
  baseUrl?: string    // Optional: API endpoint (recommended to use OPENELECTRICITY_API_URL env var)
})

Network Data

Fetches the endpoint at (/v4/data/network)[/api/data/get-network-data]

getNetworkData

Fetch network-level time series data for power, energy, emissions, and market value metrics.

async getNetworkData(
  networkCode: NetworkCode,           // "NEM" | "WEM" | "AU"
  metrics: DataMetric[],             // Array of metrics to fetch
  params?: INetworkTimeSeriesParams  // Optional parameters
): Promise<ITimeSeriesResponse>

Parameters:

• networkCode: The network to fetch data for
• metrics: Array of metrics (e.g., [“power”, “energy”, “emissions”])
• params: Optional parameters:
  • interval: Time interval (e.g., “5m”, “1h”, “1d”)
  • dateStart: Start date (timezone-naive)
  • dateEnd: End date (timezone-naive)
  • primaryGrouping: Primary grouping field ("network" or "network_region")
  • secondaryGrouping: Array of secondary grouping fields ("fueltech", "fueltech_group", "status", "renewable")
  • network_region: Filter to a specific region (e.g., "NSW1")
  • fueltech: Array of UnitFueltechType to filter by
  • fueltech_group: Array of UnitFueltechGroupType to filter by

Example:

const { datatable } = await client.getNetworkData("NEM", ["energy"], {
  interval: "1h",
  dateStart: "2024-01-01T00:00:00",
  dateEnd: "2024-01-02T00:00:00",
  primaryGrouping: "network_region",
  secondaryGrouping: ["fueltech"]
})

Facility Data

Fetches the endpoint at (/v4/data/facility)[/api/data/get-facility-data]

getFacilityData

Fetch facility-specific time series data.

async getFacilityData(
  networkCode: NetworkCode,                // "NEM" | "WEM" | "AU"
  facilityCodes: string | string[],        // Single facility or array of facilities
  metrics: DataMetric[],                   // Array of metrics to fetch
  params?: IFacilityTimeSeriesParams      // Optional parameters
): Promise<ITimeSeriesResponse>

Parameters:

• networkCode: The network containing the facilities
• facilityCodes: Single facility code or array of codes
• metrics: Array of metrics to fetch
• params: Optional parameters:
  • interval: Time interval
  • dateStart / dateEnd: Timezone-naive dates in network time
  • unitCodes: Single unit code or array, narrows to specific units within the facilities

Example:

const { datatable } = await client.getFacilityData(
  "NEM",
  ["BAYSW1", "ERARING"],
  ["power", "emissions"],
  {
    interval: "5m",
    dateStart: "2024-01-01T00:00:00",
    dateEnd: "2024-01-02T00:00:00"
  }
)

Market Data

Fetches the endpoint at (/v4/market)[/api/data/get-network-data]

getMarket

Fetch market-related metrics like price, demand, and curtailment.

async getMarket(
  networkCode: NetworkCode,              // "NEM" | "WEM" | "AU"
  metrics: MarketMetric[],              // Array of market metrics
  params?: IMarketTimeSeriesParams      // Optional parameters
): Promise<ITimeSeriesResponse>

Parameters:

• networkCode: The market to fetch data for
• metrics: Array of market metrics including:
  • Price and demand: "price", "demand", "demand_energy", "demand_gross", "demand_gross_energy"
  • Renewable generation: "generation_renewable", "generation_renewable_with_storage", "renewable_proportion", "renewable_with_storage_proportion" (and their _energy variants)
  • Curtailment power (MW): "curtailment", "curtailment_solar_utility", "curtailment_wind"
  • Curtailment energy (MWh): "curtailment_energy", "curtailment_solar_utility_energy", "curtailment_wind_energy"
  • Flows: "flow_imports", "flow_exports" (and their _energy variants)
• params: Optional parameters:
  • interval, dateStart, dateEnd
  • primaryGrouping: "network" or "network_region"
  • network_region: Filter to a specific region (e.g., "NSW1")

Example - Price and Demand:

const { datatable } = await client.getMarket("NEM", ["price", "demand"], {
  interval: "30m",
  dateStart: "2024-01-01T00:00:00",
  dateEnd: "2024-01-02T00:00:00",
  primaryGrouping: "network_region"
})

Example - Curtailment Power (5-minute intervals):

// Fetch real-time curtailment power data (MW)
const { datatable } = await client.getMarket(
  "NEM", 
  ["curtailment_solar_utility", "curtailment_wind", "curtailment"],
  {
    interval: "5m",
    dateStart: "2024-01-01T00:00:00",
    // Omit dateEnd to get latest available data
    primaryGrouping: "network_region"
  }
)

Example - Curtailment Energy (Daily totals):

// Fetch daily curtailment energy totals (MWh)
const { datatable } = await client.getMarket(
  "NEM",
  ["curtailment_solar_utility_energy", "curtailment_wind_energy", "curtailment_energy"],
  {
    interval: "1d",
    dateStart: "2024-01-01",
    dateEnd: "2024-01-31",
    primaryGrouping: "network_region"
  }
)

Facility Information

getFacilities

Fetches the endpoint at (/v4/facilities)[/api/facilities/get-facilities]

Get information about generation facilities and their units.

async getFacilities(
  params?: IFacilityParams  // Optional filter parameters
): Promise<FacilityResponse>

Parameters:

• params: Optional filters:
  • status_id: Array of facility statuses
  • fueltech_id: Array of fuel technologies
  • network_id: Network code or array of codes
  • network_region: Specific network region

Example:

const { table } = await client.getFacilities({
  status_id: ["operating"],
  fueltech_id: ["solar_utility", "wind"],
  network_id: "NEM"
})

Pollution Data

getFacilityPollution

Fetches the endpoint at /v4/pollution/facilities.

Get time-series pollution data from the National Pollutant Inventory for facilities with NPI tracking.

async getFacilityPollution(
  params?: IFacilityPollutionParams
): Promise<ITimeSeriesResponse>

Parameters:

• params: Optional filters:
  • facility_code: Array of facility codes
  • pollutant_code: Array of PollutantCode values ("nox", "so2", "co", etc.)
  • pollutant_category: Array of PollutantCategory values ("air_pollutant", "heavy_metal", etc.)
  • dateStart / dateEnd: Timezone-naive dates

When the response contains no rows, datatable is undefined.

Example:

const { response, datatable } = await client.getFacilityPollution({
  facility_code: ["ERARING"],
  pollutant_code: ["nox", "so2"],
})

Metrics Discovery

getAvailableMetrics

Fetches the endpoint at /v4/metrics.

Discover which metrics the API supports along with their units, descriptions, default aggregations, and which endpoints they are valid for.

async getAvailableMetrics(): Promise<IMetricsResponse>

Errors are surfaced as OpenElectricityError (404 → NoDataFound, 403 → permission-denied).

Example:

const { metrics, endpoints } = await client.getAvailableMetrics()
console.log(endpoints.data)        // metrics valid on /data
console.log(metrics.power.unit)    // "MW"

User Information

getCurrentUser

Fetches the endpoint at (/v4/user)[/api/user/get-user-me]

Get information about the current API user.

async getCurrentUser(): Promise<IAPIResponse<IUser>>

Example:

const { data: user } = await client.getCurrentUser()
console.log(user.plan)       // "COMMUNITY" | "BASIC" | "PRO" | "ENTERPRISE"
console.log(user.roles)      // optional OpenNEMRolesType[]
console.log(user.rate_limit) // optional number