isone_api

isone_api#

Module Contents#

Classes Summary#

ISONEAPI

Class to authenticate with and make requests to the ISO New England API.

Attributes Summary#

`DEFAULT_PAGE_SIZE`
`EXCLUDE_FROM_REALTIME_HOURLY_DEMAND`
`ZONE_LOCATIONID_MAP`

Contents#

gridstatus.isone_api.isone_api.DEFAULT_PAGE_SIZE = 1000[source]#

gridstatus.isone_api.isone_api.EXCLUDE_FROM_REALTIME_HOURLY_DEMAND = ['NEPOOL AREA', '.H.INTERNALHUB'][source]#

class gridstatus.isone_api.isone_api.ISONEAPI(sleep_seconds: float = 5, max_retries: int = 3)[source]#

Class to authenticate with and make requests to the ISO New England API.

To authenticate, you need a username and password.

To register, create an account here: https://www.iso-ne.com/participate/applications-status-changes/access-software-systems#ws-api

Attributes

base_url	‘https://webservices.iso-ne.com/api/v1.1’
default_timezone	‘US/Eastern’
initial_delay	None
max_retries	None
password	None
sleep_seconds	5
username	None

Methods

`get_ancillary_services_strike_prices_day_ahead`(...)	Get day-ahead strike prices and close-out components for ISO-NE.
`get_binding_constraints_day_ahead_hourly`(...)
`get_binding_constraints_final_real_time_15_min`(...)
`get_binding_constraints_final_real_time_5_min`(...)
`get_binding_constraints_preliminary_real_time_15_min`(...)
`get_binding_constraints_preliminary_real_time_5_min`(...)
`get_capacity_forecast_7_day`(→ pandas.DataFrame)	Get the capacity forecast for the next 7 days.
`get_dayahead_hourly_demand`(→ pandas.DataFrame)	Get the day-ahead hourly demand data for specified locations and date range.
`get_external_flows_5_min`(→ pandas.DataFrame)	Get the five minute external flow data for specified date range.
`get_fcm_reconfiguration_annual`(→ pandas.DataFrame)	Get FCM Annual Reconfiguration Auction data for all three auctions (ARA1, ARA2, ARA3).
`get_fcm_reconfiguration_monthly`(→ pandas.DataFrame)	Get FCM Monthly Reconfiguration Auction data.
`get_fuel_mix`(→ pandas.DataFrame)	Return fuel mix data for the specified date range
`get_interchange_15_min`(→ pandas.DataFrame)	Get the fifteen minute interchange data for specified date range.
`get_interchange_hourly`(→ pandas.DataFrame)	Get the hourly interchange data for specified date range. Hourly data includes
`get_lmp_real_time_5_min_final`(→ pandas.DataFrame)	Get the real-time 5 minute LMP final data for specified date range.
`get_lmp_real_time_5_min_prelim`(→ pandas.DataFrame)	Get the real-time 5 minute LMP preliminary data for specified date range.
`get_lmp_real_time_hourly_final`(→ pandas.DataFrame)	Get the real-time hourly LMP data for specified date range.
`get_lmp_real_time_hourly_prelim`(→ pandas.DataFrame)	Get the real-time hourly LMP data for specified date range.
`get_load_forecast_hourly`(→ pandas.DataFrame)	Get the hourly load forecast data for specified locations and date range.
`get_load_hourly`(→ pandas.DataFrame)	Return hourly load data for a given date or date range
`get_location_by_id`(→ pandas.DataFrame)	Get information for a specific location by its ID.
`get_locations`(→ pandas.DataFrame)	Get a list of core hub and zone locations.
`get_locations_all`(→ pandas.DataFrame)	Get detailed information for all locations.
`get_marginal_fuel_type`(→ pandas.DataFrame)	Return marginal-fuel flags per timestamp, one boolean column per fuel type.
`get_realtime_hourly_demand`(→ pandas.DataFrame)	Get the real-time hourly demand data for specified locations and date range.
`get_regulation_clearing_prices_real_time_5_min`(...)	Get five-minute clearing prices for both regulation capacity and service in real-time.
`get_reliability_region_load_forecast`(→ pandas.DataFrame)	Get the regional load forecast data for specified date range and vintages.
`get_reserve_requirements_prices_forecast_day_ahead`(...)	Get day-ahead reserve prices, requirements, and forecast for reserve zone 7000 (system-wide).
`get_reserve_zone_prices_designations_real_time_5_min`(...)	Get five-minute real-time reserve prices, requirements, and designations by zone.
`get_reserve_zone_prices_designations_real_time_hourly_final`(...)	Get final hourly reserve prices, requirements, and designations by zone.
`get_reserve_zone_prices_designations_real_time_hourly_prelim`(...)	Get preliminary hourly reserve prices, requirements, and designations by zone.
`get_total_demand`(→ pandas.DataFrame)	Get five-minute system load ("total demand") data.
`get_zonal_load_estimated_5_min`(→ pandas.DataFrame)	Get five-minute estimated zonal load data for all load zones.
`make_api_call`(url[, api_params, parse_json, verbose])
`parse_problematic_datetime`(→ datetime.datetime)

