pyiso package

Module contents

pyiso.client_factory(client_name, **kwargs)[source]

Return a client for an external data set

pyiso.tasks module

Submodules

class pyiso.base.BaseClient(timeout_seconds=30)[source]

Base class for scraper/parser clients.

FREQUENCY_CHOICES = IntervalChoices(hourly='1hr', fivemin='5m', tenmin='10m', fifteenmin='15m', na='n/a', dam='1hr')
MARKET_CHOICES = IntervalChoices(hourly='RTHR', fivemin='RT5M', tenmin='RT5M', fifteenmin='RTPD', na='RT5M', dam='DAHR')
NAME = ''
TZ_NAME = 'UTC'
dates()[source]

Returns a list of dates in local time

fetch_xls(url)[source]
Parameters:url – The URL of the .xls file to request.
Returns:The .xls document’s content as a pandas object.
Return type:pandas.io.excel.ExcelFile
get_generation(latest=False, yesterday=False, start_at=False, end_at=False, **kwargs)[source]

Scrape and parse generation fuel mix data.

Parameters:
  • latest (bool) – If True, only get the generation mix at the one most recent available time point. Available for all regions.
  • yesterday (bool) – If True, get the generation mix for every time point yesterday. Not available for all regions.
  • start_at (datetime) – If the datetime is naive, it is assummed to be in the timezone of the Balancing Authority. The timestamp of all returned data points will be greater than or equal to this value. If using, must provide both start_at and end_at parameters. Not available for all regions.
  • end_at (datetime) – If the datetime is naive, it is assummed to be in the timezone of the Balancing Authority. The timestamp of all returned data points will be less than or equal to this value. If using, must provide both start_at and end_at parameters. Not available for all regions.
Returns:

List of dicts, each with keys [ba_name, timestamp, freq, market, fuel_name, gen_MW]. Timestamps are in UTC.

Return type:

list

get_lmp(**kwargs)[source]

Locational Marginal Price (LMP) is no longer considered a useful measure in reducing carbon emissions. As such, this method has been removed. Please see http://watttime.org/lmp for details.

get_load(latest=False, yesterday=False, start_at=False, end_at=False, **kwargs)[source]

Scrape and parse load data.

Parameters:
  • latest (bool) – If True, only get the load at the one most recent available time point. Available for all regions.
  • yesterday (bool) – If True, get the load for every time point yesterday. Not available for all regions.
  • start_at (datetime) – If the datetime is naive, it is assummed to be in the timezone of the Balancing Authority. The timestamp of all returned data points will be greater than or equal to this value. If using, must provide both start_at and end_at parameters. Not available for all regions.
  • end_at (datetime) – If the datetime is naive, it is assummed to be in the timezone of the Balancing Authority. The timestamp of all returned data points will be less than or equal to this value. If using, must provide both start_at and end_at parameters. Not available for all regions.
Returns:

List of dicts, each with keys [ba_name, timestamp, freq, market, load_MW]. Timestamps are in UTC.

Return type:

list

get_trade(latest=False, yesterday=False, start_at=False, end_at=False, **kwargs)[source]

Scrape and parse import/export data. Value is net export (export - import), can be positive or negative.

Parameters:
  • latest (bool) – If True, only get the trade at the one most recent available time point. Available for all regions.
  • yesterday (bool) – If True, get the trade for every time point yesterday. Not available for all regions.
  • start_at (datetime) – If the datetime is naive, it is assummed to be in the timezone of the Balancing Authority. The timestamp of all returned data points will be greater than or equal to this value. If using, must provide both start_at and end_at parameters. Not available for all regions.
  • end_at (datetime) – If the datetime is naive, it is assummed to be in the timezone of the Balancing Authority. The timestamp of all returned data points will be less than or equal to this value. If using, must provide both start_at and end_at parameters. Not available for all regions.
Returns:

List of dicts, each with keys [ba_name, timestamp, freq, market, net_exp_MW]. Timestamps are in UTC.

Return type:

list

handle_options(**kwargs)[source]

Process and store keyword argument options.

local_now()[source]

Returns a tz-aware datetime equal to the current moment, in the local timezone

parse_row(row, delimiter=', ', datetime_col=None, drop_vals=None)[source]
parse_to_df(filelike, mode='csv', header_names=None, sheet_names=None, **kwargs)[source]

Parse a delimited or excel file from the provided content and return a DataFrame.

Any extra kwargs are passed to the appropriate pandas parser; read the pandas docs for details. Recommended kwargs: skiprows, parse_cols, header.

Parameters:
  • filelike – string-like or filelike object containing formatted data
  • mode (string) – Choose from ‘csv’ or ‘xls’. Default ‘csv’. If ‘csv’, kwargs are passed to pandas.read_csv.
  • header_names (list) – List of strings to use as column names. If provided, this will override the header extracted by pandas.
  • sheet_names (list) – List of strings for excel sheet names to read. Default is to concatenate all sheets.
Paramtype:

string or file

request(url, mode='get', retry_sec=5, retries_remaining=5, **kwargs)[source]

Get or post to a URL with the provided kwargs. Returns the response, or None if an error was encountered. If the mode is not ‘get’ or ‘post’, raises ValueError.

serialize(df, header, extras={})[source]
serialize_faster(df, extras={}, drop_index=False)[source]

DF is a DataFrame with DateTimeIndex and columns fuel_type and gen_MW (or load_mW). Index and columns are already properly named.

slice_times(df, options=None)[source]
unpivot(df)[source]
unzip(content)[source]

Unzip encoded data. Returns the unzipped content as an array of strings, each representing one file’s content or returns None if an error was encountered. *Previous behavior: Only returned the content from the first file*

utcify(local_ts_str, tz_name=None, is_dst=None)[source]

Convert a datetime or datetime string to UTC.

Uses the default behavior of dateutil.parser.parse to convert the string to a datetime object.

Parameters:
  • local_ts (string) – The local datetime to be converted.
  • tz_name (string) – If local_ts is naive, it is assumed to be in timezone tz. If tz is not provided, the client’s default timezone is used.
  • is_dst (bool) – If provided, explicitly set daylight savings time as True or False.
Returns:

Datetime in UTC.

