Open Electricity Documentation
Platform

Type Reference

TypeScript type definitions for the Open Electricity client

Type Reference

The Open Electricity client uses TypeScript to provide type safety and better developer experience. This page documents all the types used in the client.

Network Types

NetworkCode

Represents the supported electricity networks:

typescript
type NetworkCode = "NEM" | "WEM" | "AU"
  • NEM: National Electricity Market (Eastern and Southern Australia)
  • WEM: Western Australian Electricity Market
  • AU: Australia-wide (defaults to NEM timezone)

DataInterval

Supported time intervals for data aggregation:

typescript
type DataInterval = "5m" | "1h" | "1d" | "7d" | "1M" | "3M" | "season" | "1y" | "fy"
  • 5m: 5-minute intervals
  • 1h: Hourly intervals
  • 1d: Daily intervals
  • 7d: Weekly intervals
  • 1M: Monthly intervals
  • 3M: Quarterly intervals
  • season: Seasonal intervals
  • 1y: Yearly intervals
  • fy: Financial year intervals

Metric Types

DataMetric

Metrics available for network and facility data:

typescript
type DataMetric =
  | "power"
  | "energy"
  | "emissions"
  | "market_value"
  | "pollution"
  | "renewable_proportion"
  | "storage_battery"
  • power: Instantaneous power output (MW)
  • energy: Energy generated (MWh)
  • emissions: CO2 equivalent emissions (tCO2e)
  • market_value: Market value ($)
  • pollution: Pollutant emissions (kg), used with the /pollution/facilities endpoint
  • renewable_proportion: Renewable share of generation (%)
  • storage_battery: Battery storage state of charge (MWh)

MarketMetric

Metrics available for market data:

typescript
type MarketMetric =
  | "price"
  | "demand"
  | "demand_energy"
  | "demand_gross"
  | "demand_gross_energy"
  | "generation_renewable"
  | "generation_renewable_energy"
  | "generation_renewable_with_storage"
  | "generation_renewable_with_storage_energy"
  | "renewable_proportion"
  | "renewable_with_storage_proportion"
  | "curtailment"
  | "curtailment_energy"
  | "curtailment_solar_utility"
  | "curtailment_solar_utility_energy"
  | "curtailment_wind"
  | "curtailment_wind_energy"
  | "flow_imports"
  | "flow_exports"
  | "flow_imports_energy"
  | "flow_exports_energy"

Price and Demand:

  • price: Market price ($/MWh)
  • demand: Operational demand (MW)
  • demand_energy: Operational demand energy (MWh)
  • demand_gross: Gross demand including rooftop solar (MW)
  • demand_gross_energy: Gross demand energy including rooftop solar (MWh)

Renewable Generation:

  • generation_renewable: Renewable generation including battery discharge and pumps, excluding TUMUT3 (MW)
  • generation_renewable_energy: Renewable energy (MWh)
  • generation_renewable_with_storage: Renewable generation including TUMUT3 hybrid hydro+storage (MW)
  • generation_renewable_with_storage_energy: Renewable energy including TUMUT3 (MWh)
  • renewable_proportion: Renewable share of gross demand (%)
  • renewable_with_storage_proportion: Renewable+storage share of gross demand (%)

Curtailment:

  • curtailment / curtailment_energy: Total curtailment (MW / MWh)
  • curtailment_solar_utility / curtailment_solar_utility_energy: Solar curtailment (MW / MWh)
  • curtailment_wind / curtailment_wind_energy: Wind curtailment (MW / MWh)

Interconnector Flows:

  • flow_imports / flow_imports_energy: Region imports (MW / MWh)
  • flow_exports / flow_exports_energy: Region exports (MW / MWh)

Grouping Types

DataPrimaryGrouping

Primary grouping options for data aggregation:

typescript
type DataPrimaryGrouping = "network" | "network_region"

DataSecondaryGrouping

Secondary grouping options for data aggregation:

typescript
type DataSecondaryGrouping =
  | "fueltech"
  | "fueltech_group"
  | "status"
  | "renewable"

Unit Types

UnitFueltechType

Fuel technologies for a unit:

typescript
type UnitFueltechType =
  | "battery"
  | "battery_charging"
  | "battery_discharging"
  | "bioenergy_biogas"
  | "bioenergy_biomass"
  | "coal_black"
  | "coal_brown"
  | "distillate"
  | "gas_ccgt"
  | "gas_ocgt"
  | "gas_recip"
  | "gas_steam"
  | "gas_wcmg"
  | "hydro"
  | "hydro_and_storage"
  | "pumps"
  | "solar_rooftop"
  | "solar_thermal"
  | "solar_utility"
  | "nuclear"
  | "other"
  | "solar"
  | "wind"
  | "wind_offshore"
  | "imports"
  | "exports"
  | "interconnector"
  | "aggregator_vpp"
  | "aggregator_dr"

A matching FuelTech const is exported for autocomplete (FuelTech.SOLAR_UTILITY, etc.).

UnitFueltechGroupType

typescript
type UnitFueltechGroupType =
  | "coal"
  | "gas"
  | "wind"
  | "solar"
  | "battery"
  | "battery_charging"
  | "battery_discharging"
  | "hydro"
  | "distillate"
  | "bioenergy"
  | "pumps"
  | "renewable"
  | "fossil"
  | "other"

A matching FuelTechGroup const is exported.

UnitStatusType

typescript
type UnitStatusType = "committed" | "operating" | "retired"

A matching UnitStatus const is exported.

UnitDispatchType

typescript
type UnitDispatchType =
  | "GENERATOR"
  | "LOAD"
  | "BIDIRECTIONAL"
  | "INTERCONNECTOR"

UnitDateSpecificity

How specific a unit-related date is:

typescript
type UnitDateSpecificity = "year" | "month" | "quarter" | "day"

Parameter Types

IFacilityTimeSeriesParams

Parameters for facility data queries:

typescript
interface IFacilityTimeSeriesParams {
  interval?: DataInterval
  dateStart?: string
  dateEnd?: string
  unitCodes?: string | string[]
}

IMarketTimeSeriesParams

Parameters for market data queries:

typescript
interface IMarketTimeSeriesParams extends IFacilityTimeSeriesParams {
  primaryGrouping?: DataPrimaryGrouping
  network_region?: string
}

INetworkTimeSeriesParams

Parameters for network data queries:

typescript
interface INetworkTimeSeriesParams extends IMarketTimeSeriesParams {
  secondaryGrouping?: DataSecondaryGrouping[]
  fueltech?: UnitFueltechType[]
  fueltech_group?: UnitFueltechGroupType[]
}

IFacilityParams

Parameters for facility queries:

typescript
interface IFacilityParams {
  status_id?: UnitStatusType[]
  fueltech_id?: UnitFueltechType[]
  network_id?: NetworkCode | NetworkCode[]
  network_region?: string
}

Response Types

ITimeSeriesResponse

Standard response type for time series data:

typescript
interface ITimeSeriesResponse {
  response: IAPIResponse<INetworkTimeSeries[]>
  datatable?: DataTable
}

INetworkTimeSeries

Network time series data structure:

typescript
interface INetworkTimeSeries {
  network_code: string
  metric: Metric
  unit: string
  interval: DataInterval
  start: string
  end: string
  groupings: DataPrimaryGrouping[] | DataSecondaryGrouping[]
  results: ITimeSeriesResult[]
  network_timezone_offset: string
}

IFacility

Facility information structure:

typescript
interface IFacility {
  code: string
  name: string
  network_id: string
  network_region: string
  description: string | null
  npi_id: string | null
  location: ILocation | null
  units: IUnit[]
  created_at?: string | null
  updated_at?: string | null
}

IFacilityPollutionParams

Parameters for the /pollution/facilities endpoint:

typescript
interface IFacilityPollutionParams {
  facility_code?: string[]
  pollutant_code?: PollutantCode[]
  pollutant_category?: PollutantCategory[]
  dateStart?: string
  dateEnd?: string
}

PollutantCategory

typescript
type PollutantCategory =
  | "air_pollutant"
  | "water_pollutant"
  | "heavy_metal"
  | "organic"

PollutantCode

typescript
type PollutantCode =
  // Air pollutants
  | "nox" | "so2" | "co" | "pm10" | "pm2_5" | "voc" | "ammonia" | "hcl"
  // Heavy metals
  | "as" | "cd" | "cr3" | "cr6" | "cu" | "hg" | "ni" | "pb" | "zn"
  // Organic compounds
  | "benzene" | "formaldehyde" | "pah" | "dioxins"
  // Other
  | "fluoride"

IFacilityDataRow

Structure for facility data rows:

typescript
interface IFacilityDataRow {
  time: string
  value: number
  facility_code: string
  facility_name: string
  facility_network: string
  facility_region: string
  unit_code: string
  unit_fueltech: UnitFueltechType | null
  unit_status: UnitStatusType | null
  unit_capacity: number | null
  unit_emissions_factor: number | null
  unit_first_seen: string | null
  unit_last_seen: string | null
  unit_dispatch_type: UnitDispatchType
}

Data Analysis Types

IDataTableRow

Structure for data table rows:

typescript
interface IDataTableRow {
  interval: Date
  [key: string]: Date | string | number | boolean | null
}

Error Types

OpenElectricityError

Custom error type for API errors:

typescript
class OpenElectricityError extends Error {
  constructor(
    message: string,
    public response?: IAPIErrorResponse
  )
}

NoDataFound

Error type thrown when no data matches the query (HTTP 404):

typescript
class NoDataFound extends Error {
  constructor(message: string = "No data found")
}

API Response Types

IAPIResponse

Standard envelope returned by the API:

typescript
interface IAPIResponse<T> {
  version?: string
  created_at?: string
  success: boolean
  error: string | null
  data: T
  total_records?: number
}

version and created_at are optional. The /me endpoint may omit them.

IValidationErrorDetail

Structured validation error details surfaced on OpenElectricityError.details:

typescript
interface IValidationErrorDetail {
  error?: string
  supported_metrics?: string[]
  requested_metrics?: string[]
  invalid_metrics?: string[]
  hint?: string
  [key: string]: unknown
}

IMetricsResponse

Response shape from getAvailableMetrics():

typescript
interface IMetricMetadata {
  name: string
  unit: string
  description: string
  default_aggregation: string
  precision: number
}

interface IMetricsResponse {
  metrics: Record<string, IMetricMetadata>
  total: number
  endpoints: {
    market: string[]
    data: string[]
  }
}

User Types

IUser

typescript
interface IUser {
  id: string
  full_name: string
  email: string
  owner_id: string
  plan: UserPlan
  meta: IUserMeta
  rate_limit?: number
  unkey_meta?: Record<string, unknown>
  roles?: OpenNEMRolesType[]
}

interface IUserMeta {
  remaining: number
}

UserPlan

typescript
type UserPlan = "COMMUNITY" | "BASIC" | "PRO" | "ENTERPRISE"

OpenNEMRolesType

typescript
type OpenNEMRolesType =
  | "admin"
  | "pro"
  | "academic"
  | "user"
  | "anonymous"

A matching OpenNEMRoles const is also exported for autocomplete:

typescript
import { OpenNEMRoles } from "openelectricity"

OpenNEMRoles.ADMIN  // "admin"
OpenNEMRoles.PRO    // "pro"
Edit this page

Type to search…

↑↓ navigate ↵ open esc close