get_ancillary_services_strike_prices_day_ahead(date: str | pandas.Timestamp | Literal['latest'], end: pandas.Timestamp | None = None, verbose: bool = False) → pandas.DataFrame[source]#

Get day-ahead strike prices and close-out components for ISO-NE.

Parameters:

date (pd.Timestamp | Literal["latest"]) – The start date for the data request. Use “latest” for most recent data.
end (pd.Timestamp | None) – The end date for the data request. Only used if date is not “latest”.
verbose (bool) – Whether to print verbose logging information.

Returns:

A DataFrame containing day-ahead strike prices and related data.

Return type:

pd.DataFrame

get_binding_constraints_day_ahead_hourly(date: str | pandas.Timestamp | tuple[pandas.Timestamp, pandas.Timestamp], end: str | pandas.Timestamp | tuple[pandas.Timestamp, pandas.Timestamp] | None = None, verbose: bool = False) → pandas.DataFrame[source]#

get_binding_constraints_final_real_time_15_min(date: str | pandas.Timestamp | tuple[pandas.Timestamp, pandas.Timestamp], end: str | pandas.Timestamp | tuple[pandas.Timestamp, pandas.Timestamp] | None = None, verbose: bool = False) → pandas.DataFrame[source]#

get_binding_constraints_final_real_time_5_min(date: str | pandas.Timestamp | tuple[pandas.Timestamp, pandas.Timestamp], end: str | pandas.Timestamp | tuple[pandas.Timestamp, pandas.Timestamp] | None = None, verbose: bool = False) → pandas.DataFrame[source]#

get_binding_constraints_preliminary_real_time_15_min(date: str | pandas.Timestamp | tuple[pandas.Timestamp, pandas.Timestamp], end: str | pandas.Timestamp | tuple[pandas.Timestamp, pandas.Timestamp] | None = None, verbose: bool = False) → pandas.DataFrame[source]#

get_binding_constraints_preliminary_real_time_5_min(date: str | pandas.Timestamp | tuple[pandas.Timestamp, pandas.Timestamp], end: str | pandas.Timestamp | tuple[pandas.Timestamp, pandas.Timestamp] | None = None, verbose: bool = False) → pandas.DataFrame[source]#

get_capacity_forecast_7_day(date: str | pandas.Timestamp = 'latest', end: str | pandas.Timestamp | None = None, verbose: bool = False) → pandas.DataFrame[source]#: Get the capacity forecast for the next 7 days.

get_dayahead_hourly_demand(date: str | pandas.Timestamp = 'latest', end: str | pandas.Timestamp | None = None, locations: list[str] = None, verbose: bool = False) → pandas.DataFrame[source]#

Get the day-ahead hourly demand data for specified locations and date range.

Parameters:

date (str) – The start date for the data request. Use “latest” for most recent data.
end_date (str | None) – The end date for the data request. Only used if date is not “latest”.
locations (list[str], optional) – List of specific location names to request data for. If None, data for all locations will be retrieved.