Return type:

datetime

utcify_index(local_index, tz_name=None, tz_col=None)[source]

Convert a DateTimeIndex to UTC.

Parameters:
  • local_index (DateTimeIndex) – The local DateTimeIndex to be converted.
  • tz_name (string) – If local_ts is naive, it is assumed to be in timezone tz. If tz is not provided, the client’s default timezone is used.
Returns:

DatetimeIndex in UTC.

Return type:

DatetimeIndex

class pyiso.base.IntervalChoices(hourly, fivemin, tenmin, fifteenmin, na, dam)
dam

Alias for field number 5

fifteenmin

Alias for field number 3

fivemin

Alias for field number 1

hourly

Alias for field number 0

na

Alias for field number 4

tenmin

Alias for field number 2

class pyiso.bpa.BPAClient(timeout_seconds=30)[source]
NAME = 'BPA'
TZ_NAME = 'America/Los_Angeles'
base_url = 'https://transmission.bpa.gov/business/operations/'
date_parser(ts_str)[source]
fetch_historical()[source]

Get BPA generation or load data from the far past

fetch_recent()[source]

Get BPA generation or load data from the past week

fetcher()[source]

Choose the correct fetcher method for this request

fuels = {'Fossil/Biomass': 'biomass', 'Hydro': 'hydro', 'Thermal': 'thermal', 'Wind': 'wind'}
get_generation(latest=False, start_at=False, end_at=False, **kwargs)[source]

Scrape and parse generation fuel mix data.

Parameters:
  • latest (bool) – If True, only get the generation mix at the one most recent available time point. Available for all regions.
  • yesterday (bool) – If True, get the generation mix for every time point yesterday. Not available for all regions.
  • start_at (datetime) – If the datetime is naive, it is assummed to be in the timezone of the Balancing Authority. The timestamp of all returned data points will be greater than or equal to this value. If using, must provide both start_at and end_at parameters. Not available for all regions.
  • end_at (datetime) – If the datetime is naive, it is assummed to be in the timezone of the Balancing Authority. The timestamp of all returned data points will be less than or equal to this value. If using, must provide both start_at and end_at parameters. Not available for all regions.
Returns:

List of dicts, each with keys [ba_name, timestamp, freq, market, fuel_name, gen_MW]. Timestamps are in UTC.

Return type:

list

get_load(latest=False, start_at=False, end_at=False, **kwargs)[source]

Scrape and parse load data.

Parameters:
  • latest (bool) – If True, only get the load at the one most recent available time point. Available for all regions.
  • yesterday (bool) – If True, get the load for every time point yesterday. Not available for all regions.
  • start_at (datetime) – If the datetime is naive, it is assummed to be in the timezone of the Balancing Authority. The timestamp of all returned data points will be greater than or equal to this value. If using, must provide both start_at and end_at parameters. Not available for all regions.
  • end_at (datetime) – If the datetime is naive, it is assummed to be in the timezone of the Balancing Authority. The timestamp of all returned data points will be less than or equal to this value. If using, must provide both start_at and end_at parameters. Not available for all regions.
Returns:

List of dicts, each with keys [ba_name, timestamp, freq, market, load_MW]. Timestamps are in UTC.

Return type:

list

handle_options(**kwargs)[source]

Process and store keyword argument options.

parse_generation(df)[source]
class pyiso.caiso.CAISOClient[source]

Interface to CAISO data sources.

For information about the data sources, see http://www.caiso.com/Documents/InterfaceSpecifications-OASISv4_1_3.pdf

NAME = 'CAISO'
TZ_NAME = 'America/Los_Angeles'
base_payload = {'version': 1}
base_url_gen = 'http://content.caiso.com/green/renewrpt/'
base_url_oasis = 'http://oasis.caiso.com/oasisapi/SingleZip'
base_url_outlook = 'http://content.caiso.com/outlook/SP/'
construct_oasis_payload(queryname, **kwargs)[source]
fetch_oasis(payload={}, return_all_files=False)[source]

Returns a list of report data elements, or an empty list if an error was encountered.

If return_all_files=False, returns only the content from the first file in the .zip - this is the default behavior and was used in earlier versions of this function.

If return_all_files=True, will return an array representing the content from each file.

fetch_todays_outlook_renewables()[source]
fuels = {'BIOGAS': 'biogas', 'BIOMASS': 'biomass', 'GEOTHERMAL': 'geo', 'HYDRO': 'hydro', 'NUCLEAR': 'nuclear', 'SMALL HYDRO': 'smhydro', 'SOLAR': 'solar', 'SOLAR PV': 'solarpv', 'SOLAR THERMAL': 'solarth', 'THERMAL': 'thermal', 'WIND TOTAL': 'wind'}
get_generation(latest=False, yesterday=False, start_at=False, end_at=False, **kwargs)[source]

Scrape and parse generation fuel mix data.

Parameters:
  • latest (bool) – If True, only get the generation mix at the one most recent available time point. Available for all regions.
  • yesterday (bool) – If True, get the generation mix for every time point yesterday. Not available for all regions.
  • start_at (datetime) – If the datetime is naive, it is assummed to be in the timezone of the Balancing Authority. The timestamp of all returned data points will be greater than or equal to this value. If using, must provide both start_at and end_at parameters. Not available for all regions.
  • end_at (datetime) – If the datetime is naive, it is assummed to be in the timezone of the Balancing Authority. The timestamp of all returned data points will be less than or equal to this value. If using, must provide both start_at and end_at parameters. Not available for all regions.
Returns:

List of dicts, each with keys [ba_name, timestamp, freq, market, fuel_name, gen_MW]. Timestamps are in UTC.

Return type:

list

get_load(latest=False, start_at=False, end_at=False, **kwargs)[source]

Scrape and parse load data.

Parameters:
  • latest (bool) – If True, only get the load at the one most recent available time point. Available for all regions.
  • yesterday (bool) – If True, get the load for every time point yesterday. Not available for all regions.
  • start_at (datetime) – If the datetime is naive, it is assummed to be in the timezone of the Balancing Authority. The timestamp of all returned data points will be greater than or equal to this value. If using, must provide both start_at and end_at parameters. Not available for all regions.
  • end_at (datetime) – If the datetime is naive, it is assummed to be in the timezone of the Balancing Authority. The timestamp of all returned data points will be less than or equal to this value. If using, must provide both start_at and end_at parameters. Not available for all regions.
