watttime 1.4.0

An officially maintained python client for WattTime's API providing access to electricity grid emissions data.

About

This SDK is provided to help users retrieve data from WattTime’s API (version 3) in specific formats (e.g., JSON, pandas, csv). The SDK is open-source with an MIT license. The data retrieved is not open-source, it is subject to a separate license with WattTime. Contact WattTime about obtaining a data license.

Users may register for access to the WattTime API through this client or directly with an API query, however the basic user scoping given upon registration will only allow users to access data for the CAISO_NORTH region, and the 'co2_moer' and 'health_damage' signal types.

See the API docs for full documentation of WattTime's API including information about available endpoints and signals along with response samples.

Configuration

The SDK can be installed as a python package from the PyPi repository, we recommend using an environment manager such as miniconda or venv.

pip install watttime

If you are not registered for the WattTime API, you can do so using the SDK:

from watttime import WattTimeMyAccess

wt = WattTimeMyAccess(username=<USERNAME>, password=<PASSWORD>)
wt.register(email=<EMAIL>, organization=<ORGANIZATION>)

If you are already registered for the WattTime API, you may set your credentials as environment variables to avoid passing these during class initialization:

# linux or mac
export WATTTIME_USER=<your WattTime API username>
export WATTTIME_PASSWORD=<your WattTime API password>

Once you have set your credentials as environment variables, you can omit passing username and password when instantiating sdk objects. For instance, in the example below, you could replace the second line with

wt_myaccess = WattTimeMyAccess()

Using the SDK

Users may first want to query the /v3/my-access endpoint using the WattTimeMyAccess class to get a dataframe of regions and signal types available to them:

from watttime import WattTimeMyAccess

wt_myaccess = WattTimeMyAccess(username, password)

# return a nested json describing signals and regions you have access to
wt_myaccess.get_access_json()

# return a pandas dataframe describing signals and regions you have access to
wt_myaccess.get_access_pandas()

Accessing Historical Data

Once you confirm your access, you may wish to request data for a particular region:

from watttime import WattTimeHistorical

wt_hist = WattTimeHistorical(username, password)

# get data as a pandas dataframe
moers = wt_hist.get_historical_pandas(
    start = '2022-01-01 00:00Z', # ISO 8601 format, UTC
    end = '2023-01-01 00:00Z', # ISO 8601 format, UTC
    region = 'CAISO_NORTH',
    signal_type = 'co2_moer' # ['co2_moer', 'co2_aoer', 'health_damage', etc.]
)

# save data as a csv -> ~/watttime_historical_csvs/<region>_<signal_type>_<start>_<end>.csv
wt_hist.get_historical_csv(
    start = '2022-01-01 00:00Z', # ISO 8601 format, UTC
    end = '2023-01-01 00:00Z', # ISO 8601 format, UTC
    region = 'CAISO_NORTH',
    signal_type = 'co2_moer' # ['co2_moer', 'co2_aoer', 'health_damage', etc.]
)

You could also combine these classes to iterate through all regions where you have access to data:

from watttime import WattTimeMyAccess, WattTimeHistorical
import pandas as pd

wt_myaccess = WattTimeMyAccess(username, password)
wt_hist = WattTimeHistorical(username, password)

access_df = wt_myaccess.get_access_pandas()

moers = pd.DataFrame()
moer_regions = access_df.loc[access_df['signal_type'] == 'co2_moer', 'region'].unique()
for region in moer_regions:
    region_df = wt_hist.get_historical_pandas(
        start = '2022-01-01 00:00Z',
        end = '2023-01-01 00:00Z',
        region = region,
        signal_type = 'co2_moer'
    )
    moers = pd.concat([moers, region_df], axis='rows')

Accessing Real-Time and Historical Forecasts

You can also use the SDK to request a current forecast for some signal types, such as co2_moer and health_damage:

from watttime import WattTimeForecast

wt_forecast = WattTimeForecast(username, password)
forecast = wt_forecast.get_forecast_json(
    region = 'CAISO_NORTH',
    signal_type = 'health_damage'
)

We recommend using the WattTimeForecast class to access data for real-time optimization. The first item of the response from this call is always guaranteed to be an estimate of the signal_type for the current five minute period, and forecasts extend at least 24 hours at a five minute granularity, which is useful for scheduling utilization during optimal times.

Methods also exist to request historical forecasts, however these responses may be slower as the volume of data can be significant:

hist_forecasts = wt_forecast.get_historical_forecast_json(
    start = '2022-12-01 00:00+00:00',
    end = '2022-12-31 23:59+00:00',
    region = 'CAISO_NORTH',
    signal_type = 'health_damage'
)

Accessing Location Data

We provide two methods to access location data:

1. The region_from_loc() method allows users to provide a latitude and longitude coordinates in order to receive the valid region for a given signal type.

2. the WattTimeMaps class provides a get_maps_json() method which returns a GeoJSON object with complete boundaries for all regions available for a given signal type. Note that access to this endpoint is only available for Pro and Analyst subscribers.

from watttime import WattTimeMaps

wt = WattTimeMaps(username, password)

# get BA region for a given location
wt.region_from_loc(
    latitude=39.7522,
    longitude=-105.0,
    signal_type='co2_moer'
)

# get shape files for all regions of a signal type
wt.get_maps_json('co2_moer')

Calculating a Typical Carbon Year (TCY)

The SDK provides functionality to calculate a Typical Carbon Year (TCY) profile, which represents typical MOER patterns over a year by combining three years of historical data. A TCY accounts for seasonal variations, daily patterns, and differences between weekdays and weekends/holidays:

from watttime import TCYCalculator

# Initialize calculator (using env variables for credentials)
calculator = TCYCalculator(
    region="CAISO_NORTH",
    timezone="America/Los_Angeles"
)

# Or with explicit credentials
calculator = TCYCalculator(
    region="CAISO_NORTH",
    timezone="America/Los_Angeles",
    username="your_username",
    password="your_password"
)

# Calculate TCY for any year (uses recent MOER patterns with target year's calendar)
tcy_profile = calculator.calculate_tcy(2024)

The returned tcy_profile is a pandas series with hourly timestamps in the specified timezone and corresponding MOER values (in lbs CO2/MWh). The profile provides hourly values that represent typical grid emissions patterns for the region. Note that this data has a lower variance than real-time MOER data, so it should not be used to estimate the carbon reduction opportunity from load-shifting/AER.

This can be useful for:

• Estimating the relative carbon impact of building design choices
• Understanding typical emissions patterns in a region