Returns:

A DataFrame containing the day-ahead hourly demand data for all requested locations.

Return type:

pandas.DataFrame

get_external_flows_5_min(date: str | pandas.Timestamp = 'latest', end: str | pandas.Timestamp | None = None, verbose: bool = False) → pandas.DataFrame[source]#

Get the five minute external flow data for specified date range.

Parameters:

date (str) – The start date for the data request. Use “latest” for most
data. (recent)
end_date (str | None) – The end date for the data request. Only used if date
"latest". (is not)

Returns:

A DataFrame containing the external flow five minute data for all requested locations.

Return type:

pandas.DataFrame

get_fcm_reconfiguration_annual(date: str | pandas.Timestamp = 'latest', end: str | pandas.Timestamp | None = None, verbose: bool = False) → pandas.DataFrame[source]#

Get FCM Annual Reconfiguration Auction data for all three auctions (ARA1, ARA2, ARA3).

Queries the API for all three annual reconfiguration auctions using the endpoint /fcmara/cp/{cp}/ara/{ARA} where {ARA} can be ARA1, ARA2, or ARA3.

Parameters:

date (str | pd.Timestamp) – The start date for the data request. Use “latest” for most recent data.
end (str | pd.Timestamp | None) – The end date for the data request. Only used if date is not “latest”.
verbose (bool) – Whether to print verbose logging information.

Returns:

A DataFrame containing annual reconfiguration auction data with an “ARA”: column with values 1, 2, or 3 distinguishing between ARA1, ARA2, and ARA3. Note that not all three auctions may exist for all commitment periods (e.g., ARA3 may not exist yet for recent periods).

Return type:

pd.DataFrame

get_fcm_reconfiguration_monthly(date: str | pandas.Timestamp = 'latest', end: str | pandas.Timestamp | None = None, verbose: bool = False) → pandas.DataFrame[source]#

Get FCM Monthly Reconfiguration Auction data.

Parameters:

date (str | pd.Timestamp) – The start date for the data request. Use “latest” for most recent data.
end (str | pd.Timestamp | None) – The end date for the data request. Only used if date is not “latest”.
verbose (bool) – Whether to print verbose logging information.

Returns:

A DataFrame containing monthly reconfiguration auction data.

Return type:

pd.DataFrame

get_fuel_mix(date: str | pandas.Timestamp = 'latest', end: str | pandas.Timestamp | None = None, verbose: bool = False) → pandas.DataFrame[source]#

Return fuel mix data for the specified date range

Parameters:

date (str | pd.Timestamp) – The start date for the data request. Use “latest” for most recent data.
end (str | pd.Timestamp | None) – The end date for the data request. Only used if date is not “latest”.
verbose (bool) – Whether to print verbose logging information.

Returns:

DataFrame containing fuel mix data with timestamps and generation by fuel type

Return type:

pd.DataFrame

get_interchange_15_min(date: str | pandas.Timestamp = 'latest', end: str | pandas.Timestamp | None = None, verbose: bool = False) → pandas.DataFrame[source]#

Get the fifteen minute interchange data for specified date range.

Parameters:

date (str) – The start date for the data request. Use “latest” for most
data. (recent)
end_date (str | None) – The end date for the data request. Only used if date
"latest". (is not)

Returns:

A DataFrame containing the interchange fifteen minute data for all requested locations.

Return type:

pandas.DataFrame

get_interchange_hourly(date: str | pandas.Timestamp = 'latest', end: str | pandas.Timestamp | None = None, verbose: bool = False) → pandas.DataFrame[source]#

Get the hourly interchange data for specified date range. Hourly data includes multiple locations.

Parameters:

date (str) – The start date for the data request. Use “latest” for most
data. (recent)
end_date (str | None) – The end date for the data request. Only used if date
"latest". (is not)

Returns:

A DataFrame containing the interchange fifteen minute data for all requested locations.

Return type:

pandas.DataFrame