Returns:

List of dicts, each with keys [ba_name, timestamp, freq, market, load_MW]. Timestamps are in UTC.

Return type:

list

get_trade(latest=False, start_at=False, end_at=False, **kwargs)[source]

Scrape and parse import/export data. Value is net export (export - import), can be positive or negative.

Parameters:
  • latest (bool) – If True, only get the trade at the one most recent available time point. Available for all regions.
  • yesterday (bool) – If True, get the trade for every time point yesterday. Not available for all regions.
  • start_at (datetime) – If the datetime is naive, it is assummed to be in the timezone of the Balancing Authority. The timestamp of all returned data points will be greater than or equal to this value. If using, must provide both start_at and end_at parameters. Not available for all regions.
  • end_at (datetime) – If the datetime is naive, it is assummed to be in the timezone of the Balancing Authority. The timestamp of all returned data points will be less than or equal to this value. If using, must provide both start_at and end_at parameters. Not available for all regions.
Returns:

List of dicts, each with keys [ba_name, timestamp, freq, market, net_exp_MW]. Timestamps are in UTC.

Return type:

list

handle_options(**kwargs)[source]

Process and store keyword argument options.

oasis_markets = {'DAHR': 'DAM', 'RT5M': 'RTM', 'RTHR': 'HASP', 'RTPD': 'RTPD'}
oasis_request_time_format = '%Y%m%dT%H:%M-0000'
parse_oasis_demand_forecast(raw_data)[source]

Parse raw data output of fetch_oasis for system-wide 5-min RTM demand forecast.

parse_oasis_renewable(raw_data)[source]

Parse raw data output of fetch_oasis for renewables.

parse_oasis_slrs(raw_data)[source]

Parse raw data output of fetch_oasis for System Load and Resource Schedules.

parse_todays_outlook_renewables(soup, ts)[source]
price_map_url = 'http://wwwmobile.caiso.com/Web.Service.Chart/api/v3/ChartService/PriceContourMap1'
set_dt_index(df, date, hours, end_of_hour=True)[source]
todays_outlook_time(demand_soup)[source]
class pyiso.eia_esod.EIAClient(*args, **kwargs)[source]

Interface to EIA API.

The EIA API provides this information for the US lower 48 and beyond:
-Hourly load (actual and forecast), -Generation -Imports/exports

Full listing of BAs with time zones here: https://www.eia.gov/beta/realtime_grid/docs/UserGuideAndKnownIssues.pdf

EIA_BAs = ['AEC', 'AECI', 'AESO', 'AVA', 'AZPS', 'BANC', 'BCTC', 'BPAT', 'CISO', 'CFE', 'CHPD', 'CISO', 'CPLE', 'CPLW', 'DEAA', 'DOPD', 'DUK', 'EEI', 'EPE', 'ERCO', 'FMPP', 'FPC', 'FPL', 'GCPD', 'GRID', 'GRIF', 'GRMA', 'GVL', 'GWA', 'HGMA', 'HQT', 'HST', 'IESO', 'IID', 'IPCO', 'ISNE', 'JEA', 'LDWP', 'LGEE', 'MHEB', 'MISO', 'NBSO', 'NEVP', 'NSB', 'NWMT', 'NYIS', 'OVEC', 'PACE', 'PACW', 'PGE', 'PJM', 'PNM', 'PSCO', 'PSEI', 'SC', 'SCEG', 'SCL', 'SEC', 'SEPA', 'SOCO', 'SPA', 'SPC', 'SRP', 'SWPP', 'TAL', 'TEC', 'TEPC', 'TIDC', 'TPWR', 'TVA', 'WACM', 'WALC', 'WAUW', 'WWA', 'YAD']
FUEL_CHOICES = ['other']
NAME = 'EIA'
add_gen_data(data_list)[source]
base_url = 'http://api.eia.gov'
format_data(data)[source]

Convert load data to int, handle None

format_result(data)[source]

Output EIA API results in pyiso format

format_url()[source]

Set EIA API URL based on options

fuels = {'Other': 'other'}
get_generation(latest=False, yesterday=False, start_at=False, end_at=False, **kwargs)[source]

Scrape and parse generation fuel mix data. Note: Generation may be quite low for HST and NSB BAs.

get_load(latest=False, yesterday=False, start_at=False, end_at=False, forecast=False, **kwargs)[source]

Scrape and parse load data.

get_trade(latest=False, yesterday=False, start_at=False, end_at=False, **kwargs)[source]

Scrape and parse import/export data.

handle_ba_limitations()[source]

Handle BA limitations

handle_options(**kwargs)[source]

Process and store keyword argument options.

set_ba(bal_auth)[source]
set_url(type, series_id_suffix)[source]
class pyiso.ercot.ERCOTClient(timeout_seconds=30)[source]
NAME = 'ERCOT'
TZ_NAME = 'US/Central'
base_report_url = 'http://mis.ercot.com'
get_generation(latest=False, **kwargs)[source]

Scrape and parse generation fuel mix data.

Parameters:
  • latest (bool) – If True, only get the generation mix at the one most recent available time point. Available for all regions.
  • yesterday (bool) – If True, get the generation mix for every time point yesterday. Not available for all regions.
  • start_at (datetime) – If the datetime is naive, it is assummed to be in the timezone of the Balancing Authority. The timestamp of all returned data points will be greater than or equal to this value. If using, must provide both start_at and end_at parameters. Not available for all regions.
  • end_at (datetime) – If the datetime is naive, it is assummed to be in the timezone of the Balancing Authority. The timestamp of all returned data points will be less than or equal to this value. If using, must provide both start_at and end_at parameters. Not available for all regions.
Returns:

List of dicts, each with keys [ba_name, timestamp, freq, market, fuel_name, gen_MW]. Timestamps are in UTC.

Return type:

list

get_load(latest=False, **kwargs)[source]

Scrape and parse load data.

