Full reference

This part of the documentation covers the public classes and methods for Energy Quantified’s Python library. All interaction with the API happens through the energyquantified.EnergyQuantified class:

The main client

The default client

class energyquantified.EnergyQuantified(api_key=None, api_key_file=None, ssl_verify=True, timeout=20.0, http_delay=0.0667, api_url='https://app.energyquantified.com/api', proxies=None)

The Time Series API client.

Wraps the Energy Quantified Time Series API. Handles validation, network errors, rate limiting, and parsing of the API responses.

Exactly one of api_key and api_key_file must be set at the same time. api_key_file shall be the file path to a file that contains just the API key (blank lines a stripped when read).

Parameters
  • api_key (string, optional) – The API key for your user account

  • api_key_file (string, file, optional) – A file path to a file that contains the API key

  • ssl_verify (bool, optional) – Whether or not to verify the server certificate, defaults to True

  • timeout (float, optional) – Maximum timeout per HTTP request, defaults to 20.0

  • http_delay (float, optional) – The minimum number of seconds between the start of each HTTP request, defaults to 0.0667 seconds (15 req/s)

  • api_url (string, optional) – The root URL for the API

  • proxies (dict, optional) – Map of proxies, defaults to None (no proxy)

Basic usage:

>>> from energyquantified import EnergyQuantified
>>> eq = EnergyQuantified(api_key="aaaa-bbbb-cccc-dddd")
>>> eq.metadata.curves(q="de wind power actual")
events

See energyquantified.api.EventsAPI. For using the curve events stream.

instances

See energyquantified.api.InstancesAPI. For loading time series instances.

is_api_key_valid()

Check if the supplied API key is valid/user account can sign in.

Does so by trying to load the categories list. If it succeeds, then the user has supplied a valid API key.

Returns

True if API key is valid, otherwise False

Return type

bool

Raises

APIError – If there were any network- or server-related issues while check the API key

metadata

See energyquantified.api.MetadataAPI. For metadata queries (such as curve search and place lookups).

ohlc

See energyquantified.api.OhlcAPI. For loading OHLC data in various ways

period_instances

See energyquantified.api.PeriodInstancesAPI. For loading instances of period-based series.

periods

See energyquantified.api.PeriodsAPI. For loading period-based series.

srmc

See energyquantified.api.SrmcAPI. For loading and calculating short-run marginal costs (SRMC) from OHLC data.

timeseries

See energyquantified.api.TimeseriesAPI. For loading time series data.

user

See energyquantified.api.UserAPI. For user details.

The Realto client

class energyquantified.RealtoConnection(api_url=None, api_key=None, api_key_file=None, ssl_verify=True, timeout=20.0, http_delay=0.1, proxies=None)

The Time Series API client for customers subscribing via Realto.

Wraps a Energy Quantified Time Series API on Realto. Handles validation, network errors, rate limiting, and parsing of the API responses.

You must specify the api_url. There are constants with predefined URLs in this class.

Exactly one of api_key and api_key_file must be set at the same time. api_key_file shall be the file path to a file that contains just the API key (blank lines a stripped when read).

Parameters
  • api_url (string) – The root URL for the API, such as ‘https://api.realto.io/energyquantified-germany

  • api_key (string, optional) – The API key for your user account

  • api_key_file (string, file, optional) – A file path to a file that contains the API key

  • ssl_verify (bool, optional) – Whether or not to verify the server certificate, defaults to True

  • timeout (float, optional) – Maximum timeout per HTTP request, defaults to 20.0

  • http_delay (float, optional) – The minimum number of seconds between the start of each HTTP request, defaults to 0.1 seconds (10 req/s)

  • proxies (dict, optional) – Map of proxies, defaults to None (no proxy)

Basic usage:

>>> from energyquantified import RealtoConnection
>>> eq = RealtoConnection(
>>>     api_url=RealtoConnection.API_URL_GERMANY,
>>>     api_key="aaaa-bbbb-cccc-dddd"
>>> )
>>> eq.metadata.curves(q="de wind power actual")
API_URL_BELGIUM = 'https://api.realto.io/energyquantified-belgium'

The base URL for the Belgium data API on Realto.

API_URL_FRANCE = 'https://api.realto.io/energyquantified-france'

The base URL for the French data API on Realto.

API_URL_GERMANY = 'https://api.realto.io/energyquantified-germany'

The base URL for the German data API on Realto.

API_URL_NETHERLANDS = 'https://api.realto.io/energyquantified-netherlands'

The base URL for the Netherlands data API on Realto.

API_URL_UK = 'https://api.realto.io/energyquantified-greatbritain'

The base URL for the UK data API on Realto.

instances

See energyquantified.api.InstancesAPI. For loading time series instances.

is_api_key_valid()

Check if the supplied API key is valid/user account can sign in.

Does so by trying to load the categories list. If it succeeds, then the user has supplied a valid API key.

Returns

True if API key is valid, otherwise False

Return type

bool

Raises

APIError – If there were any network- or server-related issues while check the API key

metadata

See energyquantified.api.MetadataAPI. For metadata queries (such as curve search and place lookups).

period_instances

See energyquantified.api.PeriodInstancesAPI. For loading instances of period-based series.

periods

See energyquantified.api.PeriodsAPI. For loading period-based series.

timeseries

See energyquantified.api.TimeseriesAPI. For loading time series data.

API operations

The API operations are grouped into sections similar to the way the API is organized. Each of those sections are implemented in their own class.

Here are the different API section classes:


class energyquantified.api.MetadataAPI(*args, **kwargs)

Operations for curve search and place lookups. It also includes operations for listing attributes on energyquantified.metadata.Curve objects.

categories()

List all available categories.

Results are cached on repeated calls.

Returns

A set of available categories (strings)

Return type

set

curve(name)

Fetch a Curve object for a given curve name.

Parameters

name (str, required) – Freetext search, defaults to None

Returns

A Curve for the provided name

Return type

energyquantified.metadata.Curve

curves(q=None, area=None, curve_type=None, data_type=None, category=None, exact_category=None, frequency=None, commodity=None, has_place=None, page=1, page_size=50)

Search for curves. Supports paging.

Parameters
  • q (str, optional) – Freetext search, defaults to None

  • area (Area, str, optional) – Filter on an area, defaults to None

  • curve_type (CurveType, str, optional) – Filter on a CurveType, defaults to None

  • data_type (DataType, str, optional) – Filter on a DataType, defaults to None

  • category (list[str], optional) – List of one or more categories that the curves must have, defaults to None

  • exact_category (str, optional) – An exact string of the category list for a curve, defaults to None

  • frequency (Frequency, str, optional) – Filter by frequency, defaults to None

  • commodity (str, optional) – Filter by commodity, defaults to None

  • has_place (bool, optional) – True – only curves for places, False – only curves without places, defaults to None

  • page (int, optional) – Set the page, defaults to 1

  • page_size (int, optional) – Set the page size, defaults to 50

Returns

A page of energyquantified.metadata.Curve

Return type

energyquantified.utils.Page (subclass of list)

exact_categories()

List available exact combinations of categories (meaning combinations that exists in curve names). You can use this response for filtering curves on the exact_category parameter in MetadataAPI.curves.

Results are cached on repeated calls.

Returns

A set of category combinations (strings)

Return type

set

places(q=None, area=None, fuel=None, kind=None, tree=False, page=1, page_size=50)

Search for places. Supports places.

Parameters
  • q (str, optional) – Freetext search, defaults to None

  • area (Area, str, optional) – Filter on an area, defaults to None

  • fuel (str, optional) – Filter by fuel type, defaults to None

  • kind (str, optional) – Type of place (producer, consumer, river, etc.), defaults to None

  • tree (bool, optional) – Enable to return as a hierachy, defaults to False

  • page (int, optional) – Set the page, defaults to 1

  • page_size (int, optional) – Set the page size, defaults to 50

Returns

A page of energyquantified.metadata.Place

Return type

energyquantified.utils.Page (subclass of list)


class energyquantified.api.TimeseriesAPI(*args, **kwargs)

Time series API operations. Access these operations via an instance of the energyquantified.EnergyQuantified class:

>>> eq = EnergyQuantified(api_key="aaaa-bbbb-cccc-dddd")
>>> eq.timeseries.load(curve, begin, end)
load(curve, begin=None, end=None, time_zone=None, frequency=None, aggregation=None, hour_filter=None, threshold=None, unit=None)

Load time series data for a energyquantified.metadata.Curve.

This operation works for curves with curve_type = TIMESERIES | SCENARIO_TIMESERIES only.

Parameters
  • curve (energyquantified.metadata.Curve, str) – The curve or curve name

  • begin (date, datetime, str, required) – The begin date-time

  • end (date, datetime, str, required) – The end date-time

  • time_zone (TzInfo, optional) – Set the timezone for the date-times

  • frequency (Frequency, optional) – Set the preferred frequency for aggregations, defaults to None

  • aggregation (Aggregation, optional) – The aggregation method (i.e. AVERAGE, MIN, MAX), has no effect unless frequency is provided, defaults to AVERAGE

  • hour_filter (Filter, optional) – Filters on hours to include (i.e. BASE, PEAK), has no effect unless frequency is provided, defaults to BASE

  • threshold (int, optional) – Allow that many values to be missing within one frame of frequency. Has no effect unless frequency is provided, defaults to 0.

  • unit (str, optional) – Convert unit of data, defaults to curves unit

Returns

A time series

Return type

energyquantified.data.Timeseries


class energyquantified.api.InstancesAPI(*args, **kwargs)

Instance API operations. Access these operations via an instance of the energyquantified.EnergyQuantified class:

>>> eq = EnergyQuantified(api_key="aaaa-bbbb-cccc-dddd")
>>> eq.instances.list(curve, tags)
absolute(curve, delivery, begin, end, frequency=None, time_zone=None, hour_filter=None, unit=None, aggregation=None, tags=None, exclude_tags=None)

Load forecasted values from various instances for a specific point in time, to see how forecasts develop over time.

The point in time is the datetime supplied to the delivery parameter. Choose the frequency of the delivery by providing the frequency parameter. If a frequency is not provided, it defaults to using the Curve’s frequency.

Loads forecasted values from instances issued between begin (inclusive) and end (exclusive).

Parameters
  • curve (energyquantified.metadata.Curve, str) – The curve or curve name

  • delivery (date, datetime, str, required) – The datetime to load forecasted values for. The frequency and time zone of the delivery defaults to the Curve’s frequency and instance zone, respectively, but can be changed by the frequency and time_zone parameters.

  • begin (date, datetime, str, required) – Earliest instance issued date-time (inclusive)

  • end (date, datetime, str, required) – Latest instance issued date-time (exclusive)

  • frequency (Frequency, optional) – Aggregate the delivery to a lower frequency than the Curve’s frequency. Defaults to None, which keeps the result in the Curve’s frequency.

  • time_zone (TzInfo, optional) – Timezone of the delivery. Defaults to the Curve’s instance zone.

  • hour_filter (Filter, optional) – Filter on hours to include (i.e. BASE, PEAK), has no effect unless frequency is provided. Defaults to BASE.

  • unit (str, optional) – Convert unit of the data. Defaults to using the Curve’s unit.

  • aggregation (Aggregation, optional) – The aggregation method (i.e. AVERAGE, MIN, MAX), has no effect unless frequency is provided. Defaults to AVERAGE.

  • tags (list, str, optional) – Filter instances by tags, excluding instances not matching any of the tags. Defaults to None, which does not filter.

  • exclude_tags (list, str, optional) – Filter instances by tags, excluding instances matching any of the tags.

Returns

An absolute result

Return type

energyquantified.data.AbsoluteResult

get(curve, issued=None, tag='', time_zone=None, frequency=None, aggregation=None, hour_filter=None, threshold=None, ensembles=False, unit=None)

Get an instance specified by a issued (issue date) and tag. The default tag is blank and tags are case-insensitive.

Supports aggregation by specifying a frequency. Optionally, you can specify the aggregation method (default is average) and the hourly filter (base, peak, etc.).

This operation works for curves with curve_type = INSTANCE only.

Parameters
  • curve (energyquantified.metadata.Curve, str) – The curve or curve name

  • issued (datetime, date, str, optional) – The issue date-time, defaults to None

  • tag (str, optional) – The instance tag, defaults to “”

  • frequency (Frequency, optional) – Set the preferred frequency for aggregations, defaults to None

  • time_zone (TzInfo, optional) – Set the timezone for the date-times

  • aggregation (Aggregation, optional) – The aggregation method (i.e. AVERAGE, MIN, MAX), has no effect unless frequency is provided, defaults to AVERAGE

  • hour_filter (Filter, optional) – Filters on hours to include (i.e. BASE, PEAK), has no effect unless frequency is provided, defaults to BASE

  • threshold (int, optional) – Allow that many values to be missing within one frame of frequency. Has no effect unless frequency is provided, defaults to 0.

  • ensembles (bool, optional) – Whether to include ensembles where available, defaults to False

  • unit (str, optional) – Convert unit of data, defaults to curves unit

Returns

A time series instance

Return type

energyquantified.data.Timeseries

latest(curve, tags=None, issued_at_latest=None, time_zone=None, frequency=None, aggregation=None, hour_filter=None, threshold=None, ensembles=False, unit=None)

Get the latest time series instance with filtering on tags and issued_at_latest.

Supports aggregation by specifying a frequency. Optionally, you can specify the aggregation method (default is average) and the hourly filter (base, peak, etc.).

This operation works for curves with curve_type = INSTANCE only.

Parameters
  • curve (energyquantified.metadata.Curve, str) – The curve or curve name

  • tags (list, str, optional) – Filter by instance tags, defaults to None

  • issued_at_latest ([type], optional) – [description], defaults to None

  • time_zone (TzInfo, optional) – Set the timezone for the date-times

  • frequency (Frequency, optional) – Set the preferred frequency for aggregations, defaults to None

  • aggregation (Aggregation, optional) – The aggregation method (i.e. AVERAGE, MIN, MAX), has no effect unless frequency is provided, defaults to AVERAGE

  • hour_filter (Filter, optional) – Filters on hours to include (i.e. BASE, PEAK), has no effect unless frequency is provided, defaults to BASE

  • threshold (int, optional) – Allow that many values to be missing within one frame of frequency. Has no effect unless frequency is provided, defaults to 0.

  • ensembles (bool, optional) – Whether to include ensembles where available, defaults to False

  • unit (str, optional) – Convert unit of data, defaults to curves unit