get_lmp_real_time_5_min_final(date: str | pandas.Timestamp | tuple[pandas.Timestamp, pandas.Timestamp], end: str | pandas.Timestamp | None = None, verbose: bool = False) → pandas.DataFrame[source]#

Get the real-time 5 minute LMP final data for specified date range.

Parameters:

date (str | pd.Timestamp | tuple[pd.Timestamp, pd.Timestamp]) – The start date for the data request. Use “latest” for most recent data.
end (str | pd.Timestamp | None) – The end date for the data request. Only used if date is not “latest”.
verbose (bool) – Whether to print verbose logging information.

Returns:

A DataFrame containing the real-time 5 minute LMP final data.

Return type:

pd.DataFrame

get_lmp_real_time_5_min_prelim(date: str | pandas.Timestamp | tuple[pandas.Timestamp, pandas.Timestamp], end: str | pandas.Timestamp | None = None, verbose: bool = False) → pandas.DataFrame[source]#

Get the real-time 5 minute LMP preliminary data for specified date range.

Parameters:

date (str | pd.Timestamp | tuple[pd.Timestamp, pd.Timestamp]) – The start date for the data request. Use “latest” for most recent data.
end (str | pd.Timestamp | None) – The end date for the data request. Only used if date is not “latest”.
verbose (bool) – Whether to print verbose logging information.

Returns:

A DataFrame containing the real-time 5 minute LMP preliminary data.

Return type:

pd.DataFrame

get_lmp_real_time_hourly_final(date: str | pandas.Timestamp = 'latest', end: str | pandas.Timestamp | None = None, verbose: bool = False) → pandas.DataFrame[source]#

Get the real-time hourly LMP data for specified date range.

Parameters:

date (str | pd.Timestamp) – The start date for the data request. Use “latest” for most
data. (recent)
end_date (str | pd.Timestamp | None) – The end date for the data request. Only used if date
"latest". (is not)

Returns:

A DataFrame containing the real-time hourly LMP data.

Return type:

pandas.DataFrame

get_lmp_real_time_hourly_prelim(date: str | pandas.Timestamp = 'latest', end: str | pandas.Timestamp | None = None, verbose: bool = False) → pandas.DataFrame[source]#

Get the real-time hourly LMP data for specified date range.

Parameters:

date (str | pd.Timestamp) – The start date for the data request. Use “latest” for most
data. (recent)
end_date (str | pd.Timestamp | None) – The end date for the data request. Only used if date
"latest". (is not)

Returns:

A DataFrame containing the real-time hourly LMP data.

Return type:

pandas.DataFrame

get_load_forecast_hourly(date: str | pandas.Timestamp = 'latest', end: str | pandas.Timestamp | None = None, vintage: Literal['latest', 'all'] = 'all', verbose: bool = False) → pandas.DataFrame[source]#

Get the hourly load forecast data for specified locations and date range.

NB: ISO NE publishes load forecasts roughly every 30 minutes for the next 48-72 future intervals. Getting all forecasts (all “vintages”) can be a lot of data, potentially thousands of rows for a single day. Sometimes you may want this, and that’s why ISO NE provides the option to get all vintages, but you may be most interested in the most recent forecast for a given historical interval, essentially the shortest vintages, most accurate forecast, which they also provide. All vintages is typically 5x to 20x more data than latest, so it’s something to consider when making a request.

Giving the option for just the “latest” forecast (aka shortest horizon, aka most recent publish time/vintage) for a given historical interval avoids this large data pull and collation since ISO NE API has done that work for you already.

Parameters:

date (str) – The start date for the data request. Use “latest” for most recent data.
end_date (str | None) – The end date for the data request. Only used if date is not “latest”.
vintage (Literal["latest", "all"]) – The vintage for the data request. Options are “latest” or “all”, defaults to “all”.

Returns:

A DataFrame containing the hourly load forecast data for the system.

Return type:

pandas.DataFrame

get_load_hourly(date: str | pandas.Timestamp, end: str | pandas.Timestamp = None, verbose: bool = False) → pandas.DataFrame[source]#

Return hourly load data for a given date or date range

Parameters:

date (str | pd.Timestamp) – The start date for the data request. Use “latest” for most recent data.
end (str | pd.Timestamp, optional) – The end date for the data request. Only used if date is not “latest”.
locations (list[str], optional) – List of specific location names to request data for. If None, data for all locations will be retrieved.
verbose (bool, optional) – Whether to print verbose logging information.

Returns:

DataFrame containing load data with timestamps and load

Return type:

pd.DataFrame

get_location_by_id(location_id: int) → pandas.DataFrame[source]#

Get information for a specific location by its ID.

Parameters:: location_id (int) – The ID of the location to retrieve.
Returns:: A DataFrame containing the location information.
Return type:: pandas.DataFrame

get_locations() → pandas.DataFrame[source]#

Get a list of core hub and zone locations.

Returns:: A DataFrame containing location information.
Return type:: pandas.DataFrame

get_locations_all() → pandas.DataFrame[source]#

Get detailed information for all locations.

Returns:: A DataFrame containing detailed information for all locations.
Return type:: pandas.DataFrame

get_marginal_fuel_type(date: str | pandas.Timestamp = 'latest', end: str | pandas.Timestamp | None = None, verbose: bool = False) → pandas.DataFrame[source]#

Return marginal-fuel flags per timestamp, one boolean column per fuel type.

Parameters:

date (str | pd.Timestamp) – The start date for the data request. Use “latest” for most recent data.
end (str | pd.Timestamp | None) – The end date for the data request. Only used if date is not “latest”.
verbose (bool) – Whether to print verbose logging information.

Returns:

One row per timestamp. Column “Time” plus one boolean: column per fuel category (e.g. “Natural Gas”, “Solar”). True means the fuel was marginal at that timestamp; missing (timestamp, fuel) pairs and timestamps with no marginal fuel are False.

Return type:

pd.DataFrame

get_realtime_hourly_demand(date: str | pandas.Timestamp = 'latest', end: str | pandas.Timestamp | None = None, locations: list[str] = None, verbose: bool = False) → pandas.DataFrame[source]#

Get the real-time hourly demand data for specified locations and date range.

Parameters:

date (str) – The start date for the data request. Use “latest” for most recent data.
end_date (str | None) – The end date for the data request. Only used if date is not “latest”.
locations (list[str], optional) – List of specific location names to request data for. If None, data for all locations will be retrieved.

Returns:

A DataFrame containing the real-time hourly demand data for all requested locations.

Return type:

pandas.DataFrame

get_regulation_clearing_prices_real_time_5_min(date: str | pandas.Timestamp | Literal['latest'], end: pandas.Timestamp | None = None, verbose: bool = False) → pandas.DataFrame[source]#

Get five-minute clearing prices for both regulation capacity and service in real-time.

Parameters:

date (pd.Timestamp | Literal["latest"]) – The start date for the data request. Use “latest” for most recent data.
end (pd.Timestamp | None) – The end date for the data request. Only used if date is not “latest”.
verbose (bool) – Whether to print verbose logging information.

Returns:

A DataFrame containing five-minute regulation clearing prices.

Return type:

pd.DataFrame

get_reliability_region_load_forecast(date: str | pandas.Timestamp = 'latest', end: str | pandas.Timestamp | None = None, vintage: Literal['latest', 'all'] = 'all', verbose: bool = False) → pandas.DataFrame[source]#

Get the regional load forecast data for specified date range and vintages.

Parameters:

date (str) – The start date for the data request. Use “latest” for most recent data.
end (str | None) – The end date for the data request. Only used if date is not “latest”.
vintages (Literal["latest", "all"]) – The vintage for the data request. Options are “latest” or “all”.

Returns:

A DataFrame containing the regional load forecast data for all requested locations.

Return type:

pandas.DataFrame

get_reserve_requirements_prices_forecast_day_ahead(date: str | pandas.Timestamp | Literal['latest'], end: pandas.Timestamp | None = None, verbose: bool = False) → pandas.DataFrame[source]#

Get day-ahead reserve prices, requirements, and forecast for reserve zone 7000 (system-wide).