Parameters:
  • latest (bool) – If True, only get the load at the one most recent available time point. Available for all regions.
  • yesterday (bool) – If True, get the load for every time point yesterday. Not available for all regions.
  • start_at (datetime) – If the datetime is naive, it is assummed to be in the timezone of the Balancing Authority. The timestamp of all returned data points will be greater than or equal to this value. If using, must provide both start_at and end_at parameters. Not available for all regions.
  • end_at (datetime) – If the datetime is naive, it is assummed to be in the timezone of the Balancing Authority. The timestamp of all returned data points will be less than or equal to this value. If using, must provide both start_at and end_at parameters. Not available for all regions.
Returns:

List of dicts, each with keys [ba_name, timestamp, freq, market, load_MW]. Timestamps are in UTC.

Return type:

list

handle_options(**kwargs)[source]

Process and store keyword argument options.

is_dst(val, standard)[source]
parse_rtm(content)[source]
real_time_url = 'http://www.ercot.com/content/cdr/html/real_time_system_conditions.html'
report_type_ids = {'gen_hrly': '12358', 'load_7day': '12311', 'wind_5min': '13071', 'wind_hrly': '13028'}
class pyiso.ieso.AdequacyReportHandler(ieso_client)[source]
earliest_available_datetime()[source]
Returns:A tz-aware datetime representing the earliest EST datetime that (historical) report data is publicly available.
Return type:datetime
frequency()[source]

The frequency of the report data. :return: One of BaseClient.FREQUENCY_CHOICES

latest_available_datetime()[source]
Returns:A tz-aware datetime representing the latest EST datetime that (current/future) report data is publicly available.
Return type:datetime
market()[source]

The market which the report data is for. :return: One of BaseClient.MARKET_CHOICES

parse_report(xml_content, result_ts, parser_format, min_datetime, max_datetime)[source]

Parses the report content and appends them to a timeseries of results, in one of several WattTime client formats.

Parameters:
  • xml_content (str) – The XML response body of the report.
  • result_ts (list) – The timeseries (a list of dicts) which results should be appended to. Timestamps are in UTC.
  • parser_format (str) – The parser format used to append results.
  • min_datetime (datetime) – The minimum datetime that can be appended to the results.
  • max_datetime (datetime) – The maximum datetime that can be appended to the results.
report_interval()[source]

The amount of time time between reports. :return: One of the ReportFileInterval enum strings.

report_url(report_datetime=None)[source]
Parameters:report_datetime (datetime) – If provided, report URL for that date will be constructed. If no datetime is provided, the current report URL will be constructed.
Returns:The fully-qualified request URL.
Return type:str
class pyiso.ieso.BaseIesoReportHandler(ieso_client)[source]

Base class to standardize how IESO market reports are parsed and to define date-related attributes.

BASE_URL = 'http://reports.ieso.ca/public/'
append_generation(result_ts, tz_aware_dt, gen_mw, fuel)[source]

Appends a dict to the results list, with the keys [ba_name, timestamp, freq, market, fuel_name, gen_MW]. Timestamps are in UTC. :param list result_ts: The timeseries (a list of dicts) which results should be appended to. :param datetime tz_aware_dt: The datetime of the data being appended (timezone-aware). :param float gen_mw: Electricity generation in megawatts (MW) :param str fuel: IESO fuel name (will be converted to WattTime name).

append_load(result_ts, tz_aware_dt, load_mw)[source]

Appends a dict to the results list, with the keys [ba_name, timestamp, freq, market, load_MW]. Timestamps are in UTC. :param list result_ts: The timeseries (a list of dicts) which results should be appended to. :param datetime tz_aware_dt: The datetime of the data being appended (timezone-aware). :param float load_mw: Electricity load in megawatts (MW).

append_trade(result_ts, tz_aware_dt, net_exp_mw)[source]

Appends a dict to the results list, with the keys [ba_name, timestamp, freq, market, net_exp_MW]. Timestamps are in UTC. :param list result_ts: The timeseries (a list of dicts) which results should be appended to. :param datetime tz_aware_dt: The datetime of the data being appended (timezone-aware). :param float net_exp_mw: The net exported megawatts (MW) (i.e. export - import). Negative values indicate that

more electricity was imported than exported.
datetime_for_next_report_request(tz_aware_dt)[source]

When requesting reports for a time range, some scenarios (e.g. hour ending 23 and report boundaries) require that the datetime for the next report request not be based off the full report interval. This convenience method helps determine the next datetime that should be used when iterating over report requests chronologically to retrieve data for a time range.

Parameters:tz_aware_dt – The timezone-aware datetime of the of the report that has already been requested.
Returns:A timezone-aware datetime that should be used for the next report request when requesting reports for a time range chronologically.
datetime_for_report_request(tz_aware_dt)[source]

This method converts a timezone-aware datetime to EST and makes necessary “hour ending” considerations.

The hourly IESO reports follow the convention of “hour ending” for reporting data. This means that hour ending 1 corresponds to the time 01:00 and hour ending 23 corresponds to 23:00. The time 00:00 for a given day is represented by hour ending 24 contained in the previous day’s report.

Parameters:tz_aware_dt (datetime) – A timezone-aware datetime.
Returns:A date which should be used when requesting the date-formatted URL to retrieve a report containing data for the datetime.
Return type:datetime
earliest_available_datetime()[source]
Returns:A tz-aware datetime representing the earliest EST datetime that (historical) report data is publicly available.
Return type:datetime
frequency()[source]

The frequency of the report data. :return: One of BaseClient.FREQUENCY_CHOICES

static is_start_of_day(dt)[source]
Parameters:dt (datetime) – Any datetime.
Returns:True/False indicating if the time is exactly 00:00:00.000.
Return type:bool
static is_start_of_hour(dt)[source]
Parameters:dt (datetime) – Any datetime.
Returns:True/False indicating if the datetime is the start of an hour (i.e. HH:00:00.000).
Return type:bool
static is_start_of_year(dt)[source]
Parameters:dt (datetime) – Any datetime.
Returns:True/False indicating if the datetime is exactly 00:00:00.000 on January 1st.
Return type:bool
latest_available_datetime()[source]
Returns:A tz-aware datetime representing the latest EST datetime that (current/future) report data is publicly available.
Return type:datetime
market()[source]

