关于

此SDK旨在帮助用户对WattTime API（版本3）进行基本查询，并获取以特定格式返回的数据（例如，JSON、pandas、csv）。

用户可以通过此客户端注册访问WattTime API，但基本用户范围仅允许新注册用户访问CAISO_NORTH地区的数据。此外，新注册用户可能无法访问所有信号类型的数据。

WattTime API的完整文档，包括响应样本和有关可用端点的信息也可用。

配置

SDK可以作为从PyPi存储库安装的Python包，我们建议使用环境管理器，如miniconda或venv。

pip install watttime

如果您尚未注册WattTime API，可以使用SDK进行注册

from watttime import WattTimeMyAccess

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

如果您已注册WattTime API，您可以将其凭据设置为环境变量，以避免在类初始化期间传递这些凭据

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

一旦将凭据设置为环境变量，您可以在实例化sdk对象时省略传递username和password。例如，在下面的示例中，您可以将第二行替换为

wt_myaccess = WattTimeMyAccess()

使用SDK

用户可能首先希望使用WattTimeMyAccess类查询/v3/my-access端点，以获取他们可用的区域和信号类型的数据框

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()

访问历史数据

一旦确认您的访问权限，您可以请求特定区域的数据

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.]
)

您也可以将这些类组合起来遍历您有权访问数据的所有区域

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')

访问实时和历史预测

您还可以使用SDK请求某些信号类型（如co2_moer和health_damage）的当前预测

from watttime import WattTimeForecast

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

我们建议使用 WattTimeForecast 类来访问实时优化所需的数据。此调用响应的第一项始终保证是当前五分钟周期的信号_type的估计值，并且预测至少以五分钟粒度扩展24小时，这对在最佳时间安排利用度非常有用。

也存在方法来请求历史预测，但是这些响应可能较慢，因为数据量可能很大。

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'
)

访问位置数据

我们提供了两种访问位置数据的方法。

1. region_from_loc() 方法允许用户提供纬度和经度坐标，以接收给定信号类型的有效区域。

2. WattTimeMaps 类提供了一个 get_maps_json() 方法，该方法返回一个包含所有给定信号类型可用区域完整边界的 GeoJSON 对象。请注意，此端点的访问仅限于专业和分析订阅者。

from watttime import WattTimeMaps

wt = WattTimeMaps()

# 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')