Returns

A time series instance

Return type

energyquantified.data.Timeseries

list(curve, tags=None, exlude_tags=None, limit=25, issued_at_latest=None, issued_at_earliest=None)

List instances for the curve. Does not load any time series data.

Filter on the instance tags or exclude_tags (list of values allowed), or restrict the instance issue date by setting issued_at_latest and/or issued_at_earliest.

Limit the maximum number of returned instances by setting limit anywhere between 1 and 25.

This operation works for curves with curve_type = INSTANCE only.

Parameters
  • curve (energyquantified.metadata.Curve, str) – The curve or curve name

  • tags (list, str, optional) – Filter by instance tags, defaults to None

  • exlude_tags (list, str, optional) – Exclude instance tags, defaults to None

  • limit (int, optional) – Number of instances returned, defaults to 25

  • issued_at_latest (datetime, date, str, optional) – Filter by issue date, defaults to None

  • issued_at_earliest (datetime, date, str, optional) – Filter by issue date, defaults to None

Returns

A list of energyquantified.metadata.Instance

Return type

list

load(curve, tags=None, exlude_tags=None, limit=5, issued_at_latest=None, issued_at_earliest=None, time_zone=None, frequency=None, aggregation=None, hour_filter=None, threshold=None, ensembles=False, unit=None)

Load time series instances.

Filter on the instance tags or exclude_tags (list of values allowed), or restrict the instance issue date by setting issued_at_latest and/or issued_at_earliest.

When ensembles is False: Adjust the maximum number of returned time series instances by setting limit between 1 and 25.

When ensembles is True: limit must be between 1 and 10.

Supports aggregation by specifying a frequency. Optionally, you can specify the aggregation method (default is average) and the hourly filter (base, peak, etc.).

This operation works for curves with curve_type = INSTANCE only.

Parameters
  • curve (energyquantified.metadata.Curve, str) – The curve or curve name

  • tags (list, str, optional) – Filter by instance tags, defaults to None

  • exlude_tags (list, str, optional) – Exclude instance tags, defaults to None

  • limit (int, optional) – Maximum number of instances returned, defaults to 5

  • issued_at_latest ([type], optional) – [description], defaults to None

  • issued_at_earliest ([type], optional) – [description], defaults to None

  • time_zone (TzInfo, optional) – Set the timezone for the date-times

  • frequency (Frequency, optional) – Set the preferred frequency for aggregations, defaults to None

  • aggregation (Aggregation, optional) – The aggregation method (i.e. AVERAGE, MIN, MAX), has no effect unless frequency is provided, defaults to AVERAGE

  • hour_filter (Filter, optional) – Filters on hours to include (i.e. BASE, PEAK), has no effect unless frequency is provided, defaults to BASE

  • threshold (int, optional) – Allow that many values to be missing within one frame of frequency. Has no effect unless frequency is provided, defaults to 0.

  • ensembles (bool, optional) – Whether to include ensembles where available, defaults to False

  • unit (str, optional) – Convert unit of data, defaults to curves unit

Returns

A list energyquantified.data.Timeseries instances

Return type

list

relative(curve, begin=None, end=None, tag=None, days_ahead=1, issued='latest', time_of_day=None, after_time_of_day=None, before_time_of_day=None, modified_at_latest=None, time_zone=None, frequency=None, aggregation=None, hour_filter=None, threshold=None, unit=None)

Load one instance for each day based on some common criteria, stitch them together and return a continuous time series.

By default, this method selects the day-ahead instances (forecasts), but you can set days_ahead to 0 or higher. 0 means intraday, 1 means the day-ahead (default), 2 means the day after day-ahead, and so on.

You may control the time of the day the instance is issued by setting exactly one of the follow parameters: time_of_day, after_time_of_day or before_time_of_day. Additionally, you may control the time of the day the instance has been modified (or created if modified is null) by setting modified-at-latest. These should be set to a time (HH:MM:SS). You can use the datetime.time.

This operation works for curves with curve_type = INSTANCE only.

Parameters
  • curve (energyquantified.metadata.Curve, str) – The curve or curve name

  • begin (date, datetime, str, required) – The begin date-time

  • end (date, datetime, str, required) – The end date-time

  • days_ahead (int, optional) – The number of leading days (0 or higher), defaults to 1

  • issued (str, optional) – Whether to select the earliest or latest matching instance per day, allowed values “earliest” | “latest”, defaults to “earliest”

  • time_of_day (time, str, optional) – The exact time of the instance is issued, defaults to None

  • after_time_of_day (time, str, optional) – The instance must be issued at this time of day or after, defaults to None

  • before_time_of_day (time, str, optional) – The instance must be issued before this time of day, defaults to None

  • modified-at-latest (time, str, optional) – The instance must be modified (or created if modified is null) before this time of day, defaults to None

  • time_zone (TzInfo, optional) – Set the timezone for the date-times

  • frequency (Frequency, optional) – Set the preferred frequency for aggregations, defaults to None

  • aggregation (Aggregation, optional) – The aggregation method (i.e. AVERAGE, MIN, MAX), has no effect unless frequency is provided, defaults to AVERAGE

  • hour_filter (Filter, optional) – Filters on hours to include (i.e. BASE, PEAK), has no effect unless frequency is provided, defaults to BASE

  • threshold (int, optional) – Allow that many values to be missing within one frame of frequency. Has no effect unless frequency is provided, defaults to 0.

  • unit (str, optional) – Convert unit of data, defaults to curves unit

Returns

A time series

Return type

energyquantified.data.Timeseries

rolling(curve, begin, end, hours_ahead=0, tags=None, exclude_tags=None, time_zone=None, frequency=None, aggregation=None, hour_filter=None, threshold=None, unit=None)

Load a timeseries from begin to end, where each value is from the latest instance created at least hours_ahead before the datetime of the value.

Parameters
  • curve (energyquantified.metadata.Curve, str) – The curve or curve name

  • begin (date, datetime, str, required) – The begin date (inclusive) of the resulting timeseries

  • end (date, datetime, str, required) – The end date (exclusive) of the resulting timeseries

  • hours_ahead (int, optional) – The minimum number of hours between the created datetime of an instance and its values to be considered in the rolling forecast. Must be 0 at minimum and 24 at maximum. Defaults to 0

  • tags (list, str, optional) – Filter by instance tags, defaults to None

  • exclude_tags (list, str, optional) – Exclude instance tags, defaults to None

  • time_zone (TzInfo, optional) – Convert the timezone of the resulting series, defaults to None

  • frequency (Frequency, optional) – Set the preferred frequency for aggregations, defaults to None

  • aggregation (Aggregation, optional) – The aggregation method (i.e. AVERAGE, MIN, MAX). Has no effect unless frequency is provided. Defaults to AVERAGE.

  • hour_filter (Filter, optional) – Filters on hours to include (i.e. BASE, PEAK). Has no effect unless frequency is provided. Defaults to BASE.

  • threshold (_type_, optional) – Allow that many values to be missing within one frame of frequency. Has no effect unless frequency is provided, defaults to 0.

  • unit (str, optional) – Convert unit of data, defaults to the Curve’s unit

Returns

A time series instance

Return type

energyquantified.data.Timeseries

tags(curve)

Get all tags available for a curve.

This operation works for curves with curve_type = INSTANCE only.

Parameters

curve (energyquantified.metadata.Curve, str) – The curve or curve name

Returns

A set available tags for provded curve

Return type

set


class energyquantified.api.PeriodsAPI(*args, **kwargs)

Period-based series API operations. Access these operations via an instance of the energyquantified.EnergyQuantified class:

>>> eq = EnergyQuantified(api_key="aaaa-bbbb-cccc-dddd")
>>> eq.periods.load(curve, begin, end)
load(curve, begin=None, end=None, time_zone=None, unit=None)

Load period-based series data for a curve.

This operation works for curves with curve_type = PERIOD only.

Parameters
  • curve (energyquantified.metadata.Curve, str) – The curve or curve name

  • begin (date, datetime, str, required) – The begin date-time

  • end (date, datetime, str, required) – The end date-time

  • time_zone (TzInfo, optional) – Set the timezone for the date-times

  • unit (str, optional) – Convert unit of data, defaults to curves unit

Returns

A period-based series

Return type

energyquantified.data.Periodseries


class energyquantified.api.PeriodInstancesAPI(*args, **kwargs)

Period-based series instances API operations. Access these operations via an instance of the energyquantified.EnergyQuantified class:

>>> eq = EnergyQuantified(api_key="aaaa-bbbb-cccc-dddd")
>>> eq.period_instances.load(curve, begin, end)
get(curve, begin=None, end=None, issued=None, tag='', time_zone=None, unit=None)

Get a specific period-based series instance.

Parameters
  • curve (energyquantified.metadata.Curve, str) – The curve or curve name

  • begin (date, datetime, str, required) – The begin date-time

  • end (date, datetime, str, required) – The end date-time

  • issued (datetime, date, str, required) – The instance issue date

  • tag (str, required) – The instance tag

  • time_zone (TzInfo, optional) – Set the timezone for the date-times

  • unit (str, optional) – Convert unit of data, defaults to curves unit

Returns

A period-based series

Return type

energyquantified.data.Periodseries

latest(curve, begin=None, end=None, issued_at_latest=None, time_zone=None, unit=None)

Get the latest period-based series instance.

This operation works for curves with curve_type = INSTANCE_PERIOD only.

Parameters
  • curve (energyquantified.metadata.Curve, str) – The curve or curve name

  • begin (date, datetime, str, required) – The begin date-time

  • end (date, datetime, str, required) – The end date-time

  • issued_at_latest (date, datetime, str, optional) – The latest issue date for the loaded instance, defaults to None

  • time_zone (TzInfo, optional) – Set the timezone for the date-times

  • unit (str, optional) – Convert unit of data, defaults to curves unit

Returns

A period-based series

Return type

energyquantified.data.Periodseries

list(curve, tags=None, exlude_tags=None, limit=20, issued_at_latest=None, issued_at_earliest=None)

List instances for the curve. Does not lad any period-based series.

Filter on the instance tags or exclude_tags (list of values allowed), or restrict the instance issue date by setting issued_at_latest and/or issued_at_earliest.

Limit the maximum number of returned instances by setting limit anywhere between 1 and 20.

This operation works for curves with curve_type = INSTANCE_PERIOD only.

Parameters
  • curve (energyquantified.metadata.Curve, str) – The curve or curve name

  • tags (list, str, optional) – Filter by instance tags, defaults to None

  • exlude_tags (list, str, optional) – Exclude instance tags, defaults to None

  • limit (int, optional) – Number of instances returned, defaults to 25

  • issued_at_latest (datetime, date, str, optional) – Filter by issue date, defaults to None

  • issued_at_earliest (datetime, date, str, optional) – Filter by issue date, defaults to None

Returns

A list of energyquantified.metadata.Instance

Return type

list

load(curve, begin=None, end=None, tags=None, exlude_tags=None, limit=3, issued_at_latest=None, issued_at_earliest=None, time_zone=None, unit=None)

Load period-based series instances.

Filter on the instance tags or exclude_tags (list of values allowed), or restrict the instance issue date by setting issued_at_latest and/or issued_at_earliest.

This operation works for curves with curve_type = INSTANCE_PERIOD only.

Parameters
  • curve (energyquantified.metadata.Curve, str) – The curve or curve name

  • begin (date, datetime, str, required) – The begin date-time

  • end (date, datetime, str, required) – The end date-time

  • tags (list, str, optional) – Filter by instance tags, defaults to None

  • exlude_tags (list, str, optional) – Exclude instance tags, defaults to None

  • limit (int, optional) – Number of instances returned, defaults to 3

  • issued_at_latest (datetime, date, str, optional) – Filter by issue date, defaults to None

  • issued_at_earliest (datetime, date, str, optional) – Filter by issue date, defaults to None

  • time_zone (TzInfo, optional) – Set the timezone for the date-times

  • unit (str, optional) – Convert unit of data, defaults to curves unit

Returns

List of energyquantified.data.Periodseries objects

Return type

list

relative(curve, begin=None, end=None, days_ahead=None, before_time_of_day=None, time_zone=None, unit=None)

Loads period-based series instances n days-ahead and stitches them together to a single, continuous period series.

This operation is useful for loading historical day-ahead forecasts.

Parameters
  • curve (energyquantified.metadata.Curve, str) – The curve or curve name

  • begin (date, datetime, str, required) – The begin date-time

  • end (date, datetime, str, required) – The end date-time

  • days_ahead (int, required) – The n days ahead of the instance’s issue date. days-head = 0 means intraday forecasts, days-ahead = 1 means day-ahead, days-ahead = 2 means the day after day-ahead, and so on.

  • before_time_of_day (time, str, optional) – The time of day to load the instance, defaults to None

  • time_zone (TzInfo, optional) – Set the timezone for the date-times

  • unit (str, optional) – Convert unit of data, defaults to curves unit

Returns

A period-based series

Return type

energyquantified.data.Periodseries


class energyquantified.api.OhlcAPI(client)

Operations for OHLC data retrieval. Access these operations via an instance of the energyquantified.EnergyQuantified class:

>>> eq = EnergyQuantified(api_key="aaaa-bbbb-cccc-dddd")
>>> eq.ohlc.load(curve, begin, end)
latest(curve, date=None, unit=None)

Select all OHLC for specific trading day, while defaulting to the latest available OHLC data.

If date is given, this method will try to fetch OHLC data for that trading day. When there is no data for the given day, OHLC data will be loaded for the closest trading day earlier in time with data.

This operation works for curves with curve_type = OHLC only.

Parameters
  • curve (energyquantified.metadata.Curve, str) – The curve or curve name

  • date (date, str, required) – The trading date, defaults to today

  • unit (str, optional) – Convert unit of data, defaults to curves unit

Returns

A list of OHLC objects

Return type

energyquantified.data.OHLCList

latest_as_periods(curve, field=SETTLEMENT, date=None, time_zone=None, unit=None)

Load all OHLC rows from a single trading day, sort them, and merge/convert them to a continuous series.