The market which the report data is for. :return: One of BaseClient.MARKET_CHOICES

parse_report(xml_content, result_ts, parser_format, min_datetime, max_datetime)[source]

Parses the report content and appends them to a timeseries of results, in one of several WattTime client formats.

Parameters:
  • xml_content (str) – The XML response body of the report.
  • result_ts (list) – The timeseries (a list of dicts) which results should be appended to. Timestamps are in UTC.
  • parser_format (str) – The parser format used to append results.
  • min_datetime (datetime) – The minimum datetime that can be appended to the results.
  • max_datetime (datetime) – The maximum datetime that can be appended to the results.
report_interval()[source]

The amount of time time between reports. :return: One of the ReportFileInterval enum strings.

report_url(report_datetime=None)[source]
Parameters:report_datetime (datetime) – If provided, report URL for that date will be constructed. If no datetime is provided, the current report URL will be constructed.
Returns:The fully-qualified request URL.
Return type:str
class pyiso.ieso.GeneratorOutputByFuelHourlyReportHandler(ieso_client)[source]
earliest_available_datetime()[source]
Returns:A tz-aware datetime representing the earliest EST datetime that (historical) report data is publicly available.
Return type:datetime
frequency()[source]

The frequency of the report data. :return: One of BaseClient.FREQUENCY_CHOICES

latest_available_datetime()[source]
Returns:A tz-aware datetime representing the latest EST datetime that (current/future) report data is publicly available.
Return type:datetime
market()[source]

The market which the report data is for. :return: One of BaseClient.MARKET_CHOICES

parse_report(xml_content, result_ts, parser_format, min_datetime, max_datetime)[source]

Parses the report content and appends them to a timeseries of results, in one of several WattTime client formats.

Parameters:
  • xml_content (str) – The XML response body of the report.
  • result_ts (list) – The timeseries (a list of dicts) which results should be appended to. Timestamps are in UTC.
  • parser_format (str) – The parser format used to append results.
  • min_datetime (datetime) – The minimum datetime that can be appended to the results.
  • max_datetime (datetime) – The maximum datetime that can be appended to the results.
report_interval()[source]

The amount of time time between reports. :return: One of the ReportFileInterval enum strings.

report_url(report_datetime=None)[source]
Parameters:report_datetime (datetime) – If provided, report URL for that date will be constructed. If no datetime is provided, the current report URL will be constructed.
Returns:The fully-qualified request URL.
Return type:str
class pyiso.ieso.GeneratorOutputCapabilityReportHandler(ieso_client)[source]
earliest_available_datetime()[source]
Returns:A tz-aware datetime representing the earliest EST datetime that (historical) report data is publicly available.
Return type:datetime
frequency()[source]

The frequency of the report data. :return: One of BaseClient.FREQUENCY_CHOICES

latest_available_datetime()[source]
Returns:A tz-aware datetime representing the latest EST datetime that (current/future) report data is publicly available.
Return type:datetime
market()[source]

The market which the report data is for. :return: One of BaseClient.MARKET_CHOICES

parse_report(xml_content, result_ts, parser_format, min_datetime, max_datetime)[source]

Parses the report content and appends them to a timeseries of results, in one of several WattTime client formats.

Parameters:
  • xml_content (str) – The XML response body of the report.
  • result_ts (list) – The timeseries (a list of dicts) which results should be appended to. Timestamps are in UTC.
  • parser_format (str) – The parser format used to append results.
  • min_datetime (datetime) – The minimum datetime that can be appended to the results.
  • max_datetime (datetime) – The maximum datetime that can be appended to the results.
report_interval()[source]

The amount of time time between reports. :return: One of the ReportFileInterval enum strings.

report_url(report_datetime=None)[source]
Parameters:report_datetime (datetime) – If provided, report URL for that date will be constructed. If no datetime is provided, the current report URL will be constructed.
Returns:The fully-qualified request URL.
Return type:str
class pyiso.ieso.IESOClient[source]

The Independent Electricity System Operator (IESO) of Ontario publishes a variety of public XML reports at http://reports.ieso.ca/public/ which can be stitched together to implement WattTime’s pyiso API.

NAME = 'IESO'
TZ_NAME = 'EST'
base_url = 'http://reports.ieso.ca/public/'
fuels = {'BIOFUEL': 'biomass', 'GAS': 'natgas', 'HYDRO': 'hydro', 'NUCLEAR': 'nuclear', 'OTHER': 'other', 'SOLAR': 'solar', 'WIND': 'wind'}
get_generation(latest=False, yesterday=False, start_at=None, end_at=None, **kwargs)[source]

Scrape and parse generation fuel mix data.

Parameters:
  • latest (bool) – If True, only get the generation mix at the one most recent available time point. Available for all regions.
  • yesterday (bool) – If True, get the generation mix for every time point yesterday. Not available for all regions.
  • start_at (datetime) – If the datetime is naive, it is assummed to be in the timezone of the Balancing Authority. The timestamp of all returned data points will be greater than or equal to this value. If using, must provide both start_at and end_at parameters. Not available for all regions.
  • end_at (datetime) – If the datetime is naive, it is assummed to be in the timezone of the Balancing Authority. The timestamp of all returned data points will be less than or equal to this value. If using, must provide both start_at and end_at parameters. Not available for all regions.
Returns:

List of dicts, each with keys [ba_name, timestamp, freq, market, fuel_name, gen_MW]. Timestamps are in UTC.

Return type:

list

get_load(latest=False, yesterday=False, start_at=None, end_at=None, **kwargs)[source]

Scrape and parse load data.

Parameters:
  • latest (bool) – If True, only get the load at the one most recent available time point. Available for all regions.
  • yesterday (bool) – If True, get the load for every time point yesterday. Not available for all regions.
  • start_at (datetime) – If the datetime is naive, it is assummed to be in the timezone of the Balancing Authority. The timestamp of all returned data points will be greater than or equal to this value. If using, must provide both start_at and end_at parameters. Not available for all regions.
  • end_at (datetime) – If the datetime is naive, it is assummed to be in the timezone of the Balancing Authority. The timestamp of all returned data points will be less than or equal to this value. If using, must provide both start_at and end_at parameters. Not available for all regions.