Parameters:

date (pd.Timestamp | Literal["latest"]) – The start date for the data request. Use “latest” for most recent data.
end (pd.Timestamp | None) – The end date for the data request. Only used if date is not “latest”.
verbose (bool) – Whether to print verbose logging information.

Returns:

A DataFrame containing day-ahead reserve requirements, prices, and forecast.

Return type:

pd.DataFrame

get_reserve_zone_prices_designations_real_time_5_min(date: str | pandas.Timestamp | Literal['latest'], end: pandas.Timestamp | None = None, verbose: bool = False) → pandas.DataFrame[source]#

Get five-minute real-time reserve prices, requirements, and designations by zone.

Parameters:

date (pd.Timestamp | Literal["latest"]) – The start date for the data request. Use “latest” for most recent data.
end (pd.Timestamp | None) – The end date for the data request. Only used if date is not “latest”.
verbose (bool) – Whether to print verbose logging information.

Returns:

A DataFrame containing five-minute reserve zone prices and designations.

Return type:

pd.DataFrame

get_reserve_zone_prices_designations_real_time_hourly_final(date: str | pandas.Timestamp | Literal['latest'], end: pandas.Timestamp | None = None, verbose: bool = False) → pandas.DataFrame[source]#

Get final hourly reserve prices, requirements, and designations by zone.

Parameters:

date (pd.Timestamp | Literal["latest"]) – The start date for the data request. Use “latest” for most recent data.
end (pd.Timestamp | None) – The end date for the data request. Only used if date is not “latest”.
verbose (bool) – Whether to print verbose logging information.

Returns:

A DataFrame containing final hourly reserve zone prices and designations.

Return type:

pd.DataFrame

get_reserve_zone_prices_designations_real_time_hourly_prelim(date: str | pandas.Timestamp | Literal['latest'], end: pandas.Timestamp | None = None, verbose: bool = False) → pandas.DataFrame[source]#

Get preliminary hourly reserve prices, requirements, and designations by zone.

Parameters:

date (pd.Timestamp | Literal["latest"]) – The start date for the data request. Use “latest” for most recent data.
end (pd.Timestamp | None) – The end date for the data request. Only used if date is not “latest”.
verbose (bool) – Whether to print verbose logging information.

Returns:

A DataFrame containing preliminary hourly reserve zone prices and designations.

Return type:

pd.DataFrame

get_total_demand(date: str | pandas.Timestamp | Literal['latest'], end: str | pandas.Timestamp | None = None, verbose: bool = False) → pandas.DataFrame[source]#

Get five-minute system load (“total demand”) data.

Includes Total Load, Native Load, Storage Load, and the behind-the-meter (estimated solar) variants, as reported by the ISO-NE /fiveminutesystemload web service endpoint.

Parameters:

date (pd.Timestamp | Literal["latest"]) – The start date for the data request. Use “latest” for most recent data.
end (pd.Timestamp | None) – The end date for the data request. Only used if date is not “latest”.
verbose (bool) – Whether to print verbose logging information.

Returns:

A DataFrame containing five-minute total demand data.

Return type:

pd.DataFrame

get_zonal_load_estimated_5_min(date: str | pandas.Timestamp | Literal['latest'], end: str | pandas.Timestamp | None = None, verbose: bool = False) → pandas.DataFrame[source]#

Get five-minute estimated zonal load data for all load zones.

Parameters:

date (pd.Timestamp | Literal["latest"]) – The start date for the data request. Use “latest” for most recent data.
end (pd.Timestamp | None) – The end date for the data request. Only used if date is not “latest”.
verbose (bool) – Whether to print verbose logging information.

Returns:

A DataFrame containing five-minute estimated zonal load data.

Return type:

pd.DataFrame

make_api_call(url: str, api_params: dict = None, parse_json: bool = True, verbose: bool = False)[source]#

parse_problematic_datetime(date_string: str | pandas.Timestamp) → datetime.datetime[source]#

gridstatus.isone_api.isone_api.ZONE_LOCATIONID_MAP[source]#