It defaults to using the latest prices available, therefore “latest_as_period”.

If date is given, this method will try to fetch OHLC data for that trading day. When there is no data for the given day, OHLC data will be loaded for the closest trading day earlier in time with data.

By default, this method uses the settlement price. Select another field, such as close price, by setting the field parameter.

This operation works for curves with curve_type = OHLC only.

Parameters
  • curve (energyquantified.metadata.Curve, str) – The curve or curve name

  • field (OHLCField, str, optional) – The field to generate the series from, defaults to OHLCField.SETTLEMENT

  • date (date, str, required) – The trading date, defaults to today

  • time_zone (TzInfo, optional) – Set the timezone for the date-times

  • unit (str, optional) – Convert unit of data, defaults to curves unit

Returns

A period-based series

Return type

energyquantified.data.Periodseries

load(curve, begin=None, end=None, period=None, delivery=None, front=None, unit=None)

Load OHLC data for a energyquantified.metadata.Curve.

This operation works for curves with curve_type = OHLC only.

Parameters
  • curve (energyquantified.metadata.Curve, str) – The curve or curve name

  • begin (date, str, required) – The begin date

  • end (date, str, required) – The end date

  • period (ContractPeriod, str, optional) – Filter on contract period (day, week, month etc.), defaults to None

  • delivery (date, str, optional) – Filter on delivery date, requires parameter period to be set; cannot be used together with front, defaults to None

  • front (int, optional) – Filter on front contract, requires parameter period to be set; cannot be used together with delivery, defaults to None

  • unit (str, optional) – Convert unit of data, defaults to curves unit

Returns

A list of OHLC objects

Return type

energyquantified.data.OHLCList

load_delivery_as_timeseries(curve, begin=None, end=None, period=None, delivery=None, field=SETTLEMENT, fill=None, unit=None)

Load historical OHLC data for specific contract, and convert it to a energyquantified.data.Timeseries.

Defaults to use the settlement field, but you can select any field you want. All other parameters are required.

This operation works for curves with curve_type = OHLC only.

Parameters
  • curve (energyquantified.metadata.Curve, str) – The curve or curve name

  • begin (date, str, required) – The begin date

  • end (date, str, required) – The end date

  • period (ContractPeriod, str, required) – The contract period (week, month, quarter)

  • delivery (date, str, required) – The delivery date for the contract

  • field (OHLCField, str, required) – The field (close, settlement, etc.) to extract to a time series, defaults to OHLCField.SETTLEMENT

  • fill (str, optional) – How to handle days without trades. Allowed values are: no-fill do nothing, fill-holes fill in holes with data from previous trading day, forward-fill fill in all blanks with data from the previous trading day (also into the future). Defaults to no-fill.

  • unit (str, optional) – Convert unit of data, defaults to curves unit

Returns

A time series

Return type

energyquantified.data.Timeseries

load_front_as_timeseries(curve, begin=None, end=None, period=None, front=None, field=SETTLEMENT, fill=None, unit=None)

Load historical OHLC data for a continuous front contract, and convert it to a energyquantified.data.Timeseries.

Defaults to use the settlement field, but you can select any field you want. All other parameters are required.

This operation works for curves with curve_type = OHLC only.

Parameters
  • curve (energyquantified.metadata.Curve, str) – The curve or curve name

  • begin (date, str, required) – The begin date

  • end (date, str, required) – The end date

  • period (ContractPeriod, str, required) – The contract period (week, month, quarter)

  • front (int, required) – The front contract (1=front, 2=second front, etc.)

  • field (OHLCField, str, required) – The field (close, settlement, etc.) to extract to a time series, defaults to OHLCField.SETTLEMENT

  • fill (str, optional) – How to handle days without trades. Allowed values are: no-fill do nothing, fill-holes fill in holes with data from previous trading day, forward-fill fill in all blanks with data from the previous trading day (also into the future). Defaults to no-fill.

  • unit (str, optional) – Convert unit of data, defaults to curves unit

Returns

A time series

Return type

energyquantified.data.Timeseries


class energyquantified.api.SrmcAPI(client)

Operations for SRMC calculations in the API. Access these operations via an instance of the energyquantified.EnergyQuantified class:

>>> eq = EnergyQuantified(api_key="aaaa-bbbb-cccc-dddd")
>>> eq.srmc.load_front(curve, begin, end, period='month', front=1)
latest(curve, date=None, gas_therm_to_mwh=None, api2_tonne_to_mwh=None, carbon_emissions=None, efficiency=None, carbon_tax_area=None, unit=None)

Calculate short-run margincal costs (SRMC) for all settlement prices from a trading day. Defaults to using OHLC data from the latest available trading day, hence latest().

If date is given, this method will try to fetch OHLC data for that trading day. When there is no data for the given day, OHLC data will be loaded for the closest trading day earlier in time with data.

SRMC is calculated from a coal or gas curve of your choosing. It uses the daily reference rates from the European Central Bank (ECB) for currency conversions. The EUA price in the calculation is the settlement price from ICE.

Some countries, such as Great Britain, has an additional flat tax on carbon emissions. Specify the carbon_tax_area parameter to apply tax rules for a specific country.

This operation works for coal or gas curves with curve_type = OHLC only.

Parameters
  • curve (energyquantified.metadata.Curve, str) – The curve or curve name

  • date (date, str, required) – The trading date, defaults to today

  • gas_therm_to_mwh (float, optional) – Conversion from pence/therm to GBP/MWh (still in higher-heating value). Defaults to 0.029307.

  • api2_tonne_to_mwh (float, optional) – Conversion from API2 coal to MWh. Defaults to 6.978.

  • carbon_emissions (float, optional) – The carbon content as tCO2/MWh. This value varies between coal and gas. For coal, the default factor is 0.34056. For gas, the default factor is 0.202.

  • efficiency (float, optional) – The energy efficiency. For coal, the default factor is 0.42. For gas, the default factor is 0.59.

  • carbon_tax_area (Area, str, optional) – Set an area to apply tax rules for.

  • unit (str, optional) – Convert unit of data, defaults to curves unit

Returns

An SRMC object with a list of OHLC objects

Return type

energyquantified.data.SRMC

latest_as_periods(curve, date=None, gas_therm_to_mwh=None, api2_tonne_to_mwh=None, carbon_emissions=None, efficiency=None, carbon_tax_area=None, time_zone=None, unit=None)

Calculate short-run margincal costs (SRMC) for all settlement prices from a trading day, sort them, and merge/convert them to a continuous series.

Defaults to using OHLC data from the latest available trading day, hence latest in the method name.

If date is given, this method will try to fetch OHLC data for that trading day. When there is no data for the given day, OHLC data will be loaded for the closest trading day earlier in time with data.

SRMC is calculated from a coal or gas curve of your choosing. It uses the daily reference rates from the European Central Bank (ECB) for currency conversions. The EUA price in the calculation is the settlement price from ICE.

Some countries, such as Great Britain, has an additional flat tax on carbon emissions. Specify the carbon_tax_area parameter to apply tax rules for a specific country.

This operation works for coal or gas curves with curve_type = OHLC only.

Parameters
  • curve (energyquantified.metadata.Curve, str) – The curve or curve name

  • date (date, str, required) – The trading date, defaults to today

  • gas_therm_to_mwh (float, optional) – Conversion from pence/therm to GBP/MWh (still in higher-heating value). Defaults to 0.029307.

  • api2_tonne_to_mwh (float, optional) – Conversion from API2 coal to MWh. Defaults to 6.978.

  • carbon_emissions (float, optional) – The carbon content as tCO2/MWh. This value varies between coal and gas. For coal, the default factor is 0.34056. For gas, the default factor is 0.202.

  • efficiency (float, optional) – The energy efficiency. For coal, the default factor is 0.42. For gas, the default factor is 0.59.

  • carbon_tax_area (Area, str, optional) – Set an area to apply tax rules for.

  • time_zone (TzInfo, optional) – Set the timezone for the date-times

  • unit (str, optional) – Convert unit of data, defaults to curves unit

Returns

An SRMC object with a period-based series

Return type

energyquantified.data.SRMC

load_delivery(curve, begin=None, end=None, period=None, delivery=None, gas_therm_to_mwh=None, api2_tonne_to_mwh=None, carbon_emissions=None, efficiency=None, carbon_tax_area=None, unit=None)

Calculate historical short-run margincal costs (SRMC) for a specific contract, such as the year 2021, the month Jan 2021, etc.

SRMC is calculated from a coal or gas curve of your choosing. It uses the daily reference rates from the European Central Bank (ECB) for currency conversions. The EUA price in the calculation is the settlement price from ICE.

Some countries, such as Great Britain, has an additional flat tax on carbon emissions. Specify the carbon_tax_area parameter to apply tax rules for a specific country.

This operation works for coal or gas curves with curve_type = OHLC only.

Parameters
  • curve (energyquantified.metadata.Curve, str) – The curve or curve name

  • begin (date, str, required) – The begin date

  • end (date, str, required) – The end date

  • period (ContractPeriod, str, required) – Filter on contract period (day, week, month etc.), defaults to None

  • delivery (date, str, required) – Filter on delivery date, requires parameter period to be set; cannot be used together with front, defaults to None

  • gas_therm_to_mwh (float, optional) – Conversion from pence/therm to GBP/MWh (still in higher-heating value). Defaults to 0.029307.

  • api2_tonne_to_mwh (float, optional) – Conversion from API2 coal to MWh. Defaults to 6.978.

  • carbon_emissions (float, optional) – The carbon content as tCO2/MWh. This value varies between coal and gas. For coal, the default factor is 0.34056. For gas, the default factor is 0.202.

  • efficiency (float, optional) – The energy efficiency. For coal, the default factor is 0.42. For gas, the default factor is 0.59.

  • carbon_tax_area (Area, str, optional) – Set an area to apply tax rules for.

  • unit (str, optional) – Convert unit of data, defaults to curves unit

Returns

An SRMC object with a list of OHLC objects

Return type

energyquantified.data.SRMC

load_delivery_as_timeseries(curve, begin=None, end=None, period=None, delivery=None, fill=None, gas_therm_to_mwh=None, api2_tonne_to_mwh=None, carbon_emissions=None, efficiency=None, carbon_tax_area=None, unit=None)

Calculate historical short-run margincal costs (SRMC) for a specific contract and convert it to a daily time series.

A specific contract could be the year 2021, the month Jan 2021, etc.

SRMC is calculated from a coal or gas curve of your choosing. It uses the daily reference rates from the European Central Bank (ECB) for currency conversions. The EUA price in the calculation is the settlement price from ICE.

Some countries, such as Great Britain, has an additional flat tax on carbon emissions. Specify the carbon_tax_area parameter to apply tax rules for a specific country.

This operation works for coal or gas curves with curve_type = OHLC only.

Parameters
  • curve (energyquantified.metadata.Curve, str) – The curve or curve name

  • begin (date, str, required) – The begin date

  • end (date, str, required) – The end date

  • period (ContractPeriod, str, required) – Filter on contract period (day, week, month etc.), defaults to None

  • delivery (date, str, required) – Filter on delivery date, requires parameter period to be set; cannot be used together with front, defaults to None

  • fill (str, optional) – How to handle days without trades. Allowed values are: no-fill do nothing, fill-holes fill in holes with data from previous trading day, forward-fill fill in all blanks with data from the previous trading day (also into the future). Defaults to no-fill.

  • gas_therm_to_mwh (float, optional) – Conversion from pence/therm to GBP/MWh (still in higher-heating value). Defaults to 0.029307.

  • api2_tonne_to_mwh (float, optional) – Conversion from API2 coal to MWh. Defaults to 6.978.

  • carbon_emissions (float, optional) – The carbon content as tCO2/MWh. This value varies between coal and gas. For coal, the default factor is 0.34056. For gas, the default factor is 0.202.

  • efficiency (float, optional) – The energy efficiency. For coal, the default factor is 0.42. For gas, the default factor is 0.59.

  • carbon_tax_area (Area, str, optional) – Set an area to apply tax rules for.

  • unit (str, optional) – Convert unit of data, defaults to curves unit

Returns

An SRMC object with a timeseries object

Return type

energyquantified.data.SRMC

load_front(curve, begin=None, end=None, period=None, front=None, gas_therm_to_mwh=None, api2_tonne_to_mwh=None, carbon_emissions=None, efficiency=None, carbon_tax_area=None, unit=None)

Calculate historical short-run margincal costs (SRMC) for a continuous front contract.

SRMC is calculated from a coal or gas curve of your choosing. It uses the daily reference rates from the European Central Bank (ECB) for currency conversions. The EUA price in the calculation is the settlement price from ICE.

Some countries, such as Great Britain, has an additional flat tax on carbon emissions. Specify the carbon_tax_area parameter to apply tax rules for a specific country.

This operation works for coal or gas curves with curve_type = OHLC only.

Parameters
  • curve (energyquantified.metadata.Curve, str) – The curve or curve name

  • begin (date, str, required) – The begin date

  • end (date, str, required) – The end date

  • period (ContractPeriod, str, required) – Filter on contract period (day, week, month etc.), defaults to None

  • front (int, required) – The front contract (1=front, 2=second front, etc.)

  • gas_therm_to_mwh (float, optional) – Conversion from pence/therm to GBP/MWh (still in higher-heating value). Defaults to 0.029307.

  • api2_tonne_to_mwh (float, optional) – Conversion from API2 coal to MWh. Defaults to 6.978.

  • carbon_emissions (float, optional) – The carbon content as tCO2/MWh. This value varies between coal and gas. For coal, the default factor is 0.34056. For gas, the default factor is 0.202.

  • efficiency (float, optional) – The energy efficiency. For coal, the default factor is 0.42. For gas, the default factor is 0.59.

  • carbon_tax_area (Area, str, optional) – Set an area to apply tax rules for.

  • unit (str, optional) – Convert unit of data, defaults to curves unit

Returns

An SRMC object with a list of OHLC objects

Return type

energyquantified.data.SRMC

load_front_as_timeseries(curve, begin=None, end=None, frequency=None, period=None, front=None, fill=None, gas_therm_to_mwh=None, api2_tonne_to_mwh=None, carbon_emissions=None, efficiency=None, carbon_tax_area=None, unit=None)