Returns:

List of dicts, each with keys [ba_name, timestamp, freq, market, load_MW]. Timestamps are in UTC.

Return type:

list

get_trade(latest=False, yesterday=False, start_at=None, end_at=None, **kwargs)[source]

Scrape and parse import/export data. Value is net export (export - import), can be positive or negative.

Parameters:
  • latest (bool) – If True, only get the trade at the one most recent available time point. Available for all regions.
  • yesterday (bool) – If True, get the trade for every time point yesterday. Not available for all regions.
  • start_at (datetime) – If the datetime is naive, it is assummed to be in the timezone of the Balancing Authority. The timestamp of all returned data points will be greater than or equal to this value. If using, must provide both start_at and end_at parameters. Not available for all regions.
  • end_at (datetime) – If the datetime is naive, it is assummed to be in the timezone of the Balancing Authority. The timestamp of all returned data points will be less than or equal to this value. If using, must provide both start_at and end_at parameters. Not available for all regions.
Returns:

List of dicts, each with keys [ba_name, timestamp, freq, market, net_exp_MW]. Timestamps are in UTC.

Return type:

list

handle_options(**kwargs)[source]

Process and store keyword argument options.

class pyiso.ieso.IntertieScheduleFlowReportHandler(ieso_client)[source]
earliest_available_datetime()[source]
Returns:A tz-aware datetime representing the earliest EST datetime that (historical) report data is publicly available.
Return type:datetime
frequency()[source]

The frequency of the report data. :return: One of BaseClient.FREQUENCY_CHOICES

latest_available_datetime()[source]
Returns:A tz-aware datetime representing the latest EST datetime that (current/future) report data is publicly available.
Return type:datetime
market()[source]

The market which the report data is for. :return: One of BaseClient.MARKET_CHOICES

parse_report(xml_content, result_ts, parser_format, min_datetime, max_datetime)[source]

Parses the report content and appends them to a timeseries of results, in one of several WattTime client formats.

Parameters:
  • xml_content (str) – The XML response body of the report.
  • result_ts (list) – The timeseries (a list of dicts) which results should be appended to. Timestamps are in UTC.
  • parser_format (str) – The parser format used to append results.
  • min_datetime (datetime) – The minimum datetime that can be appended to the results.
  • max_datetime (datetime) – The maximum datetime that can be appended to the results.
report_interval()[source]

The amount of time time between reports. :return: One of the ReportFileInterval enum strings.

report_url(report_datetime=None)[source]
Parameters:report_datetime (datetime) – If provided, report URL for that date will be constructed. If no datetime is provided, the current report URL will be constructed.
Returns:The fully-qualified request URL.
Return type:str
class pyiso.ieso.ParserFormat[source]

Since report handlers can parse the XML reports into a variety of formats, this enum facilitates passing which pyiso output format should be used between IESOClient and the BaseIesoReportHandler implementations.

generation = 'generation'
load = 'load'
trade = 'trade'
class pyiso.ieso.PredispatchConstrainedTotalsReportHandler(ieso_client)[source]
earliest_available_datetime()[source]
Returns:A tz-aware datetime representing the earliest EST datetime that (historical) report data is publicly available.
Return type:datetime
frequency()[source]

The frequency of the report data. :return: One of BaseClient.FREQUENCY_CHOICES

latest_available_datetime()[source]
Returns:A tz-aware datetime representing the latest EST datetime that (current/future) report data is publicly available.
Return type:datetime
market()[source]

The market which the report data is for. :return: One of BaseClient.MARKET_CHOICES

parse_report(xml_content, result_ts, parser_format, min_datetime, max_datetime)[source]

Parses the report content and appends them to a timeseries of results, in one of several WattTime client formats.

Parameters:
  • xml_content (str) – The XML response body of the report.
  • result_ts (list) – The timeseries (a list of dicts) which results should be appended to. Timestamps are in UTC.
  • parser_format (str) – The parser format used to append results.
  • min_datetime (datetime) – The minimum datetime that can be appended to the results.
  • max_datetime (datetime) – The maximum datetime that can be appended to the results.
report_interval()[source]

The amount of time time between reports. :return: One of the ReportFileInterval enum strings.

report_url(report_datetime=None)[source]
Parameters:report_datetime (datetime) – If provided, report URL for that date will be constructed. If no datetime is provided, the current report URL will be constructed.
Returns:The fully-qualified request URL.
Return type:str
class pyiso.ieso.RealTimeConstrainedTotalsReportHandler(ieso_client)[source]
earliest_available_datetime()[source]
Returns:A tz-aware datetime representing the earliest EST datetime that (historical) report data is publicly available.
Return type:datetime
frequency()[source]

The frequency of the report data. :return: One of BaseClient.FREQUENCY_CHOICES

latest_available_datetime()[source]
Returns:A tz-aware datetime representing the latest EST datetime that (current/future) report data is publicly available.
Return type:datetime
market()[source]

The market which the report data is for. :return: One of BaseClient.MARKET_CHOICES

parse_report(xml_content, result_ts, parser_format, min_datetime, max_datetime)[source]

Parses the report content and appends them to a timeseries of results, in one of several WattTime client formats.

Parameters:
  • xml_content (str) – The XML response body of the report.
  • result_ts (list) – The timeseries (a list of dicts) which results should be appended to. Timestamps are in UTC.
  • parser_format (str) – The parser format used to append results.
  • min_datetime (datetime) – The minimum datetime that can be appended to the results.
  • max_datetime (datetime) – The maximum datetime that can be appended to the results.
report_interval()[source]

The amount of time time between reports. :return: One of the ReportFileInterval enum strings.

report_url(report_datetime=None)[source]
Parameters:report_datetime (datetime) – If provided, report URL for that date will be constructed. If no datetime is provided, the current report URL will be constructed.
Returns:The fully-qualified request URL.
Return type:str
class pyiso.ieso.ReportFileInterval[source]

The report files are published with filenames containing date/time information. Some reports are broken up hourly, some daily, and ony yearly.

