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:

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:

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 intervalsanal
• 1y: Yearly intervals
• fy: Financial year intervals

Metric Types

DataMetric

Metrics available for network and facility data:

type DataMetric = "power" | "energy" | "emissions" | "market_value"

• power: Instantaneous power output (MW)
• energy: Energy generated (MWh)
• emissions: CO2 equivalent emissions (tCO2e)
• market_value: Market value ($)

MarketMetric

Metrics available for market data:

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:

type DataPrimaryGrouping = "network" | "network_region"

DataSecondaryGrouping

Secondary grouping options for data aggregation:

type DataSecondaryGrouping =
  | "fueltech"
  | "fueltech_group"
  | "renewable"
  | "dispatch_type"

Parameter Types

INetworkTimeSeriesParams

Parameters for network data queries:

interface INetworkTimeSeriesParams {
  interval?: DataInterval
  dateStart?: string
  dateEnd?: string
  primaryGrouping?: DataPrimaryGrouping
  secondaryGrouping?: DataSecondaryGrouping
}

IFacilityTimeSeriesParams

Parameters for facility data queries:

interface IFacilityTimeSeriesParams {
  interval?: DataInterval
  dateStart?: string
  dateEnd?: string
}

IMarketTimeSeriesParams

Parameters for market data queries:

interface IMarketTimeSeriesParams extends IFacilityTimeSeriesParams {
  primaryGrouping?: DataPrimaryGrouping
}

IFacilityParams

Parameters for facility queries:

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:

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

INetworkTimeSeries

Network time series data structure:

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:

interface IFacility {
  code: string
  name: string
  network_id: string
  network_region: string
  description: string | null
  units: IUnit[]
}

IFacilityDataRow

Structure for facility data rows:

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:

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

Error Types

OpenElectricityError

Custom error type for API errors:

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

NoDataFound

Error type for when no data matches the query (416 status):

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