Package: utility-bill-scraper
Utility bill scraperDownload energy usage data and estimate CO2emissions from utility websites or pdf bills.What is this?The science is clear — global temperatures are rising and we need to drastically reduce our use of fossil fuels if we want to keep our planet habitable for future generations. Many governments around the world are declaringclimate emergenciesand are setting ambitious targets to reduce emissions (e.g.,net zero by 2050,50% reduction by 2030). While broad systemic changes are clearly required, individual action is also important. For those living in theGlobal North, the majority of fossil-fuel emissions arise from heating/cooling our homes, using electricity, transportation, and the food we eat. It's obvious that we need to rapidly transition off fossil fuels, which will require (1)clear targets, (2)a plan to achieve them, and (3)tools for measuring progress.There aremanyexistingcarbonfootprintcalculators, but they often require manual data entry, leading most people to try them once to get a static snapshot at a point in time. While useful for gaining a high-level understanding of your personal emission sources, it would be much better if this footprint could be automatically updated over time to provide people withfeedbackon the impact of their actions. This project aims to do just that — to assist individuals with collecting data from utility companies (e.g., electricity and natural gas) by automatically downloading their data and converting usage into CO2emissions.Table of contentsSupported utilitiesInstallData storageGetting and plotting data using the Python APIUpdate dataPlot monthly gas consumptionConvert gas consumption to CO2emissionsPlot Annual CO2emissionsCommand line utilitiesUpdate dataExport dataOptionsEnvironment variablesContributorsSupported utilitiesThe simplest way to get started is to click on one of the following links, which will open a session onhttps://mybinder.orgwhere you can try downloading some data.Note: after you click on the link, it will take a couple of minutes to load an interactive Jupyter notebook.Then follow the instructions (e.g., provide yourusernameandpassword) to run the notebook directly from your browser.Kitchener Utilities (gas & water)Kitchener-Wilmot HydroInstallpipinstallutility-bill-scraperData storageAll data is stored in a file located at$DATA_PATH/$UTILITY_NAME/monthly.csv. The path to this file can be set as input argument when initializing an API object via thedata_pathargument.└───data
    └───Kitchener Utilities
        └───monthly.csv
        └───statements
            │───2021-10-18 - Kitchener Utilities - $102.30.pdf
            ...
            └───2021-06-15 - Kitchener Utilities - $84.51.pdfGetting and plotting data using the Python APIUpdate dataimportutility_bill_scraper.canada.on.kitchener_utilitiesaskuapi=ku.KitchenerUtilitiesAPI(username='username',password='password')# Get new statements.updates=api.update()ifupdatesisnotNone:print(f"{len(updates)}statements_downloaded")api.history("monthly").tail()Plot monthly gas consumptionimportmatplotlib.pyplotaspltdf=ku_api.history("monthly")plt.figure()plt.bar(df.index,df["Gas Consumption"],width=0.9,alpha=0.5)plt.xticks(rotation=90)plt.title("Monthly Gas Consumption")plt.ylabel("m$^3$")Convert gas consumption to CO2emissionsfromutility_bill_scraperimportGAS_KGCO2_PER_CUBIC_METERdf["kgCO2"]=df["Gas Consumption"]*GAS_KGCO2_PER_CUBIC_METERPlot Annual CO2emissionsfromutility_bill_scraperimportGAS_KGCO2_PER_CUBIC_METERdf["kgCO2"]=df["Gas Consumption"]*GAS_KGCO2_PER_CUBIC_METERdf["year"]=[int(x[0:4])forxindf.index]df["month"]=[int(x[5:7])forxindf.index]plt.figure()df.groupby("year").sum()["Gas Consumption"].plot.bar(width=bin_width,alpha=alpha)plt.ylabel("m$^3$")ylim=plt.ylim()ax=plt.gca()ax2=ax.twinx()plt.ylabel("tCO$_2$e")plt.ylim([GAS_KGCO2_PER_CUBIC_METER*y/1e3foryinylim])plt.title("Annual CO$_2$e emissions from natural gas")Command line utilitiesUpdate and export your utility data from the command line.Update data>ubs--utilty-name"Kitchener Utilities"update--user$USER--password$PASSWORDExport data>ubs--utilty-name"Kitchener Utilities"export--outputmonthly.csvOptions>ubs--help
usage:ubs[-h][-eENV][--data-pathDATA_PATH][--utility-nameUTILITY_NAME][--google-sa-credentialsGOOGLE_SA_CREDENTIALS]{update,export}...

ubs(Utilitybillscraper)optionalarguments:-h,--helpshowthishelpmessageandexit-eENV,--envENVpathto.envfile--data-pathDATA_PATHfoldercontainingthedatafileandstatements--utility-nameUTILITY_NAMEnameoftheutility--google-sa-credentialsGOOGLE_SA_CREDENTIALSgoogleserviceaccountcredentials

subcommands:{update,export}availablesub-commandsEnvironment variablesNote that many options can be set via environment variables (useful for continuous integration and/or working with containers). The following can be set in your shell or via a.envfile passed using the-eoption.DATA_PATH="folder containing the data file and statements"UTILITY_NAME="name of the utility"GOOGLE_SA_CREDENTIALS="google service account credentials"USER="username"PASSWORD="password"SAVE_STATEMENTS="save downloaded statements (default=True)"MAX_DOWNLOADS="maximum number of statements to download"ContributorsRyan Fobel (@ryanfobel)