daily = 'daily'
hourly = 'hourly'
yearly = 'yearly'
class pyiso.isone.ISONEClient(*args, **kwargs)[source]
NAME = 'ISONE'
TZ_NAME = 'America/New_York'
base_url = 'https://webservices.iso-ne.com/api/v1.1'
fetch_data(endpoint, auth)[source]
fuels = {'Coal': 'coal', 'Hydro': 'hydro', 'Landfill Gas': 'biogas', 'Natural Gas': 'natgas', 'Nuclear': 'nuclear', 'Oil': 'oil', 'Other': 'other', 'Refuse': 'refuse', 'Solar': 'solar', 'Wind': 'wind', 'Wood': 'biomass'}
get_generation(latest=False, start_at=False, end_at=False, **kwargs)[source]

Scrape and parse generation fuel mix data.

Parameters:
  • latest (bool) – If True, only get the generation mix at the one most recent available time point. Available for all regions.
  • yesterday (bool) – If True, get the generation mix for every time point yesterday. Not available for all regions.
  • start_at (datetime) – If the datetime is naive, it is assummed to be in the timezone of the Balancing Authority. The timestamp of all returned data points will be greater than or equal to this value. If using, must provide both start_at and end_at parameters. Not available for all regions.
  • end_at (datetime) – If the datetime is naive, it is assummed to be in the timezone of the Balancing Authority. The timestamp of all returned data points will be less than or equal to this value. If using, must provide both start_at and end_at parameters. Not available for all regions.
Returns:

List of dicts, each with keys [ba_name, timestamp, freq, market, fuel_name, gen_MW]. Timestamps are in UTC.

Return type:

list

get_load(latest=False, start_at=False, end_at=False, forecast=False, **kwargs)[source]

Scrape and parse load data.

Parameters:
  • latest (bool) – If True, only get the load at the one most recent available time point. Available for all regions.
  • yesterday (bool) – If True, get the load for every time point yesterday. Not available for all regions.
  • start_at (datetime) – If the datetime is naive, it is assummed to be in the timezone of the Balancing Authority. The timestamp of all returned data points will be greater than or equal to this value. If using, must provide both start_at and end_at parameters. Not available for all regions.
  • end_at (datetime) – If the datetime is naive, it is assummed to be in the timezone of the Balancing Authority. The timestamp of all returned data points will be less than or equal to this value. If using, must provide both start_at and end_at parameters. Not available for all regions.
Returns:

List of dicts, each with keys [ba_name, timestamp, freq, market, load_MW]. Timestamps are in UTC.

Return type:

list

get_morningreport(day=None)[source]

Retrieve the morning report

Parameters:day (str) – Retrieve the Morning Report for a specific day (optional). format: YYYYMMDD
Return type:dict
get_sevendayforecast(day=None)[source]

Retrieve the seven day forecast

Parameters:day (str) – Retrieve the Seven Day Forecast for a specific day (optional). format: YYYYMMDD
Return type:dict
handle_options(**kwargs)[source]

Process and store keyword argument options.

locations = {'CONNECTICUT': 4004, 'INTERNALHUB': 4000, 'MAINE': 4001, 'NEMASSBOST': 4008, 'NEWHAMPSHIRE': 4002, 'RHODEISLAND': 4005, 'SEMASS': 4006, 'VERMONT': 4003, 'WCMASS': 4007}
parse_json_load_data(data)[source]

Pull approriate keys from json data set. Raise ValueError if parser fails.

request_endpoints(location_id=None)[source]

Returns a list of endpoints to query, based on handled options

class pyiso.miso.IntervalChoices(hourly, hourly_prelim, fivemin, tenmin, na, dam, dam_exante)
dam

Alias for field number 5

dam_exante

Alias for field number 6

fivemin

Alias for field number 2

hourly

Alias for field number 0

hourly_prelim

Alias for field number 1

na

Alias for field number 4

tenmin

Alias for field number 3

class pyiso.miso.MISOClient(timeout_seconds=30)[source]
MARKET_CHOICES = IntervalChoices(hourly='RTHR', hourly_prelim='RTHR_prelim', fivemin='RT5M', tenmin='RT5M', na='RT5M', dam='DAHR', dam_exante='DAHR_exante')
NAME = 'MISO'
TZ_NAME = 'Etc/GMT+5'
base_url = 'https://api.misoenergy.org/MISORTWDDataBroker/DataBrokerServices.asmx'
docs_url = 'https://docs.misoenergy.org/marketreports/'
fetch_forecast(date)[source]
fuels = {'Coal': 'coal', 'Natural Gas': 'natgas', 'Nuclear': 'nuclear', 'Other': 'other', 'Wind': 'wind'}
get_generation(latest=False, **kwargs)[source]

Scrape and parse generation fuel mix data.

Parameters:
  • latest (bool) – If True, only get the generation mix at the one most recent available time point. Available for all regions.
  • yesterday (bool) – If True, get the generation mix for every time point yesterday. Not available for all regions.
  • start_at (datetime) – If the datetime is naive, it is assummed to be in the timezone of the Balancing Authority. The timestamp of all returned data points will be greater than or equal to this value. If using, must provide both start_at and end_at parameters. Not available for all regions.
  • end_at (datetime) – If the datetime is naive, it is assummed to be in the timezone of the Balancing Authority. The timestamp of all returned data points will be less than or equal to this value. If using, must provide both start_at and end_at parameters. Not available for all regions.
Returns:

List of dicts, each with keys [ba_name, timestamp, freq, market, fuel_name, gen_MW]. Timestamps are in UTC.

Return type:

list

get_latest_fuel_mix()[source]
get_load(latest=False, **kwargs)[source]

Scrape and parse load data.

Parameters:
  • latest (bool) – If True, only get the load at the one most recent available time point. Available for all regions.
  • yesterday (bool) – If True, get the load for every time point yesterday. Not available for all regions.
  • start_at (datetime) – If the datetime is naive, it is assummed to be in the timezone of the Balancing Authority. The timestamp of all returned data points will be greater than or equal to this value. If using, must provide both start_at and end_at parameters. Not available for all regions.
  • end_at (datetime) – If the datetime is naive, it is assummed to be in the timezone of the Balancing Authority. The timestamp of all returned data points will be less than or equal to this value. If using, must provide both start_at and end_at parameters. Not available for all regions.