Calculate historical short-run margincal costs (SRMC) for a continuous front contract and convert the result to a daily time series.

SRMC is calculated from a coal or gas curve of your choosing. It uses the daily reference rates from the European Central Bank (ECB) for currency conversions. The EUA price in the calculation is the settlement price from ICE.

Some countries, such as Great Britain, has an additional flat tax on carbon emissions. Specify the carbon_tax_area parameter to apply tax rules for a specific country.

This operation works for coal or gas curves with curve_type = OHLC only.

Parameters
  • curve (energyquantified.metadata.Curve, str) – The curve or curve name

  • begin (date, str, required) – The begin date

  • end (date, str, required) – The end date

  • period (ContractPeriod, str, required) – Filter on contract period (day, week, month etc.), defaults to None

  • front (int, required) – The front contract (1=front, 2=second front, etc.)

  • fill (str, optional) – How to handle days without trades. Allowed values are: no-fill do nothing, fill-holes fill in holes with data from previous trading day, forward-fill fill in all blanks with data from the previous trading day (also into the future). Defaults to no-fill.

  • gas_therm_to_mwh (float, optional) – Conversion from pence/therm to GBP/MWh (still in higher-heating value). Defaults to 0.029307.

  • api2_tonne_to_mwh (float, optional) – Conversion from API2 coal to MWh. Defaults to 6.978.

  • carbon_emissions (float, optional) – The carbon content as tCO2/MWh. This value varies between coal and gas. For coal, the default factor is 0.34056. For gas, the default factor is 0.202.

  • efficiency (float, optional) – The energy efficiency. For coal, the default factor is 0.42. For gas, the default factor is 0.59.

  • carbon_tax_area (Area, str, optional) – Set an area to apply tax rules for.

  • unit (str, optional) – Convert unit of data, defaults to curves unit

Returns

An SRMC object with a timeseries object

Return type

energyquantified.data.SRMC


class energyquantified.api.UserAPI(*args, **kwargs)

User API operations.

user()

Get details about the current user.

Returns

The current user

Return type

energyquantified.user.User


class energyquantified.api.EventsAPI(ws_url, api_key)

The curve events API client.

Wraps the Energy Quantified websocket API for curve events. Handles validation, network errors, and parsing of API responses.

Parameters
  • ws_url (str) – The root URL for the events websocket API

  • api_key (str) – The API key for your user account

Basic usage:

Access these operation via an instance of the energyquantified.EnergyQuantified class:

>>> eq = EnergyQuantified(api_key="aaaa-bbbb-cccc-dddd)

Connect to the stream and subscribe to curve events:

>>> # Connect
>>> events = eq.events.connect()
>>> # Subscribe to curve events in Germany
>>> filters = CurveAttributeFilter(areas=[Area.DE])
>>> eq.events.subscribe_curve_events(filters=filters)
>>> # Loop over events as they come
>>> for event in events.get_next():
>>>     # Handle events
close()

Close the stream connection (if open) and disables automatic reconnect.

connect(last_id_file=None, timeout=15, reconnect_attempts=5)

Connect to the curve update events stream.

To keep track of the last event received in between sesssions, supply the last_id_file parameter with a file path. The file will be created for you if it does not already exist. The file will be updated at specific intervals, and when the process terminates. If the file exists and contains an ID, that ID will be stored in memory as the last received. The next time you subscribe (assuming last_id parameter is not changed from the default “keep”), the client will request all events that occured after the event with ID from file. This is useful in the case of disconnects or unexpected terminations.

>>> eq.events.connect(last_id_file="last_id_file.json")

The file can also be created inside a folder (which will be created for you if it does not already exist):

>>> eq.events.connect(
>>>     last_id_file="folder_name/last_id_file.json"
>>> )

Optionally supply the timeout parameter with an integer to change the default number of seconds to wait for a connection to be established before failing. It is not recommended to change this too low, as connecting always takes a certain amount of time at minimum.

The client tries to automatically reconnect if the connections drops. The number of reconnect attempts can be set through the reconnect_attempts parameter.

Parameters
  • last_id_file (str, optional) – A file path to a file that keeps track of the last event id received from the curve events stream

  • timeout (int, optional) – The time in seconds to wait for a connection to be established. Also used as the minimum wait-time inbetween reconnect attempts. Defaults to 15.

  • reconnect_attempts (int, optional) – The number of reconnect attempts after each disconnect. The counter is reset whenever a connection is established. Defaults to 5.

Returns

The obj instance this method was invoked upon, so the API can be used fluently

Return type

energyquantified.events.EventsAPI

disconnect()

Close the stream connection (if open) and disables automatic reconnect.

get_curve_filters(timeout=15)

Request the active curve event filters.

First make sure to connect (see eq.events.connect()):

>>> eq = EnergyQuantified(
>>>     api_key="aaaa-bbbb-cccc-dddd
>>> )
>>> eq.events.connect(last_id_file="last_id_file.json")

Request the currently active curve event filters:

>>> eq.events.get_curve_filters()
Parameters

timeout (int, optional) – The number of seconds to wait for a response, defaults to 15

Returns

A list of currently active curve event filters. Is None if not subscribed to curve events.

Return type

List[energyquantified.events.CurveNameFilter, energyquantified.events.CurveAttributeFilter], None

get_next(timeout=None)

Returns a generator over new events, and blocks while waiting for new.

Every event returned is one of the following types:

The event_type attribute is common for all events (type: EventType) and is used to check the type of an event.

CurveUpdateEvent is the model that describes change in data for a curve. ConnectionEvent describes a new event related to the connection.

>>> for event in eq.events.get_next(timeout=10):
>>>     if event.event_type == EventType.CURVE_UPDATE:
>>>         # Data in a curve is updated, let's load the new data
>>>         data = event.load_data()
>>>         continue
>>>
>>>     if event.event_type == EventType.DISCONNECTED::
>>>         # Not connected
>>>         log.error("Disconnected")
>>>         # Wait a short moment before reconnecting
>>>         time.sleep(10)
>>>         eq.events.connect()
>>>         # Subscribe
>>>         # eq.events.subscribe_curve_events(filters=[...])
>>>         # ...
>>>         continue
>>>
>>>     if event.event_type == EventType.TIMEOUT:
>>>         # Nothing happened in the last 10 (timeout param) seconds
>>>         # Use this event to act in between events during quiet times
>>>         pass
Parameters

timeout (int, optional) – The number of seconds to wait (blocking) for a new message, yielding a TimeoutEvent if no new event occurs. Waits indefinetly if timeout is None. Defaults to None.

Raises

WebSocketsError – If failed to resubscribe after automatic reconnect in the case of a disconnect

Yield

A generator of events. Blocks while waiting for a new event.

Return type

energyquantified.events.CurveUpdateEvent, energyquantified.events.ConnectionEvent, energyquantified.events.TimeoutEvent

subscribe_curve_events(filters, last_id='keep', timeout=15)

Send a filter or a list of filters to the stream, subscribing to curve events matching any of the filters.

First make sure to connect (see eq.events.connect()):

>>> eq = EnergyQuantified(
>>>     api_key="aaaa-bbbb-cccc-dddd
>>> )
>>> eq.events.connect(last_id_file="last_id_file.json")

Create a filter and subscribe:

>>> filters = [
>>>     CurveAttributeFilter(event_types="CURVE_UPDATE")
>>> ]
>>> eq.events.subscribe_curve_events(filters=filters)
Parameters
Returns

The filters and (optionally) event ID subscribed with, confirmed by the server.

Return type

energyquantified.events.CurvesSubscribeResponse

Data types

There are three main groups of data types: Time series, period-based series and OHLC data:

Time series classes

class energyquantified.data.Timeseries(data=None, scenario_names=None, **kwargs)

Bases: energyquantified.data.base.Series

A time series with metadata.

Parameters
  • curve (Curve, optional) – The curve, defaults to None

  • name (str, optional) – A name which is used as column name when converted to a pandas.DataFrame, defaults to None

  • resolution (Resolution, optional) – The resolution of the time series, defaults to None

  • instance (Instance, optional) – The instance, defaults to None

  • unit (str, optional) – The unit, defaults to None

  • denominator (str, optional) – The denominator, defaults to None

  • data (list[]) – A list of values (Value, ScenariosValue, or MeanScenariosValue)

  • scenario_names (list[str], optional) – A list of scenario names, if any

begin()

Get the begin date-time in the timeseries (inclusive).

Returns

The begin date

Return type

datetime

end()

Get the end date-time in the timeseries (exclusive).

Returns

The end date

Return type

datetime

has_data()

Check if this series has any data.

Returns

True if there is at least one data point, otherwise False

Return type

bool

has_scenarios()

Check whether or not this time series has scenarios.

Returns

True when this time series has scenarios, otherwise False

Return type

bool

instance_or_contract_dataframe_column_header()

Get the instance or contract for this time series, in a format fitting for a pandas.DataFrame column header.

Returns

An instance or contract column header for a data frame

Return type

str, NoneType

property name

Return the curve name, if a energyquantified.metadata.Curve is associated with this series.

Returns

The curve.name if it exists, otherwise None

Return type

str, NoneType

print(file=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>)

Utility method to print a time series to any file handle (defaults to stdout).

set_name(name)

Set a custom name (defaults to using curve.name).

Parameters

name (str) – An user-defined name

to_dataframe(name=None, single_level_header=False)

Convert this timeseries to a pandas.DataFrame.

Parameters
  • name (str, optional) – Set a name for the value column, defaults to value

  • single_level_header (boolean, optional) – Set to True to use single-level header in the DataFrame, defaults to False

Returns

A DataFrame

Return type

pandas.DataFrame

Raises

ImportError – When pandas is not installed on the system

to_df(name=None, single_level_header=False)

Alias for Timeseries.to_dataframe. Convert this timeseries to a pandas.DataFrame.

Parameters
  • name (str, optional) – Set a name for the value column, defaults to value

  • single_level_header (boolean, optional) – Set to True to use single-level header in the DataFrame, defaults to False

Returns

A DataFrame

Return type

pandas.DataFrame

Raises

ImportError – When pandas is not installed on the system

total_values_per_item()

Get the total number of values per item:

  • A regular time series has one value per item

  • A scenario-based time series will return number of scenarios

  • A forecast with mean and ensembles will return 1 + number of ensembles

Returns

Total number of values per date-time in this time series

Return type

int

validate()

Validate the time series.

value_type()

Return the value type of this time series.

Returns

The value type of this time series

Return type

ValueType


class energyquantified.data.TimeseriesList(iterable=(), frequency=None)

Bases: list

A list of Timeseries objects. All time series must have the same frequency.

Parameters

iterable (iterable) – Any iterable of time series

append(timeseries)

Append object to the end of the list.

clear()

Remove all items from list.

copy()

Return a shallow copy of the list.

count(value, /)

Return number of occurrences of value.

extend(iterable)

Extend list by appending elements from the iterable.

index(value, start=0, stop=9223372036854775807, /)

Return first index of value.

Raises ValueError if the value is not present.

insert(index, timeseries)

Insert object before index.

pop(index=- 1, /)

Remove and return item at index (default last).

Raises IndexError if list is empty or index is out of range.

remove(value, /)

Remove first occurrence of value.

Raises ValueError if the value is not present.

reverse()

Reverse IN PLACE.

sort(*, key=None, reverse=False)

Sort the list in ascending order and return None.

The sort is in-place (i.e. the list itself is modified) and stable (i.e. the order of two equal elements is maintained).

If a key function is given, apply it once to each list item and sort them, ascending or descending, according to their function values.

The reverse flag can be set to sort in descending order.

to_dataframe(single_level_header=False)

Convert this TimeseriesList to a pandas.DataFrame where all time series are placed in its own column and are lined up with the date-time as index.

Parameters

single_level_header (boolean, optional) – Set to True to use single-level header in the DataFrame, defaults to False

Returns

A DataFrame

Return type

pandas.DataFrame

Raises

ImportError – When pandas is not installed on the system

to_df(single_level_header=False)

Alias for Timeseries.to_dataframe.

Convert this TimeseriesList to a pandas.DataFrame where all time series are placed in its own column and are lined up with the date-time as index.

Parameters

single_level_header (boolean, optional) – Set to True to use single-level header in the DataFrame, defaults to False

Returns

A DataFrame

Return type

pandas.DataFrame

Raises

ImportError – When pandas is not installed on the system


class energyquantified.data.ValueType(value)

Enumerator of supported value types for timeseries.data[].

MEAN_AND_SCENARIOS = 'MEAN_AND_SCENARIOS'

A value and scenarios. See energyquantified.data.MeanScenariosValue.

SCENARIOS = 'SCENARIOS'

Only scenarios. See energyquantified.data.ScenariosValue.

VALUE = 'VALUE'

Single value. See energyquantified.data.Value.


class energyquantified.data.Value(date, value)

A time series value.

Implemented as a namedtuple of (date, value).

date

The date-time for a time series value (index)

value

The numeric value


class energyquantified.data.ScenariosValue(date, scenarios)

A time series value of scenarios.

Implemented as a namedtuple of (date, scenarios).

date

The date-time for a time series value (index)

scenarios

A tuple of scenario values


class energyquantified.data.MeanScenariosValue(date, value, scenarios)

A time series value with scenarios and a mean value.

Implemented as a namedtuple of (date, value, scenarios).

date

The date-time for a time series value (index)

value

The numeric value

scenarios

A tuple of scenario values

Period-based series classes

class energyquantified.data.Periodseries(data=None, **kwargs)

Bases: energyquantified.data.base.Series

A period-based series with metadata.

Parameters
  • curve (Curve, optional) – The curve, defaults to None

  • resolution (Resolution, optional) – The resolution of the time series, defaults to None

  • instance (Instance, optional) – The instance, defaults to None

  • unit (str, optional) – The unit, defaults to None

  • denominator (str, optional) – The denominator, defaults to None

  • data (list[]) – A list of periods (Period or CapacityPeriod)

begin()

Get the begin date-time in the timeseries (inclusive).

Returns

The begin date

Return type

datetime

end()

Get the end date-time in the timeseries (exclusive).

Returns

The end date

Return type

datetime

has_data()

Check if this series has any data.

Returns

True if there is at least one data point, otherwise False

Return type

bool

instance_or_contract_dataframe_column_header()

Get the instance or contract for this time series, in a format fitting for a pandas.DataFrame column header.

Returns

An instance or contract column header for a data frame

Return type

str, NoneType

property name

Return the curve name, if a energyquantified.metadata.Curve is associated with this series.

Returns

The curve.name if it exists, otherwise None

Return type

str, NoneType

print(file=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>)

Utility method to print a period-based series to any file handle (defaults to stdout).

set_name(name)

Set a custom name (defaults to using curve.name).

Parameters

name (str) – An user-defined name

to_dataframe(frequency=None, name=None, single_level_header=False, field='value')

Convert this period-based to a pandas.DataFrame as a time series in the given frequency.

Using Periodseries.to_timeseries to convert this period-based series to a regular time series first. When periods overlap the same step in the resulting time series, a weighted average is calculated down to second-precision.

Parameters
  • frequency (Frequency, required) – The frequency of the resulting pandas.DataFrame time series

  • name (str, optional) – Set a name for the column in the pandas.DataFrame, defaults to value

  • single_level_header (boolean, optional) – Set to True to use single-level header in the DataFrame, defaults to False

  • field (str, optional) – Which period attribute to use when converting to timeseries. Options: ‘value’ or ‘installed’. Defaults to ‘value’.

Returns

A DataFrame

Return type

pandas.DataFrame

Raises

ImportError – When pandas is not installed on the system

to_df(frequency=None, name=None, single_level_header=False, field='value')

Alias for Periodseries.to_dataframe.

Convert this period-based to a pandas.DataFrame as a time series in the given frequency.

Using Periodseries.to_timeseries to convert this period-based series to a regular time series first. When periods overlap the same step in the resulting time series, a weighted average is calculated down to second-precision.

Parameters
  • frequency (Frequency, required) – The frequency of the resulting pandas.DataFrame time series

  • name (str, optional) – Set a name for the column in the pandas.DataFrame, defaults to value

  • single_level_header (boolean, optional) – Set to True to use single-level header in the DataFrame, defaults to False

  • field (str, optional) – Which period attribute to use when converting to timeseries. Options: ‘value’ or ‘installed’. Defaults to ‘value’.

Returns

A DataFrame

Return type

pandas.DataFrame

Raises

ImportError – When pandas is not installed on the system

to_timeseries(frequency=None, field='value')

Convert this period-based series to a regular time series.

When periods overlap the same step in the resulting time series, a weighted average is calculated down to second-precision.

Parameters
  • frequency (Frequency, required) – The frequency of the resulting time series

  • field (str, optional) – Which period attribute to use when converting to timeseries. Options: ‘value’ or ‘installed’. Defaults to ‘value’.

Returns

A time series

Return type

Timeseries


class energyquantified.data.PeriodseriesList(iterable=())

Bases: list

A list of Periodseries objects. Have methods for converting them to a TimeseriesList or a pandas.DataFrame.

Parameters

iterable (iterable) – Any iterable of Periodseries

append(periodseries)

Append object to the end of the list.

clear()

Remove all items from list.

copy()

Return a shallow copy of the list.

count(value, /)

Return number of occurrences of value.

extend(iterable)

Extend list by appending elements from the iterable.

index(value, start=0, stop=9223372036854775807, /)

Return first index of value.

Raises ValueError if the value is not present.

insert(index, periodseries)

Insert object before index.

pop(index=- 1, /)

Remove and return item at index (default last).

Raises IndexError if list is empty or index is out of range.

remove(value, /)

Remove first occurrence of value.

Raises ValueError if the value is not present.

reverse()

Reverse IN PLACE.

sort(*, key=None, reverse=False)

Sort the list in ascending order and return None.

The sort is in-place (i.e. the list itself is modified) and stable (i.e. the order of two equal elements is maintained).

If a key function is given, apply it once to each list item and sort them, ascending or descending, according to their function values.

The reverse flag can be set to sort in descending order.

to_dataframe(frequency=None, single_level_header=False, field='value')

Convert this PeriodseriesList to a pandas.DataFrame where all time series are placed in its own column and are lined up with the date-time as index.

Parameters
  • frequency (Frequency, required) – The frequency of the resulting time series’

  • single_level_header (boolean, optional) – Set to True to use single-level header in the DataFrame, defaults to False

  • field (str, optional) – Which period attribute to use when converting to timeseries. Options: ‘value’ or ‘installed’. Defaults to ‘value’.

Returns

A DataFrame

Return type

pandas.DataFrame

Raises

ImportError – When pandas is not installed on the system

to_df(frequency=None, single_level_header=False, field='value')

Alias for Timeseries.to_dataframe.

Convert this PeriodseriesList to a pandas.DataFrame where all time series are placed in its own column and are lined up with the date-time as index.

Parameters
  • frequency (Frequency, required) – The frequency of the resulting time series’

  • single_level_header (boolean, optional) – Set to True to use single-level header in the DataFrame, defaults to False

  • field (str, optional) – Which period attribute to use when converting to timeseries. Options: ‘value’ or ‘installed’. Defaults to ‘value’.

Returns

A DataFrame

Return type

pandas.DataFrame

Raises

ImportError – When pandas is not installed on the system

to_timeseries(frequency=None, field='value')

Convert all period-based series in this list to time series.

When periods overlap the same step in the resulting time series, a weighted average is calculated down to second-precision.

Parameters
  • frequency (Frequency, required) – The frequency of the resulting time series

  • field (str, optional) – Which period attribute to use when converting to timeseries. Options: ‘value’ or ‘installed’. Defaults to ‘value’.

Returns

A list of time series

Return type

TimeseriesList


class energyquantified.data.Period(begin, end, value)

A period for a period-based series.

Implemented as a namedtuple of (begin, end, value).

begin

The begin date-time

end

The end date-time

value

The numeric value


class energyquantified.data.CapacityPeriod(begin, end, value, installed)

A period for a period-based series. Includes the installed capacity for the period (which may differ from the currently available capacity given in the value attribute).

Implemented as a namedtuple of (begin, end, value).

begin

The begin date-time

end

The end date-time

value

The numeric value

installed

The total installed capacity

Base class for series

class energyquantified.data.base.Series(curve=None, name=None, resolution=None, instance=None, contract=None, unit=None, denominator=None)

Bases: object

Base class for Timeseries and Periodseries.

begin()

Get the begin date-time in the timeseries (inclusive).

Returns

The begin date

Return type

datetime

contract

The contract for OHLC operations resulting in a time series

curve

The curve

data

The data

denominator

The denominator of the data

end()

Get the end date-time in the timeseries (exclusive).

Returns

The end date

Return type

datetime

has_data()

Check if this series has any data.

Returns

True if there is at least one data point, otherwise False

Return type

bool

instance

The instance (if any)

instance_or_contract_dataframe_column_header()

Get the instance or contract for this time series, in a format fitting for a pandas.DataFrame column header.

Returns

An instance or contract column header for a data frame

Return type

str, NoneType

property name

Return the curve name, if a energyquantified.metadata.Curve is associated with this series.

Returns

The curve.name if it exists, otherwise None

Return type

str, NoneType

resolution

The resolution

set_name(name)

Set a custom name (defaults to using curve.name).

Parameters

name (str) – An user-defined name

unit

The unit of the data

OHLC data classes

class energyquantified.data.Product(traded: datetime.date, period: energyquantified.metadata.ohlc.ContractPeriod, front: int, delivery: datetime.date)

An energy product description with a trading date and the contract in detail.


class energyquantified.data.OHLC(product: energyquantified.data.ohlc.Product, open: float, high: float, low: float, close: float, settlement: float, volume: float, open_interest: float)

A summary for a trading day on a contract.

get_field(field)

Get an OHLC field from this object.

Parameters

field (OHLCField | str) – A OHLC field

Raises

ValueError – When the field parameter isn’t a valid OHLC field

Returns

The value on the given OHLC field or None if it isn’t set

Return type

float


class energyquantified.data.OHLCList(elements, curve=None, contract=None, unit=None, denominator=None)

Bases: list

A collection of OHLC data. Can contain all sorts of contracts (yearly, monthly, weekly etc.) for a specific market.

append(value)

Append object to the end of the list.

clear()

Remove all items from list.

curve

The curve holding these OHLC objects

denominator

The denominator of the data

extend(iterable)

Extend list by appending elements from the iterable.

insert(index, value)

Insert object before index.

pop(index=- 1)

Remove and return item at index (default last).

Raises IndexError if list is empty or index is out of range.

remove(value)

Remove first occurrence of value.

Raises ValueError if the value is not present.

to_dataframe()

Convert this OHLCList to a pandas.DataFrame with a column for open, high, low, close, settlement, volume and open interest.

Returns

A DataFrame

Return type

pandas.DataFrame

Raises

ImportError – When pandas is not installed on the system

to_df()

Convert this OHLCList to a pandas.DataFrame with a column for open, high, low, close, settlement, volume and open interest.

Returns

A DataFrame

Return type

pandas.DataFrame

Raises

ImportError – When pandas is not installed on the system

unit

The unit of the data

SRMC data classes

class energyquantified.data.SRMC(curve: energyquantified.metadata.curve.Curve = None, unit: str = None, denominator: str = None, contract: Union[energyquantified.metadata.ohlc.ContinuousContract, energyquantified.metadata.ohlc.SpecificContract] = None, options: energyquantified.data.srmc.SRMCOptions = None, ohlc: energyquantified.data.ohlc.OHLCList = None, timeseries: energyquantified.data.timeseries.Timeseries = None, periodseries: energyquantified.data.periodseries.Periodseries = None)

Bases: object

A data class for the API response from an SRMC calculation. It can either contain a list of OHLC objects, a time series, or a period-based series.

contract: Union[energyquantified.metadata.ohlc.ContinuousContract, energyquantified.metadata.ohlc.SpecificContract] = None

(optional) The contract when the calculation was done for historical closing prices – either a front contract (continuous front contract), or a specific contract such as Year-2020, Year-2021, Q3-2020 etc.

curve: energyquantified.metadata.curve.Curve = None

The curve used as input to this SRMC calculation

denominator: str = None

The denominator of the data

has_ohlc()

Check whether this SRMC calculation did return OHLC objects.

Returns

True when this SRMC calculation did return OHLC objects, otherwise False

Return type

bool

has_periodseries()

Check whether this SRMC calculation did return a period-based series.

Returns

True when this SRMC calculation did return a period-based series, otherwise False

Return type

bool

has_timeseries()

Check whether this SRMC calculation did return a time series.

Returns

True when this SRMC calculation did return a time series, otherwise False

Return type

bool

ohlc: energyquantified.data.ohlc.OHLCList = None

(optional) The OHLC data when the result of the calculation returns a list of OHLC objects.

options: energyquantified.data.srmc.SRMCOptions = None

The factors used in the SRMC calculation.

periodseries: energyquantified.data.periodseries.Periodseries = None

(optional) The period-based series when the result of the calculation returns a period series.

timeseries: energyquantified.data.timeseries.Timeseries = None

(optional) The time series when the result of the calculation returns a time series.

unit: str = None

The unit of the data


class energyquantified.data.SRMCOptions(fuel_type: str = None, api2_tonne_to_mwh: float = None, gas_therm_to_mwh: float = None, efficiency: float = None, carbon_emissions: float = None, carbon_tax_area: energyquantified.metadata.area.Area = None)

A data class with all factors for an SRMC calculations.

api2_tonne_to_mwh: float = None

(For coal) Conversion factor between API#2 tonnes and megawatthours.

carbon_emissions: float = None

The carbon emission factor.

carbon_tax_area: energyquantified.metadata.area.Area = None

(optional) When set, carbon tax is calculated according to tax rules in given area. Typically used for Great Britain’s flat carbon tax.

efficiency: float = None

The energy efficiency factor.

fuel_type: str = None

The fuel type. Set to either COAL or GAS.

gas_therm_to_mwh: float = None

(For gas) Conversion from pence/therm to GBP/MWh.

Absolute forecast data classes

class energyquantified.data.AbsoluteResult(curve, resolution, delivery, filters, aggregation, unit, items)

Bases: object

aggregation

The aggregation method used (only relevant if frequency of the delivery is lower than the Curve’s frequency), see energyquantified.metadata.Aggregation

begin()

Begin of the delivery (inclusive).

Returns

The delivery datetime

Return type

datetime.datetime

curve

The curve, see energyquantified.metadata.Curve

delivery

The delivery (point in time to load values for)

end()

End of the delivery

Returns

End of delivery (exclusive)

Return type

datetime.datetime

filters

The filter used when aggregating values (only relevant if frequency of the delivery is lower than the Curve’s frequency), see energyquantified.metadata.Filter

frequency()

Get the delivery frequency (resolution.frequency).

Returns

The delivery frequency

Return type

Frequency

is_empty()

Check if the result contains any AbsoluteItem’s.

Returns

True if empty, otherwise False

Return type

bool

items

List of energyquantified.data.AbsoluteItem (instance and value pairs)

resolution

Resolution of the delivery, see energyquantified.time.Resolution

size()

The number of elements in AbsoluteResult.items

Returns

The number of elements in the result

Return type

int

unit

The unit of the result

zone()

Get the delivery zone (resolution.timezone).

Returns

Timezone of the delivery

Return type

datetime.tzinfo


class energyquantified.data.AbsoluteItem(instance: energyquantified.metadata.instance.Instance, value: float)

Data class for an instance-value pair used by energyquantified.data.AbsoluteResult.

instance: energyquantified.metadata.instance.Instance

The instance, see energyquantified.metadata.Instance

value: float

The value

Metadata

class energyquantified.metadata.Allocation(value)

Enumerator of border allocation types between two price areas.

EXPLICIT = ('E', 'Explicit')

Explicit exchange border

FLOW_BASED = ('F', 'Flow-based')

Flow-based exchange border

IMPLICIT = ('I', 'Implicit')

Implicit exchange border

NO_COMMERCIAL_CAPACITY = ('N', 'No commercial capacity')

No commercial exchange available


class energyquantified.metadata.Area(tag, name, short_tag=None, country=False, price_area=False, control_area=False, external=False)

A representation of a price area or country.

Areas do have a reference to all exchange borders with available commercial capacity allocation properties. Access the borders via area.borders[]. If you just want direct access neighbour listing, use area.exchange_neighbours[].

Some areas, such as Nord Pool, consist of smaller areas. In these cases, you can access their children via area.children[]. You can also find the parent area via area.parent.

All areas has a tag, which you will find in the curve names, and a full name.

classmethod all()

Return a list of all areas.

Returns

A list of all areas

Return type

list[Area]

borders

Set of exchange borders with exchange allocation types

classmethod by_tag(tag)

Look up area by tag.

Parameters

tag (str) – An area tag

Returns

The area for the given tag

Return type

Area

classmethod by_tags(*tags)

Return multiple areas by tags.

Returns

A list of areas by the provided tags

Return type

list[Area]

children

Set of child areas (set if this area is split into other, smaller areas)

control_area

True when this area is a control area/TSO area, otherwise False

country

True when this area is a country, otherwise False

exchange_neighbours

Set of neighbouring areas

external

True when this area is outside of the supported region (used for exchange areas)

get_family()

Get all descendants in a flat list for this Area.

Returns

A list of all descendants/sub-areas for this area

Return type

list[Area]

classmethod is_valid_tag(tag)

Check whether an area tag exists or not.

Parameters

tag (str) – An area tag

Returns

True if it exists, otherwise False

Return type

bool

name

The full name of the area

parent

The parent area (set if this is a sub-area of another area)

price_area

True when this area is a price area, otherwise False

short_tag

The short tag (used for context-aware tags in Javascript/corejs)

tag

The area tag (used in curve names)


class energyquantified.metadata.Border(source, sink, allocations=None)

A one-way border between two price areas.

The source area is where the power is exported from, and the sink area is where to power is imported to.

Each border has a list of capacity allocations describing how the commercial capacities on the border are set.

__eq__(other)

Return self==value.

__hash__()

Return hash(self).

allocations

A tuple of the exchange allocation types (flow-based, implicit, etc.)

as_tuple()

Convert this border to a tuple of (source, sink, allocations)

Returns

This border as a tuple of (source, sink, allocations)

Return type

tuple

is_explicit()

Returns True if this border has explicit allocations.

Returns

True if this border has explicit allocations, otherwise False

Return type

bool

is_flow_based()

Returns True if this border is flow-based.

Returns

True if this border is flow-based, otherwise False

Return type

bool

is_implicit()

Returns True if this border has implicit allocations.

Returns

True if this border has implicit allocations, otherwise False

Return type

bool

sink

The sink area (the importer)

source

The source area (the exporter)


class energyquantified.metadata.Curve(name, curve_type=None, instance_issued_timezone=None, area=None, area_sink=None, place=None, resolution=None, frequency=None, timezone=None, categories=None, unit=None, denominator=None, data_type=None, source=None, commodity=None, subscription=None)

The curve identifies any type of time series data and OHLC data.

The curve.name is used in the API when loading data for a curve.

area

The area

area_sink

The importing area for exchange curves

area_source

The exporting area for exchange curves

categories

List of categories for this curve.

commodity

The curve commodity (Power, Gas, etc.)

curve_type

Curve type (the type of data this curve refers to).

data_type

The data type, DataType.

denominator

The denominator (for EUR/MWh: unit=EUR and denominator=MWh). See also Curve.unit.

frequency

The frequency of data in this curve

instance_issued_timezone

For instance-based curves: The timezone of the issue date in the instance, see Instance.issued.

name

The curve name is the identifier.

property resolution

The resolution (combination of frequency and timezone) for this curve.

source

The source of the data.

subscription

The subscription for this curve, see Subscription.

timezone

The timezone of date-times in this curve

unit

The unit (MW, EUR, etc.). See also Curve.denominator.


class energyquantified.metadata.CurveType(value)

Curve type is not a part of the curve name.

Curve type describes the storage format of the underlying data and which operations must be used to fetch data for these curves.

  • Load time series and scenario-based time series using the EnergyQuantified.timeseries.* operations.

  • To load instances (i.e. forecasts), use the EnergyQuantified.timeseries.* operations.

  • Periods and period-instances can be loaded by using each of their respective operations located under EnergyQuantified.periods.* and EnergyQuantified.instance_periods.*.

  • OHLC means “open, high, low and close” data. To load data from these curves, use the OHLC operations.

INSTANCE = ('INSTANCE', True)

Instances (forecasts)

INSTANCE_PERIOD = ('INSTANCE_PERIOD', True)

Instances of period-based data

OHLC = ('OHLC', False)

Closing prices for market data

PERIOD = ('PERIOD', False)

Period-based data

SCENARIO_TIMESERIES = ('SCENARIO_TIMESERIES', False)

Plain, fixed-interval scenarios of time series data

TIMESERIES = ('TIMESERIES', False)

Plain, fixed-interval time series data

static by_tag(tag)

Look up curve type by tag.

Parameters

tag (str) – A curve type tag

Returns

The curve type for the given tag

Return type

CurveType

static is_valid_tag(tag)

Check whether a curve type tag exists or not.

Parameters

tag (str) – A curve type tag

Returns

True if it exists, otherwise False

Return type

bool


class energyquantified.metadata.DataType(value)

Data types describe the type of data (i.e. actuals, forecast). This is the attribute that is always set as the last word in the curve name.

ACTUAL = ('ACTUAL', 'Actual')

Third-party actuals collected by Energy Quantified, but not modified.

BACKCAST = ('BACKCAST', 'Backcast')

The forecast models run backwards.

CAPACITY = ('CAPACITY', 'Capacity')

Total installed capacity.

CLIMATE = ('CLIMATE', 'Climate')

Scenario data generated by Energy Quantified, which is based on climate data sets (synthetic weather years).

FORECAST = ('FORECAST', 'Forecast')

Forecasts generated by Energy Quantified unless another source is explicitly stated in the curve name.

FOREX = ('FOREX', 'Forex')

Currency rates.

NORMAL = ('NORMAL', 'Normal')

The seasonal normals using 40 weather years.

OHLC = ('OHLC', 'OHLC')

Closing data from the market.

REMIT = ('REMIT', 'REMIT')

Capacity data generated from REMIT outage messages.

SCENARIO = ('SCENARIO', 'Scenario')

Scenario data generated by Energy Quantified. If you are looking for weather-based scenarios, look at DataType.CLIMATE.

SYNTHETIC = ('SYNTHETIC', 'Synthetic')

A combination of third-party actuals and numbers generated by Energy Quantified, where we have filled missing with our best calculations.

VALUE = ('VALUE', 'Value')

Some model value (such as a factor).

static by_tag(tag)

Look up data type by tag.

Parameters

tag (str) – A data type tag

Returns

The data type for the given tag

Return type

DataType

static is_valid_tag(tag)

Check whether a data type tag exists or not.

Parameters

tag (str) – A data type tag

Returns

True if it exists, otherwise False

Return type

bool


class energyquantified.metadata.Instance(issued, tag='', scenarios=None, created=None, modified=None)

An instance identifies a forecast or any other time series that was issued at a specific time.

It is typically used to specify a weather forecast that a specific forecast is based on.

An instance is identified by the combination of (issued, tag).

as_dataframe_column_header()

Create a string fitting for a column header in the a pandas.DataFrame.

Returns

A DataFrame column header text for an instance

Return type

str

created

When this instance was created (if available)

issued

The issue date of this instance

modified

When this instance was modified (if available)

scenarios

The number of scenarios available in this instance (default=0)

tag

The tag for this instance


class energyquantified.metadata.Place(kind, key, name, unit=None, fuels=None, areas=None, location=None, children=None, curves=None)

A place is a general concept of a physical location, such as a powerplant, a weather station, a position on a river etc.

areas

The list areas in which this place lies (multiple when it’s on a border), see Area.

children

A list of children (typically used for a power plants with subunits)

curves

A list of curves with data for this place. See Curve.

fuels

The fuel types (if it is a power plant unit)

key

The identifier

kind

The place type. See PlaceType.

property latitude

The latitude of this place.

location

The geolocation of this place: (latitude, longitude)

property longitude

The longitude of this place.

name

The name of the place

unit

The unit name (if it is a power plant unit)


class energyquantified.metadata.PlaceType(value)

Enumerator of place types. Used to describe type type of a Place.

CITY = ('city',)

A city

CONSUMER = ('consumer',)

A power consumer, such as a factory

GAS_INTERCONNECTOR = ('gas-interconnector',)

Gas interconnector

GAS_LNG_TERMINAL = ('gas-lng-terminal',)

Gas LNG terminal

GAS_STORAGE = ('gas-storage',)

Gas storage

OTHER = ('other',)

Unspecified

PRODUCER = ('producer',)

A power producer (power plant)

RIVER = ('river',)

A river location

WEATHERSTATION = ('weatherstation',)

A weather station

static by_tag(tag)

Look up place type by tag.

Parameters

tag (str) – A place type tag

Returns

The place type for the given tag

Return type

PlaceType

static is_valid_tag(tag)

Check whether a place type tag exists or not.

Parameters

tag (str) – A place type tag

Returns

True if it exists, otherwise False

Return type

bool


class energyquantified.metadata.Aggregation(value)

Supported aggregations in the API. Includes simple implementations of the different aggregation types for learning purposes.

AVERAGE = (<function Aggregation.<lambda>>,)

Calculate the mean value

MAX = (<built-in function max>,)

Find the maximum value

MEAN = (<function Aggregation.<lambda>>,)

Calculate the mean value (same as AVERAGE)

MIN = (<built-in function min>,)

Find the minimum value

SUM = (<built-in function sum>,)

Calculate the sum of all values

aggregate(iterable)

Perform an aggregation on any iterable of numbers (such as lists, tuples, generators etc.).

Parameters

iterable (iterable) – Any iterable of numbers

Returns

An aggregate

Return type

float

static by_tag(tag)

Look up aggregation by tag.

Parameters

tag (str) – An aggregation tag

Returns

The aggregation for the given tag

Return type

Aggregation

Raises

KeyError – if no Aggregation exists for this tag

static is_valid_tag(tag)

Check whether an aggregation tag exists or not.

Parameters

tag (str) – An aggregation tag

Returns

True if it exists, otherwise False

Return type

bool

property tag

Get the tag for this aggregation type.

Returns

The aggregation tag (name)

Return type

str


class energyquantified.metadata.Filter(value)

Supported filters in the API.

Includes simple implementations of the filters for learning purposes.

Note: The API automatically separates futures peak and offpeak by looking at the selected frequency for aggregations:

  • For weekly, monthly, quartly and yearly frequency, the futures peak and offpeak are used.

  • For daily or higher frequencies, the standard peak and offpeak are used.

BASE = (<function Filter.<lambda>>, <function Filter.<lambda>>)

All hours

OFFPEAK = (<function Filter.<lambda>>, <function Filter.<lambda>>)

Offpeak hours

PEAK = (<function Filter.<lambda>>, <function Filter.<lambda>>)

Peak hours

WEEKEND = (<function Filter.<lambda>>, <function Filter.<lambda>>)

Saturday and Sunday

WORKDAYS = (<function Filter.<lambda>>, <function Filter.<lambda>>)

Monday–Friday

static by_tag(tag)

Look up a filter by tag.

Parameters

tag (str) – A filter tag

Returns

The filter for the given tag

Return type

Filter

get_filter_function(frequency)

Given a frequency, return the appropriate filter function:

  • For weekly, monthly, quartly and yearly frequency, the futures peak and offpeak function is used.

  • For daily or higher frequencies, the standard peak and offpeak function is used.

Parameters

frequency (Frequency) – The resulting frequency of an aggregation

Returns

A filter function

Return type

function

is_in_filter(datetime_obj)

Check whether or not a datetime object is in a filter.

Parameters

datetime_obj (datetime) – A date-time

Returns

True if the date-time object falls into filter, otherwise False

Return type

bool

is_in_future_filter(datetime_obj)

Check whether or not a datetime object is in a filter for futures-contracts (weekly, monthly, quarterly, yearly).

Parameters

datetime_obj (datetime) – A date-time

Returns

True if the date-time object falls into filter, otherwise False

Return type

bool

static is_valid_tag(tag)

Check whether a filter tag exists or not.

Parameters

tag (str) – A filter tag

Returns

True if it exists, otherwise False

Return type

bool

property tag

The filter tag (name)


class energyquantified.metadata.ContractPeriod(value)

Enumerator of contract periods available in for OHLC contracts in the API. The contract periods are:

  • YEAR – Yearly contract period

  • MDEC – December delivery (for ETS EUA contracts)

  • SEASON – Summer or Winter (typically for gas contracts)

  • QUARTER – Quarterly contract period

  • MONTH – Monthly contract period

  • WEEK – Weekly contract period

  • WEEKEND – Weekend contract period

  • DAY – Daily contract period

static by_tag(tag)

Look up contract periods by tag.

Parameters

tag (str) – The tag to look up

Returns

A ContractPeriod for this tag

Return type

ContractPeriod

static is_valid_tag(tag)

Check whether a contract period tag exists or not.

Parameters

tag (str) – The tag to look up

Returns

True if the contract period tag exists, otherwise False

Return type

bool


class energyquantified.metadata.OHLCField(value)

A field in an OHLC object. Used to specify which field to load or to perform an operation on.

  • OPEN – Opening trade for the trading day

  • HIGH – Highest trade for the trading day

  • LOW – Lowest trade for the trading day

  • CLOSE – Closing trade for the trading day

  • SETTLEMENT – Settlement price for the trading day

  • VOLUME – Accumulated traded volume for the trading day

  • OPEN_INTEREST – Total volume of contracts that have been entered into and not yet liquidated by an offsetting transaction or fulfilled by delivery

static by_tag(tag)

Look up OHLC field by tag.

Parameters

tag (str) – The tag to look up

Returns

An OHLCField for this tag

Return type

OHLCField

get_value(ohlc)

Get the value from an OHLC object for this field.

Parameters

ohlc (OHLC) – An OHLC object

Returns

The value for that given OHLC field

Return type

float

static is_valid_tag(tag)

Check whether a OHLC field tag exists or not.

Parameters

tag (str) – The tag to look up

Returns

True if the OHLC field tag exists, otherwise False

Return type

bool


class energyquantified.metadata.ContinuousContract(period: energyquantified.metadata.ohlc.ContractPeriod, front: int, field: energyquantified.metadata.ohlc.OHLCField = None)

Metadata class for keeping track of which contract was queried. Continuous contracts are the rolling N-front contract – relative to its trading day.

For instance, a contract with period=MONTH, front=1 is what you would typically call a front month contract. period=MONTH, front=2 is the second closest front contract, and so forth.

See also SpecificContract.

field

The field to have fetched from the OHLC objects (such as close, settlement, open, high, low, volume)

period

The contract period (i.e. week, month, quarter)

front

The front number (1 is the closest contract, 2 is the second closest, and so on)

as_dataframe_column_header()

Create a string fitting for a column header in the a pandas.DataFrame.

Returns

A DataFrame column header text for this contract

Return type

str

is_continuous()

Check whether this contract instance is continuous.

Returns

True if continuous, otherwise False

Return type

bool

is_specific()

Check whether this contract instance is specific.

Returns

True if specific, otherwise False

Return type

bool


class energyquantified.metadata.SpecificContract(period: energyquantified.metadata.ohlc.ContractPeriod, delivery: datetime.date, field: energyquantified.metadata.ohlc.OHLCField = None)

Metadata class for keeping track of which contract was queried. Specific contracts are contracts which goes to delivery on a specific date.

For instance, a contract with period=MONTH, delivery=2020-12-01 is the contract for delivery in December 2020.

See also ContinuousContract.

field

The field to have fetched from the OHLC objects (such as close, settlement, open, high, low, volume)

period

The contract period (i.e. week, month, quarter)

delivery

The delivery date of the contract

as_dataframe_column_header()

Create a string fitting for a column header in the a pandas.DataFrame.

Returns

A DataFrame column header text for this contract

Return type

str

is_continuous()

Check whether this contract instance is continuous.

Returns

True if continuous, otherwise False

Return type

bool

is_specific()

Check whether this contract instance is specific.

Returns

True if specific, otherwise False

Return type

bool


class energyquantified.metadata.Subscription(access, subscription_type, label, package=None, area=None, collection=None, collection_perms=None)

A subscription describing the access to a curve

collection_perms

SubscriptionCollectionPerm

label

Human-readable label for this subscription

type

The type of subscription, see SubscriptionType


class energyquantified.metadata.SubscriptionAccess(value)

Access levels for a subscription.

BLOCKED = 'BLOCKED'

No access

FREE = 'FREE'

Access is available at no cost

FREEMIUM = 'FREEMIUM'

Your access is freemium

INTERNAL = 'INTERNAL'

Access is provided through partner agreements

NONE = 'NONE'

Missing access information

PAYING = 'PAYING'

Access is provided through a paid subscription

REALTO = 'REALTO'

Access is provided with a www.realto.io subscription

TRIAL = 'TRIAL'

Access is granted as a trial

static by_tag(tag)

Look up access by tag.

Parameters

tag (str) – An access tag

Returns

The access for the given tag

Return type

SubscriptionAccess

static is_valid_tag(tag)

Check whether an access tag exists or not.

Parameters

tag (str) – An access tag

Returns

True if it exists, otherwise False

Return type

bool


class energyquantified.metadata.SubscriptionType(value)

The type of subscription.

COLLECTION = 'COLLECTION'

A subscription related to collections

FREE = 'FREE'

No subscription required for provided content

FREEMIUM = 'FREEMIUM'

Limited access due to no subscription defined for provided content

PACKAGE = 'PACKAGE'

A subscription associated with a package of services

PACKAGE_AREA = 'PACKAGE_AREA'

A subscription tied to a combination of a specific package and area

PRIVATE = 'PRIVATE'

A private subscription with restricted access

static by_tag(tag)

Look up subscription type by tag.

Parameters

tag (str) – A subscription type tag

Returns

The subscription type for the given tag

Return type

SubscriptionType

static is_valid_tag(tag)

Check whether a subscription type tag exists or not.

Parameters

tag (str) – A subscription type tag

Returns

True if it exists, otherwise False

Return type

bool


class energyquantified.metadata.SubscriptionCollectionPerm(value)

The user’s permissions for a collection.

R = 'r'

Read-only access

RW = 'rw'

Read-write access

static by_tag(tag)

Look up collection permission by tag.

Parameters

tag (str) – A collection permission tag

Returns

The collection permission for the given tag

Return type

SubscriptionCollectionPerm

static is_valid_tag(tag)

Check whether a collection permission tag exists or not.

Parameters

tag (str) – A collection permission tag

Returns

True if it exists, otherwise False

Return type

bool

User

class energyquantified.user.User(name, email, organization, subscriptions)

User details.

email

The email of the user, str

name

The name of the user, str

organization

The organization of the user, see Organization

subscriptions

The subscriptions of the user, see Subscription


class energyquantified.user.Organization(name, account_manager)

Organization details.

account_manager

The account manager of the organization

name

The name of the organization


class energyquantified.user.AccountManager(name, email)

Account manager details.

Events

class energyquantified.events.EventType(value)

A field in event objects, describing the type of event.

  • CURVE_UPDATE – Data for a curve is created or modified

  • CURVE_DELETE – Some data for a curve is deleted

  • CURVE_TRUNCATE – All data for a curve is deleted

  • DISCONNECTED – Disconnected from the stream

  • TIMEOUT – Timeout

Check if an EventType object is for curve-, connection- or timeout events:

>>> from energyquantified.events import EventType
>>> EventType.CURVE_UPDATE.is_curve_type()
>>> > True
>>> EventType.CURVE_UPDATE.is_connection_type()
>>> > False
>>> EventType.CURVE_UPDATE.is_timeout_type()
>>> > False
static by_tag(tag)

Look up an EventType by tag.

Parameters

tag (str) – The tag to look up (case-insensitive)

Returns

The EventType for this tag

Return type

EventType

Raises

KeyError – if no EventType exists for this tag

is_connection_type()

Check if this event type is for connection events.

Returns

True if this event type is used by connection events, otherwise False.

Return type

bool

is_curve_type()

Check if this event type is for curve events.

Returns

True if this event type is used for curve events, otherwise False.

Return type

bool

is_timeout_type()

Check if this event type is for timeout events.

Returns

True if this event type is used by timeout events, otherwise False.

Return type

bool

static is_valid_tag(tag)

Check whether an EventType tag exists or not.

Parameters

tag (str) – The tag to look up (case-insensitive)

Returns

True if the EventType tag exists, otherwise False

Return type

bool


class energyquantified.events.CurveUpdateEvent(event_id, curve, event_type, begin=None, end=None, instance=None, num_values=None)

Describes change in data for a energyquantified.metadata.Curve, which may also be related to an energyquantified.metadata.Instance.

begin

The begin date (inclusive)

curve

See energyquantified.metadata.Curve. The curve with modified data.

end

The end date (exclusive)

event_id

The unique identifier for this event

event_type

See energyquantified.events.EventType. Is one of CURVE_UPDATE, CURVE_DELETE or CURVE_TRUNCATE.

instance

See energyquantified.metadata.Instance. The instace with modified data. Only provided where applicable.

load_data(eq)

Load data in the range described by the event. Returns ‘None’ if the event type is either EventType.CURVE_TRUNCATE or EventType.CURVE_DELETE.

Parameters

eq (energyquantified.EnergyQuantified) – Instance of the api client

Returns

The range of data the event describes

Return type

energyquantified.data.TimeSeries, energyquantified.data.Periodseries, energyquantified.data.OHLCList

Raises
  • ValueError – Invalid object

  • APIError – If there were any network- or server-related issues while loading the data

num_values

The number of affected values


class energyquantified.events.ConnectionEvent(event_type, status=None, status_code=None, message=None)

Model for describing events related to push feed connection.

event_type

See energyquantified.events.EventType. Is always DISCONNECTED for connection events.

message

Error message

status

Status name

status_code

Status code number


class energyquantified.events.TimeoutEvent

Filler event used to indicate that a certain time has passed without any new events.

event_type

See energyquantified.events.EventType. Is always TIMEOUT for timeout events.


class energyquantified.events.CurveNameFilter(begin=None, end=None, event_types=None, curves=None)

In addition to the inherited filters (begin, end, event_type), this option provides filtering on curves.

Parameters
  • begin (date, datetime, str, optional) – The begin date (inclusive). Ignored if None, defaults to None.

  • end (date, datetime, str, optional) – The end date (exclusive). Ignored if None, defaults to None.

  • event_types (EventType, str, list[EventType, str], optional) – The event types to filter. Ignored if None, defaults to None.

  • curves (Curve, str, list[Curve, str], optional) – Filter by curves. Ignored if None, defaults to None.

set_begin(begin)

Set the filters ‘begin’. The begin/end range regards the data an event describes, not to be confused with created time of the event.

Parameters

begin (str, date, datetime) – Start of range

Raises

ValueError – Invalid arg type

Returns

The instance this method was invoked upon

Return type

energyquantified.events.CurveNameFilter, energyquantified.events.CurveAttributeFilter

set_curves(curves)

Set one or more curves in this filter. Limit the events to events with a curve matching one of the curves.

Parameters

curves (Curve, str, list[Curve, str]) – Filter events by curves

Raises
  • ValueError – Curve missing name attr

  • ValueError – Invalid arg type

Returns

The instance this method was invoked upon

Return type

energyquantified.events.CurveNameFilter

set_end(end)

Set the filters ‘end’. The begin/end range regards the data an event describes, not to be confused with the created time of the event.

Parameters

end (str, date, datetime) – End of range

Raises

ValueError – Invalid arg type

Returns

The instance this method was invoked upon

Return type

energyquantified.events.CurveNameFilter, energyquantified.events.CurveAttributeFilter

set_event_types(event_types)

Set one or more EventTypes in this filter, excluding events not matching at least one. The EventTypes must be curve type (check with .is_curve_type()).

Parameters

event_types (EventType, str, list[EventType, str]) – EventTypes (or tags) to include

Raises
  • ValueError – Invalid arg type

  • ValueError – Invalid event tag

Returns

The instance this method was invoked upon

Return type

energyquantified.events.CurveNameFilter, energyquantified.events.CurveAttributeFilter

to_dict(include_not_set=False)

Represent this object as a dictionary, optionally excluding None-values.

Parameters

include_not_set (bool, optional) – If variables that are not set should be included in the dictionary. Defaults to False.

Returns

A dictionary representation of this object

Return type

dict

to_json()

Represent the output of to_dict as json.

validate()

Check the validity of this filter and discover reasons if invalid.

Returns

A tuple of two objects; (1) a bool representing the validity of the object and (2) a list of potential errors.

Return type

tuple[bool, list[str]]


class energyquantified.events.CurveAttributeFilter(begin=None, end=None, event_types=None, areas=None, data_types=None, commodities=None, categories=None, exact_categories=None)

In addition to the inherited filters (begin, end, event_type), this option provides filtering on curves attributes.

Parameters
  • begin (date, datetime, str, optional) – The begin date (inclusive). Ignored if None, defaults to None.

  • end (date, datetime, str, optional) – The end date (exclusive). Ignored if None, defaults to None.

  • event_types (EventType, str, list[EventType, str], optional) – The event types to filter. Ignored if None, defaults to None.

  • areas (Area, str, list[Area, str], optional) – Filter curves by area. Ignored if None, defaults to None.

  • data_types (DataType, str, list[DataType, str], optional) – Filter curves by data types. Ignored if None, defaults to None.

  • commodities (str, list[str], optional) – Commodities (e.g., “Gas”). Ignored if None, defaults to None.

  • categories (str, list[str], optional) – Categories (e.g., “Power”). Ignored if None, defaults to None.

  • exact_categories (str, list[str], optional) – An exact category is a combination of categories (e.g., “Wind Power”). The order matter. Ignored if None, defaults to None.

set_areas(areas)

Set one or more areas in this filter. Limit events to events having a curve with a matching Area.

Parameters

areas (Area, str, list[Area, str]) – The areas or area tags to receive events

Raises
  • ValueError – Invalid arg type

  • ValueError – Tag is not a valid Area tag

Returns

The instance this method was invoked upon

Return type

energyquantified.events.CurveAttributeFilter

set_begin(begin)

Set the filters ‘begin’. The begin/end range regards the data an event describes, not to be confused with created time of the event.

Parameters

begin (str, date, datetime) – Start of range

Raises

ValueError – Invalid arg type

Returns

The instance this method was invoked upon

Return type

energyquantified.events.CurveNameFilter, energyquantified.events.CurveAttributeFilter

set_categories(categories)

Set one or more categories. Limits events to those having a curve with at least one matching category.

Parameters

categories (str, list[str]) – The categories to include

Raises

ValueError – Invalid arg type

Returns

The instance this method was invoked upon

Return type

energyquantified.events.CurveAttributeFilter

set_commodities(commodities)

Set one or more commodities in this filter. Limit events to those having a curve with a matching commodity.

Parameters

commodities (str, list[str]) – The commidities to filter for

Raises

ValueError – Invalid arg type

Returns

The instance this method was invoked upon

Return type

energyquantified.events.CurveAttributeFilter

set_data_types(data_types)

Set one or more DataTypes. Limit events to events having a curve with a matching DataType.

Parameters

data_types (DataType, str, list[DataType, str]) – The DataTypes (optionally by tag) to receive events for

Raises
  • ValueError – Invalid arg type

  • ValueError – Tag is not a valid DataType tag

Returns

The instance this method was invoked upon

Return type

energyquantified.events.CurveAttributeFilter

set_end(end)

Set the filters ‘end’. The begin/end range regards the data an event describes, not to be confused with the created time of the event.

Parameters

end (str, date, datetime) – End of range

Raises

ValueError – Invalid arg type

Returns

The instance this method was invoked upon

Return type

energyquantified.events.CurveNameFilter, energyquantified.events.CurveAttributeFilter

set_event_types(event_types)

Set one or more EventTypes in this filter, excluding events not matching at least one. The EventTypes must be curve type (check with .is_curve_type()).

Parameters

event_types (EventType, str, list[EventType, str]) – EventTypes (or tags) to include

Raises
  • ValueError – Invalid arg type

  • ValueError – Invalid event tag

Returns

The instance this method was invoked upon

Return type

energyquantified.events.CurveNameFilter, energyquantified.events.CurveAttributeFilter

set_exact_categories(exact_categories)

Set one or more exact categories. Limits events to those with a curve matching at least one of the exact_categories. An exact category should be one or more categories in a single str, separated by space.

Parameters

exact_categories (str, list[str]) – The exact categories to include

Raises

ValueError – Invalid arg type

Returns

The instance this method was invoked upon

Return type

CurveAttributeFilter

to_dict(include_not_set=False)

Represent this object as a dictionary, optionally excluding None-values.

Parameters

include_not_set (bool, optional) – If variables that are not set should be included in the dictionary. Defaults to False.

Returns

A dictionary representation of this object

Return type

dict

to_json()

Represent the output of to_dict as json.

validate()

Check the validity of this filter and discover reasons if invalid.

Returns

A tuple of two objects; (1) a bool representing the validity of the object and (2) a list of potential errors.

Return type

tuple[bool, list[str]]


class energyquantified.events.CurvesSubscribeResponse(filters: List[Union[energyquantified.events.event_options.CurveAttributeFilter, energyquantified.events.event_options.CurveNameFilter]], last_id: Optional[str] = None)

Bases: object

Response model from successfully subscribing to curve events.

filters: List[Union[energyquantified.events.event_options.CurveAttributeFilter, energyquantified.events.event_options.CurveNameFilter]]

A list of filters subscribed to, confirmed by the server.

last_id: Optional[str] = None

The event ID subscribed from. None if it was not incldued in the subscribe request.

Date and time

class energyquantified.time.Frequency(value)

Enumerator of valid frequencies for Energy Quantified’s API. The supported frequencies are:

  • P1Y – Yearly

  • SEASON – Summer or winter

  • P3M – Quarterly

  • P1M – Monthly

  • P1W – Weekly

  • P1D – Daily

  • PT1H – Hourly

  • PT30M – 30 minutes

  • PT15M – 15 minutes

  • PT10M – 10 minutes

  • PT5M – 5 minutes

  • NONE – Tick-data (no frequency)

__ge__(b)

Return self>=value.

__gt__(b)

Return self>value.

__le__(b)

Return self<=value.

__lt__(b)

Return self<value.

between(datetime_obj1, datetime_obj2)

Count number of steps in this frequency between two dates.

Parameters
  • datetime_obj1 (datetime) – The first date-time

  • datetime_obj2 (datetime) – The second date-time

Returns

The number of time this frequency fits between the two dates

Return type

int

classmethod by_tag(tag)

Look up frequencies by tag.

Parameters

tag (str) – The tag to look up

Returns

A Frequency for this tag

Return type

Frequency

get_delta(num_steps)

Create a relativedelta of N steps in this frequency. 0 steps means no change. 1 step means one tick forward, -1 step means one tick backwards.

Parameters

num_steps (int) – Number of steps forward (positive) or backwards (negative)

Returns

A relativedelta (similar to timedelta)

Return type

relativedelta

classmethod is_valid_tag(tag)

Check whether a frequency tag exists or not.

Parameters

tag (str) – The tag to look up

Returns

True if the frequency tag exists, otherwise False

Return type

bool

matches(datetime_obj)

Check if a date-time aligns with this frequency.

Parameters

datetime_obj (datetime) – A date-time

Returns

True if it falls into this frequency, otherwise False

Return type

bool

shift(datetime_obj, num_steps)

Shift a date-time by N steps in this frequency. 0 steps means no change. 1 step means one tick forward, -1 step means one tick backwards.

Parameters
  • datetime_obj (datetime) – A date-time

  • num_steps (int) – Number of steps forward (positive) or backwards (negative)

Returns

A shifted date-time

Return type

datetime

property tag

The frequency tag (P1D, PT1H, etc.).

truncate(datetime_obj)

Snap a date-time down to the nearest instant in this frequency.

Parameters

datetime_obj (datetime) – A date-time

Returns

A datetime snapped down to the nearest instant in this frequency

Return type

datetime


class energyquantified.time.Resolution(frequency, timezone)

A combination of a frequency and a timezone with utility methods for iteration and snapping datetimes to given frequency.

Parameters
  • frequency (Frequency) – The frequency for this resolution

  • timezone (TzInfo (or similar pytz timezone)) – The timezone for this resolution

__lshift__(datetime_obj)

Move a datetime one step backward in time. Usage:

>>> datetime_obj = resolution << datetime_obj
Parameters

datetime_obj (datetime) – A date-time

Returns

The supplied date-time shifted one step backward in time

Return type

datetime

__rshift__(datetime_obj)

Move a datetime one step forward in time. Usage:

>>> datetime_obj = resolution >> datetime_obj
Parameters

datetime_obj (datetime) – A date-time

Returns

The supplied date-time shifted one step forward in time

Return type

datetime

ceil(datetime_obj)

Snap a date or datetime up to the nearest instant in this resolution’s frequency.

Parameters

datetime_obj (datetime) – A date-time

Returns

A date-time snapped up to the nearest instant in this resolution’s frequency.

Return type

datetime

datetime(year=None, month=1, day=1, hour=0, minute=0, second=0, millis=0)

Create a datetime. Only year needs to be specified. The remaining fields defaults to the lowest value. The datetime will have the same timezone as this resolution and will be snapped to the frequency.

Parameters
  • year (int, required) – The year

  • month (int, optional) – The month (1-12), defaults to 1

  • day (int, optional) – The day-of-month (1-31), defaults to 1

  • hour (int, optional) – The hour of the day (0-23), defaults to 0

  • minute (int, optional) – The minute (0-59), defaults to 0

  • second (int, optional) – The second (0-59), defaults to 0

  • millis (int, optional) – The millisecond (0-999), defaults to 0

Returns

A new date-time, snapped down to the frequency

Return type

datetime

enumerate(begin=None, end=None)

Returns a generator over all datetimes between begin and end in this resolution. Example:

>>> resolution = Resolution(Frequency.P1D, CET)
>>> begin = resolution.datetime(2020, 5, 16)
>>> end = resolution.datetime(2020, 5, 26)
>>> for i in resolution.enumerate(begin, end):
        print(i)
Parameters
  • begin (datetime, required) – The begin date-time (inclusive)

  • end (datetime, required) – The end date-time (exclusive)

Yield

A generator of date-times between begin and end in this resolution

Return type

datetime

floor(datetime_obj)

Snap a date or datetime down to the nearest instant in this resolution’s frequency.

Parameters

datetime_obj (datetime) – A date-time

Returns

A date-time snapped down to the nearest instant in this resolution’s frequency.

Return type

datetime

is_iterable()

Check whether or not this Resolution is iterable

Returns

True if this Resolution is iterable, otherwise False

Return type

bool

matches(datetime_obj)

Check if a datetime obj has the same timezone as this resolution and that the datetime aligns with the frequency of this resolution.

Parameters

datetime_obj (datetime) – A date-time

Returns

True if it falls into this frequency, otherwise False

Return type

bool

now()

Create a datetime, snapped to beginning of the current period of this resolution’s frequency.

Returns

A date-time of now, snapped to beginning of the resolution’s frequency

Return type

datetime

shift(datetime_obj, steps)

Shift a date-time by N steps in this resolution’s frequency. 0 steps means no change. 1 step means one tick forward, -1 step means one tick backwards.

Parameters
  • datetime_obj (datetime) – A date-time

  • steps (int) – Number of steps forward (positive) or backwards (negative)

Returns

A shifted date-time

Return type

datetime

to_dict()

Convert this resolution to a dict in the same format as data is returned from the Energy Quantified Time Series API.

Returns

A dict of this resolution in the same format as the API response

Return type

dict


Methods in energyquantified.time. These methods are wrappers around the default methods in Python’s standard library and other libraries where the timezone is set to CET (which is used in the European power markets) by default.

energyquantified.time.now(tz=<DstTzInfo 'CET' CET+1:00:00 STD>)

Get the current datetime.

Parameters

tz (TzInfo (or similar pytz timezone)) – The preferred timezone, defaults to DEFAULT_TZ

Returns

A timezone aware datetime set to now

Return type

datetime

energyquantified.time.today(tz=<DstTzInfo 'CET' CET+1:00:00 STD>)

Get a datetime set to midnight today.

Parameters

tz (TzInfo (or similar pytz timezone)) – The preferred timezone, defaults to DEFAULT_TZ

Returns

A timezone aware datetime set to midnight this morning

Return type

datetime

energyquantified.time.get_datetime(year=None, month=1, day=1, hour=0, minute=0, second=0, millis=0, tz=<DstTzInfo 'CET' CET+1:00:00 STD>)

Get a datetime. Only year needs to be specified. The remaining fields defaults to the lowest value. Timezone defaults to DEFAULT_TZ.

Parameters
  • year (int, required) – The year

  • month (int, optional) – The month (1-12), defaults to 1

  • day (int, optional) – The day-of-month (1-31), defaults to 1

  • hour (int, optional) – The hour-of-day (0-23), defaults to 0

  • minute (int, optional) – The minute (0-59), defaults to 0

  • second (int, optional) – The second (0-59), defaults to 0

  • millis (int, optional) – The milliseconds (0-999), defaults to 0

  • tz (TzInfo (or similar pytz timezone)) – The timezone, defaults to DEFAULT_TZ

Returns

A timezone aware datetime

Return type

datetime

energyquantified.time.get_date(year=None, month=1, day=1)

Get a date. Only year needs to be specified. The remaining fields defaults to the lowest value.

Parameters
  • year (int, required) – The year

  • month (int, optional) – The month (1-12), defaults to 1

  • day (int, optional) – The day-of-month (1-31), defaults to 1

Returns

A date

Return type

date

energyquantified.time.to_timezone(datetime_obj, tz=<DstTzInfo 'CET' CET+1:00:00 STD>)

Make a datetime object timezone-aware in given timezone. If it already has a timezone, convert the instant to provided timezone.

energyquantified.time.local_tz()

Get the local timezone.

Returns

The timezone for this system.

Return type

TzInfo


Constants in energyquantified.time. These are the most commonly used timezones in the European power markets.

energyquantified.time.UTC = <UTC>

UTC

Optimized UTC implementation. It unpickles using the single module global instance defined beneath this class declaration.

energyquantified.time.CET = <DstTzInfo 'CET' CET+1:00:00 STD>
energyquantified.time.WET = <DstTzInfo 'WET' WET0:00:00 STD>
energyquantified.time.EET = <DstTzInfo 'EET' EET+2:00:00 STD>
energyquantified.time.TRT = <DstTzInfo 'Europe/Istanbul' LMT+1:56:00 STD>
energyquantified.time.DEFAULT_TZ = <DstTzInfo 'CET' CET+1:00:00 STD>

Utils

class energyquantified.utils.Page(elements, page=None, page_size=None, total_items=None, first_page=None, last_page=None, page_load_func=None)

Bases: list

A Page is a subclass of the standard list type in Python with additional attributes for paging.

It also has methods for loading the next/previous page, and to print the page to stdout.

append(value)

Append object to the end of the list.

clear()

Remove all items from list.

copy()

Return a shallow copy of the list.

count(value, /)

Return number of occurrences of value.

extend(iterable)

Extend list by appending elements from the iterable.

first_page

The first page (is always 1)

get_next_page()

Get the next page. Will perform an HTTP request if data is not already in local cache.

Raises
  • PageError – When there is no next page

  • PageError – There is no support for loading the next page

Returns

The next page

Return type

Page

get_previous_page()

Get the previous page. Will perform an HTTP request if data is not already in local cache.

Raises
  • PageError – When there is no previous page

  • PageError – There is no support for loading the previous page

Returns

The previous page

Return type

Page

has_next_page()

Check if there is a next page.

Returns

True when there is a next page

Return type

bool

has_previous_page()

Check if there is a previous page.

Returns

True when there is a previous page

Return type

bool

index(value, start=0, stop=9223372036854775807, /)

Return first index of value.

Raises ValueError if the value is not present.

insert(index, value)

Insert object before index.

last_page

The last page in the search

page

The current page

page_size

The page size

pop(index=- 1)

Remove and return item at index (default last).

Raises IndexError if list is empty or index is out of range.

print(file=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>)

Print the page with all its attributes.

Parameters

file (file descriptor, optional) – A file descriptor, defaults to sys.stdout

remove(value)

Remove first occurrence of value.

Raises ValueError if the value is not present.

reverse()

Reverse IN PLACE.

sort(*, key=None, reverse=False)

Sort the list in ascending order and return None.

The sort is in-place (i.e. the list itself is modified) and stable (i.e. the order of two equal elements is maintained).

If a key function is given, apply it once to each list item and sort them, ascending or descending, according to their function values.

The reverse flag can be set to sort in descending order.

total_items

Total number of items found in search across all pages

total_pages

The total number of pages

Exceptions

Even though the exceptions below are listed with full path, they are exposed in module energyquantified.exceptions.

API exceptions

exception energyquantified.exceptions.APIError(*args, **kwargs)

Base exception for all errors that may occur during an API call.


exception energyquantified.exceptions.HTTPError(*args, **kwargs)

Base class for all HTTP errors. Mostly used to wrap request’s HTTP errors.


exception energyquantified.exceptions.ValidationError(reason=None, parameter=None, *args, **kwargs)

Validation error of some kind (invalid parameter or combination of parameters).


exception energyquantified.exceptions.NotFoundError(reason=None, *args, **kwargs)

The resource was not found on the server.


exception energyquantified.exceptions.UnauthorizedError(reason=None, *args, **kwargs)

Authentication errors such as invalid API key or that the user is blocked.


exception energyquantified.exceptions.ForbiddenError(reason=None, *args, **kwargs)

The resource is not accessible for the user.


exception energyquantified.exceptions.InternalServerError(*args, **kwargs)

The server failed to process the request.

Initialization errors

exception energyquantified.exceptions.InitializationError(reason=None, *args, **kwargs)

Initialization error for the Energy Quantified Python client.

Pagination exceptions

exception energyquantified.exceptions.PageError(reason=None, *args, **kwargs)

A page error.

Parser exceptions

exception energyquantified.exceptions.ParseException(*args, **kwargs)

Failed to parse an API response.

Push feed exceptions

exception energyquantified.exceptions.WebSocketsError(message, status_code=None, status=None, description=None, *args, **kwargs)