lawrencefoley / evergy

A simple utility that you can use to access your Evergy account and retrieve you meter readings.

⚡Evergy Client

A simple utility that you can use to login to your Evergy account and retrieve you meter readings.

• Documentation
• Source Code

Note: This is an unofficial utility that uses Evergy's non-public API.

Previously known as "KCPL"

⚠ No Longer Maintained ⚠

I no longer have an Evergy account so I can't test this. If you would like to become a maintainer (or even just make small fixes) let me know 🙂

Install

pip install evergy

Usage

from evergy.evergy import Evergy

evergy = Evergy("<evergy-username>", "<evergy-password>")

data = evergy.get_usage()
print("Today's kWh: " + str(data[-1]["usage"]))

Output

The last element from the get_usage() will be the latest data. The usage is in kilowatt-hours. I believe the peakDateTime is the time during that day when your usage was the highest and the peakDemand is how many kilowatts you were drawing at that time.

Latest data:
{
    'period': 'Saturday',
    'billStart': '0001-01-01T00:00:00',
    'billEnd': '0001-01-01T00:00:00',
    'billDate': '2021-09-18T00:00:00',
    'date': '9/18/2021',
    'usage': 14.7756,
    'demand': 3.7992,
    'avgDemand': 0.0,
    'peakDemand': 3.7992,
    'peakDateTime': '12:45 p.m.',
    'maxTemp': 71.0,
    'minTemp': 71.0,
    'avgTemp': 71.0,
    'cost': 18.5748, 
    'isPartial': False
}

Home Assistant Integration

There is currently a Home Assistant integration that uses this library. Checkout TheBradleySanders/Evergy.

Related Projects

• KC Water: A similar project developed by Patrick McDonagh. Check it out!

Development

Setup

python -m pip install --upgrade virtualenv
virtualenv venv
.\venv\Scripts\activate.ps1

Code Formatting

Install the dev dependencies and run isort and flake8 to properly format the code.

pip install -r requirements_dev.txt
isort evergy/
flake8 evergy/

Build Docs

Windows PowerShell:

pip install -r docs/requirements_docs.txt
docs\make.bat clean; docs\make.bat html

Release New Version

• Bump __version__ in evergy/__init__.py

git commit -m "Bump version"
git tag -a v1.0.1 -m "v1.0.1"
git push --tags

Build Wheel

The --no-isolation flag tells it to use the existing virtual env

python -m build --no-isolation --wheel

Upload to PyPi

Test

twine upload --verbose --repository testpypi dist/*

Prod

twine upload --verbose --repository pypi dist/*

evergy's Issues

Hourly Usage

Add the ability to retrieve hourly usage. This URL can be used to do that (note the interval parameter). There seems to be some (currently unknown) delay on the hourly data showing up.

https://www.evergy.com/api/report/usage/1111110000?interval=h&from=9/15/2020&to=9/16/2020

Evergy

Since the merger of KCPL the kcpl.com website redirects to evergy.com. Because of this and the new website, the login doesn't work any longer. The other functions probably don't work as well.

Need to either make fixes for this to work with the new website/api or create a new project with a name such as evergy-api.

Once a day data

I'm only getting data once a day now at 6am. Is there some recent updates I need to look for? Poll every hour but only get results once per day.

TIA

Doesn't Pull Back Meter Data

KCPL changed their website to use an API instead of form POSTs to retrieve meter data.

The API URL is in the format: https://www.kcpl.com/api/report/usage/<meterNumber>?interval=d

Handle Maintenance

Evergy has scheduled maintenance on their website sometimes. During the maintenance you get redirected (HTTP 301) to https://www.evergy.com/planned-outage.

The code should be changed to handle this and log an error about the maintenance.

This also seems to happen sometimes late at night, possibly for system patches:

2021-10-13 23:04:26,271 - INFO - root -  - Logging in with username: [email protected]
Traceback (most recent call last):
  File "main.py", line 35, in <module>
    usage = client.get_usage(start=date.today(), end=date.today(), query_scale="mi")
...
  File "/usr/lib/python3.7/json/decoder.py", line 355, in raw_decode
    raise JSONDecodeError("Expecting value", s, err.value) from None
json.decoder.JSONDecodeError: Expecting value: line 1 column 1 (char 0)

Remove HTML Parsing

Right now the code uses HTML parsing to handle the login and for getting the meter ID(s). Research should be done to see if this part can be replaced with just HTTP calls.

Benefits would include:

• simpler code
• less dependencies (Beautiful Soup, lxml)
• possibility of being added to the official Home Assistant repo (they don't allow HTML scraping for authentication)

https://www.evergy.com/api/user/current

Evergy Updated API?

Are you having any issues with this? Mine has stopped working since January 13th, it seems like Evergy might have adjusted their API. I haven't dug into it much, just curious if you're having the same issue. I'm getting an error message like I'm not logged in when running GetUsage.

idk

I don't know if I'm stupid or it no longer works, but I've been beating my head against the wall for a while now. I'm pretty sure it installed, don't know how to import into HA, and running it directly ends up with this:

2021-08-19 06:20:44,360 - INFO - root -  - Logging in with username: [email protected]
2021-08-19 06:20:45,488 - ERROR - root -  - Must login first
Traceback (most recent call last):
  File "./kcpl.py", line 81, in <module>
    logging.info("Last usage data: " + str(data[-1]))
TypeError: 'NoneType' object has no attribute '__getitem__'

Updated URL to get account number

Hello @lawrencefoley ,

Evergy just did a site redesign, and the account number is no longer where it used to be.

I know you are no longer maintaining this project, but I've found a new way to get the account number and could put in a pull request if you're willing to review/merge.

Thanks.

Archive this repository?

It looks like Evergy is has replaced the API implemented here with the Oracle's Utilities Opower API, and there's an existing library that implements its *.opower.com API calls here: https://github.com/tronikos/opower

I'd suggest archiving this repository with a note with how this implementation has been superseded by new stuff.

Thanks for your work on this repo! I've been using this implementation for a while.

Home Assistant Integration

I've been trying to figure out your code here. I'm not very good with these kinds of things, but really was hoping to get this implemented in Home Assistant. I've tried a few different methods mentioned in other issues like this one -> #8

Is there a more clear "how-to" documentation on how to get this integrated into Home Assistant? Can anyone that has effectively done so create a video or share more details on how you integrated it?