Returns:

List of dicts, each with keys [ba_name, timestamp, freq, market, load_MW]. Timestamps are in UTC.

Return type:

list

get_trade(latest=False, **kwargs)[source]

Scrape and parse import/export data. Value is net export (export - import), can be positive or negative.

Parameters:
  • latest (bool) – If True, only get the trade at the one most recent available time point. Available for all regions.
  • yesterday (bool) – If True, get the trade for every time point yesterday. Not available for all regions.
  • start_at (datetime) – If the datetime is naive, it is assummed to be in the timezone of the Balancing Authority. The timestamp of all returned data points will be greater than or equal to this value. If using, must provide both start_at and end_at parameters. Not available for all regions.
  • end_at (datetime) – If the datetime is naive, it is assummed to be in the timezone of the Balancing Authority. The timestamp of all returned data points will be less than or equal to this value. If using, must provide both start_at and end_at parameters. Not available for all regions.
Returns:

List of dicts, each with keys [ba_name, timestamp, freq, market, net_exp_MW]. Timestamps are in UTC.

Return type:

list

handle_forecast()[source]
handle_options(**kwargs)[source]

Process and store keyword argument options.

parse_forecast(df)[source]
parse_latest_fuel_mix(content)[source]
class pyiso.pjm.PJMClient(timeout_seconds=30)[source]
NAME = 'PJM'
TZ_NAME = 'America/New_York'
base_dataminer_url = 'https://dataminer.pjm.com/dataminer/rest/public/api'
base_url = 'https://datasnapshot.pjm.com/content/'
fetch_edata_point(data_type, key, header)[source]
fetch_edata_series(data_type, params=None)[source]
fetch_historical_load(year, region_name='RTO')[source]
fetch_markets_operations_soup()[source]
fetch_oasis_data()[source]
fuels = {'Black Liquor': 'other', 'Coal': 'coal', 'Gas': 'natgas', 'Hydro': 'hydro', 'Multiple Fuels': 'thermal', 'Nuclear': 'nuclear', 'Oil': 'oil', 'Other': 'other', 'Other Renewables': 'renewable', 'Solar': 'solar', 'Storage': 'other', 'Wind': 'wind'}
get_generation(latest=False, **kwargs)[source]

Scrape and parse generation fuel mix data.

Parameters:
  • latest (bool) – If True, only get the generation mix at the one most recent available time point. Available for all regions.
  • yesterday (bool) – If True, get the generation mix for every time point yesterday. Not available for all regions.
  • start_at (datetime) – If the datetime is naive, it is assummed to be in the timezone of the Balancing Authority. The timestamp of all returned data points will be greater than or equal to this value. If using, must provide both start_at and end_at parameters. Not available for all regions.
  • end_at (datetime) – If the datetime is naive, it is assummed to be in the timezone of the Balancing Authority. The timestamp of all returned data points will be less than or equal to this value. If using, must provide both start_at and end_at parameters. Not available for all regions.
Returns:

List of dicts, each with keys [ba_name, timestamp, freq, market, fuel_name, gen_MW]. Timestamps are in UTC.

Return type:

list

get_load(latest=False, start_at=None, end_at=None, forecast=False, **kwargs)[source]

Scrape and parse load data.

Parameters:
  • latest (bool) – If True, only get the load at the one most recent available time point. Available for all regions.
  • yesterday (bool) – If True, get the load for every time point yesterday. Not available for all regions.
  • start_at (datetime) – If the datetime is naive, it is assummed to be in the timezone of the Balancing Authority. The timestamp of all returned data points will be greater than or equal to this value. If using, must provide both start_at and end_at parameters. Not available for all regions.
  • end_at (datetime) – If the datetime is naive, it is assummed to be in the timezone of the Balancing Authority. The timestamp of all returned data points will be less than or equal to this value. If using, must provide both start_at and end_at parameters. Not available for all regions.
Returns:

List of dicts, each with keys [ba_name, timestamp, freq, market, load_MW]. Timestamps are in UTC.

Return type:

list

get_trade(latest=False, **kwargs)[source]

Scrape and parse import/export data. Value is net export (export - import), can be positive or negative.

Parameters:
  • latest (bool) – If True, only get the trade at the one most recent available time point. Available for all regions.
  • yesterday (bool) – If True, get the trade for every time point yesterday. Not available for all regions.
  • start_at (datetime) – If the datetime is naive, it is assummed to be in the timezone of the Balancing Authority. The timestamp of all returned data points will be greater than or equal to this value. If using, must provide both start_at and end_at parameters. Not available for all regions.
  • end_at (datetime) – If the datetime is naive, it is assummed to be in the timezone of the Balancing Authority. The timestamp of all returned data points will be less than or equal to this value. If using, must provide both start_at and end_at parameters. Not available for all regions.
Returns:

List of dicts, each with keys [ba_name, timestamp, freq, market, net_exp_MW]. Timestamps are in UTC.

Return type:

list

handle_options(**kwargs)[source]

Process and store keyword argument options.

markets_operations_url = 'http://www.pjm.com/markets-and-operations.aspx'
oasis_url = 'http://oasis.pjm.com/system.htm'
parse_date_from_markets_operations(soup)[source]
parse_date_from_oasis(content)[source]
parse_realtime_genmix(soup)[source]
request(*args, **kwargs)[source]

Get or post to a URL with the provided kwargs. Returns the response, or None if an error was encountered. If the mode is not ‘get’ or ‘post’, raises ValueError.

time_as_of(content)[source]

Returns a UTC timestamp if one is found in the html content, or None if an error was encountered.

zonal_aggregate_nodes = {'AECO': 51291, 'AEP': 8445784, 'APS': 8394954, 'ATSI': 116013753, 'BGE': 51292, 'COMED': 33092371, 'DAY': 34508503, 'DEOK': 124076095, 'DOM': 34964545, 'DPL': 51293}
class pyiso.spp.SPPClient(timeout_seconds=30)[source]
NAME = 'SPP'
TZ_NAME = 'America/Chicago'
base_url = 'https://marketplace.spp.org/web/guest/'
get_fuels(year=2014)[source]