Package: watttime
AboutThis 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 must firstregister for access to the WattTime API here.Full documentation of WattTime's API, along with response samples and information aboutavailable endpoints is also available.ConfigurationThe SDK can be installed as a python package from the PyPi repository, we recommend using an environment manager such asminicondaorvenv.pip install watttimeOnce 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 passingusernameandpasswordwhen instantiating sdk objects. For instance, in the example below, you could replace the second line withwt_myaccess=WattTimeMyAccess()Using the SDKUsers may first want to query the/v3/my-accessendpoint using theWattTimeMyAccessclass to get a dataframe of regions and signal types available to them:fromwatttimeimportWattTimeMyAccesswt_myaccess=WattTimeMyAccess(username,password)# return a nested json describing signals and regions you have access towt_myaccess.get_access_json()# return a pandas dataframe describing signals and regions you have access towt_myaccess.get_access_pandas()Once you confirm your access, you may wish to request data for a particular balancing authority:fromwatttimeimportWattTimeHistoricalwt_hist=WattTimeHistorical(username,password)# get data as a pandas dataframemoers=wt_hist.get_historical_pandas(start='2022-01-01 00:00Z',# ISO 8601 format, UTCend='2023-01-01 00:00Z',# ISO 8601 format, UTCregion='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>.csvwt_hist.get_historical_csv(start='2022-01-01 00:00Z',# ISO 8601 format, UTCend='2023-01-01 00:00Z',# ISO 8601 format, UTCregion='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:fromwatttimeimportWattTimeMyAccess,WattTimeHistoricalimportpandasaspdwt_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()forregioninmoer_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')You can also use the SDK to request a current forecast for some signal types, such as co2_moer and health_damage:fromwatttimeimportWattTimeForecastwt_forecast=WattTimeForecast(username,password)forecast=wt_forecast.get_forecast_json(region='CAISO_NORTH',signal_type='health_damage')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')