URL: /sdk/typescript/types

---
title: 'Type Reference'
description: 'TypeScript type definitions for the Open Electricity client'
icon: 'i-cursor'
---

# 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"
```