Skip to main content

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

Project description

About

This SDK is meant to help users with basic queries to WattTime’s API (version 3), and to get data returned in specific formats (e.g., JSON, pandas, csv).

Users may register for access to the WattTime API through this client, however the basic user scoping given will only allow newly registered users to access data for the CAISO_NORTH region. Additionally, data may not be available for all signal types for newly registered users.

Full documentation of WattTime's API, along with response samples and information about available endpoints is also available.

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

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

watttime-1.3.2.tar.gz (15.2 kB view details)

Uploaded Source

Built Distribution

watttime-1.3.2-py3-none-any.whl (10.2 kB view details)

Uploaded Python 3

File details

Details for the file watttime-1.3.2.tar.gz.

File metadata

  • Download URL: watttime-1.3.2.tar.gz
  • Upload date:
  • Size: 15.2 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/4.0.2 CPython/3.11.11

File hashes

Hashes for watttime-1.3.2.tar.gz
Algorithm Hash digest
SHA256 c15003b5f27ae3fe241e8f18129b2ff7737a1d73811266b74a56343ef72d6404
MD5 4a57db6b257e592d4db5b4ff7b2b22c3
BLAKE2b-256 05ea1aa622667f38c33535cee2844747b5fe8a583277eef922ae83d37d555184

See more details on using hashes here.

File details

Details for the file watttime-1.3.2-py3-none-any.whl.

File metadata

  • Download URL: watttime-1.3.2-py3-none-any.whl
  • Upload date:
  • Size: 10.2 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/4.0.2 CPython/3.11.11

File hashes

Hashes for watttime-1.3.2-py3-none-any.whl
Algorithm Hash digest
SHA256 8f13d462c65609268c8edfcbd52a285a9090dbe7b319239e96213c56482c61a1
MD5 4dea5145e1a02b577eae7b0cf58bdaa7
BLAKE2b-256 fffef0ba6ba05a5e2aa31eadf289bf842d6370bb97b588951b307a5cd618d2d1

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page