# Tauron eLicznik Scraper
This Python 3 package allows to read electric energy meter reading history from the
[Tauron eLicznik](https://elicznik.tauron-dystrybucja.pl/) website.
## Installation
The package can be installed using pip:
```
$ pip3 install elicznik
```
or alternatively:
```
$ pip3 install git@github.com:mlesniew/elicznik.git
```
## Command line usage
With the package installed readings can be retrieved by simply running the `elicznik` command:
```
usage: elicznik [-h] [--format {table,csv}] [--api {chart,csv}] [--site SITE] username password [start_date] [end_date]
positional arguments:
username tauron-dystrybucja.pl user name
password tauron-dystrybucja.pl password
start_date Start date of date range to be retrieved, in ISO8601 format. If the end date is omitted, it's the only date for which measurements are retrieved.
end_date End date of date range to be retrieved, inclusive, in ISO8601 format. Can be omitted to only retrieve a single day's measurements.
options:
-h, --help show this help message and exit
--format {table,csv} Specify the output format
--api {chart,csv} Specify which Tauron API to use to get the measurements
--site SITE site identifier, must match '[0-9]+_[0-9]+_[0-9]+'
(venv) ~/src/elicznik (site) $ elicznik --help | cat
usage: elicznik [-h] [--format {table,csv}] [--api {chart,csv}] [--site SITE]
username password [start_date] [end_date]
positional arguments:
username tauron-dystrybucja.pl user name
password tauron-dystrybucja.pl password
start_date Start date of date range to be retrieved, in ISO8601
format. If the end date is omitted, it's the only date
for which measurements are retrieved.
end_date End date of date range to be retrieved, inclusive, in
ISO8601 format. Can be omitted to only retrieve a
single day's measurements.
options:
-h, --help show this help message and exit
--format {table,csv} Specify the output format
--api {chart,csv} Specify which Tauron API to use to get the
measurements
--site SITE site identifier, must match '[0-9]+_[0-9]+_[0-9]+'
```
### Example
```
$ elicznik freddy@example.com secretpassword 2022-07-20
timestamp consumed produced net consumption net production
------------------- ---------- ---------- ----------------- ----------------
2022-07-20 00:00:00 0.133 0 0.133 0
2022-07-20 01:00:00 0.127 0 0.127 0
2022-07-20 02:00:00 0.119 0 0.119 0
2022-07-20 03:00:00 0.119 0 0.119 0
2022-07-20 04:00:00 0.124 0 0.124 0
2022-07-20 05:00:00 0.02 0.226 0 0.206
2022-07-20 06:00:00 0 1.058 0 1.058
2022-07-20 07:00:00 0.086 1.607 0 1.521
2022-07-20 08:00:00 0 2.09 0 2.09
2022-07-20 09:00:00 0 2.302 0 2.302
2022-07-20 10:00:00 0.223 2.427 0 2.204
2022-07-20 11:00:00 0.031 2.723 0 2.692
2022-07-20 12:00:00 0 2.818 0 2.818
2022-07-20 13:00:00 0 2.735 0 2.735
2022-07-20 14:00:00 0 2.413 0 2.413
2022-07-20 15:00:00 0 1.953 0 1.953
2022-07-20 16:00:00 0.316 1.407 0 1.091
2022-07-20 17:00:00 0.183 1.2 0 1.017
2022-07-20 18:00:00 0.001 0.843 0 0.842
2022-07-20 19:00:00 0.446 0.274 0.172 0
2022-07-20 20:00:00 0.712 0 0.712 0
2022-07-20 21:00:00 0.225 0 0.225 0
2022-07-20 22:00:00 0.207 0 0.207 0
2022-07-20 23:00:00 0.15 0 0.15 0
```
## API usage
```
import datetime
import elicznik
with elicznik.ELicznik("freddy@example.com", "secretpassword", "optional_site_identifier") as m:
# date range
print("July 2021")
readings = m.get_readings(datetime.date(2021, 7, 1), datetime.date(2021, 7, 31))
for timestamp, consumed, produced, consumed_net, produced_net in readings:
print(timestamp, consumed, produced, consumed_net, produced_net)
# single day
print("Yesterday")
yesterday = datetime.date.today() - datetime.timedelta(days=1)
readings = m.get_readings(yesterday)
for timestamp, consumed, produced, consumed_net, produced_net in readings:
print(timestamp, consumed, produced, consumed_net, produced_net)
```
## Notes on APIs and the `--api` command line switch
Tauron exposes two API endpoints for retrieving meter readings -- one for downloading CSV (and XLS) data,
the other is a back-end supporting the charts in the Web UI. In theory, both endpoints are equivalent.
They can be used to get exactly the same data. In practice, the endpoint for downloading CSV data seems
more stable -- in contrast to the chart one, which changed a few times in the past. The CSV endpoint is
also more robust and allows downloading more data with fewer requests.
This project supports fetching data from both. CSV is the default and recommended one, but it's possible
to switch to the chart API endpoint in case of problems.
This can be done by adding `--api=chart` on the command line:
```
$ elicznik --api=chart freddy@example.com secretpassword 2021-07-10
```
Both APIs can also be used explicitly from code. The `elicznik` module defines two classes for that `ELicznikChart`
and `ELicznikCSV`. `ELicznik` is just an alias for `ELicznikCSV`:
```
import elicznik
with elicznik.ELicznikChart("freddy@example.com", "secretpassword") as m:
...
```
## TODO & bugs
* Convert the dates to UTC and handle switches from and to DST properly
* Make the dependency on tabulate optional
## Similar projects
This project is based on the excellent
[tauron-elicznik-scrapper](https://github.com/MichalZaniewicz/tauron-elicznik-scraper) project by
[Michał Zaniewicz](https://github.com/MichalZaniewicz), but there are several other available out there.
Among the other [similar eLicznik projects on GitHub](https://github.com/search?q=elicznik) there's one especially
worth checking out:
the [Tauron AMIplus sensor](https://github.com/PiotrMachowski/Home-Assistant-custom-components-Tauron-AMIplus) -- it's
an eLicznik Home Assistant integration.
Raw data
{
"_id": null,
"home_page": "https://github.com/mlesniew/elicznik",
"name": "elicznik",
"maintainer": null,
"docs_url": null,
"requires_python": "<4,>=3.6",
"maintainer_email": null,
"keywords": "elicznik, tauron, scrapper",
"author": "Micha\u0142 Le\u015bniewski",
"author_email": "mlesniew@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/6a/2a/e209bd51f99747da076d5abb43c57eece518f32e929e308417003d312a12/elicznik-2.2.1.tar.gz",
"platform": null,
"description": "# Tauron eLicznik Scraper\n\nThis Python 3 package allows to read electric energy meter reading history from the \n[Tauron eLicznik](https://elicznik.tauron-dystrybucja.pl/) website.\n\n\n## Installation\n\nThe package can be installed using pip:\n\n```\n$ pip3 install elicznik\n```\n\nor alternatively:\n```\n$ pip3 install git@github.com:mlesniew/elicznik.git\n```\n\n\n\n## Command line usage\n\nWith the package installed readings can be retrieved by simply running the `elicznik` command:\n```\nusage: elicznik [-h] [--format {table,csv}] [--api {chart,csv}] [--site SITE] username password [start_date] [end_date]\n\npositional arguments:\n username tauron-dystrybucja.pl user name\n password tauron-dystrybucja.pl password\n start_date Start date of date range to be retrieved, in ISO8601 format. If the end date is omitted, it's the only date for which measurements are retrieved.\n end_date End date of date range to be retrieved, inclusive, in ISO8601 format. Can be omitted to only retrieve a single day's measurements.\n\noptions:\n -h, --help show this help message and exit\n --format {table,csv} Specify the output format\n --api {chart,csv} Specify which Tauron API to use to get the measurements\n --site SITE site identifier, must match '[0-9]+_[0-9]+_[0-9]+'\n(venv) ~/src/elicznik (site) $ elicznik --help | cat\nusage: elicznik [-h] [--format {table,csv}] [--api {chart,csv}] [--site SITE]\n username password [start_date] [end_date]\n\npositional arguments:\n username tauron-dystrybucja.pl user name\n password tauron-dystrybucja.pl password\n start_date Start date of date range to be retrieved, in ISO8601\n format. If the end date is omitted, it's the only date\n for which measurements are retrieved.\n end_date End date of date range to be retrieved, inclusive, in\n ISO8601 format. Can be omitted to only retrieve a\n single day's measurements.\n\noptions:\n -h, --help show this help message and exit\n --format {table,csv} Specify the output format\n --api {chart,csv} Specify which Tauron API to use to get the\n measurements\n --site SITE site identifier, must match '[0-9]+_[0-9]+_[0-9]+'\n```\n\n\n### Example\n\n```\n$ elicznik freddy@example.com secretpassword 2022-07-20\ntimestamp consumed produced net consumption net production\n------------------- ---------- ---------- ----------------- ----------------\n2022-07-20 00:00:00 0.133 0 0.133 0\n2022-07-20 01:00:00 0.127 0 0.127 0\n2022-07-20 02:00:00 0.119 0 0.119 0\n2022-07-20 03:00:00 0.119 0 0.119 0\n2022-07-20 04:00:00 0.124 0 0.124 0\n2022-07-20 05:00:00 0.02 0.226 0 0.206\n2022-07-20 06:00:00 0 1.058 0 1.058\n2022-07-20 07:00:00 0.086 1.607 0 1.521\n2022-07-20 08:00:00 0 2.09 0 2.09\n2022-07-20 09:00:00 0 2.302 0 2.302\n2022-07-20 10:00:00 0.223 2.427 0 2.204\n2022-07-20 11:00:00 0.031 2.723 0 2.692\n2022-07-20 12:00:00 0 2.818 0 2.818\n2022-07-20 13:00:00 0 2.735 0 2.735\n2022-07-20 14:00:00 0 2.413 0 2.413\n2022-07-20 15:00:00 0 1.953 0 1.953\n2022-07-20 16:00:00 0.316 1.407 0 1.091\n2022-07-20 17:00:00 0.183 1.2 0 1.017\n2022-07-20 18:00:00 0.001 0.843 0 0.842\n2022-07-20 19:00:00 0.446 0.274 0.172 0\n2022-07-20 20:00:00 0.712 0 0.712 0\n2022-07-20 21:00:00 0.225 0 0.225 0\n2022-07-20 22:00:00 0.207 0 0.207 0\n2022-07-20 23:00:00 0.15 0 0.15 0\n```\n\n\n## API usage\n\n```\nimport datetime\nimport elicznik\n\nwith elicznik.ELicznik(\"freddy@example.com\", \"secretpassword\", \"optional_site_identifier\") as m:\n # date range\n print(\"July 2021\")\n\n readings = m.get_readings(datetime.date(2021, 7, 1), datetime.date(2021, 7, 31))\n\n for timestamp, consumed, produced, consumed_net, produced_net in readings:\n print(timestamp, consumed, produced, consumed_net, produced_net)\n\n # single day\n print(\"Yesterday\")\n\n yesterday = datetime.date.today() - datetime.timedelta(days=1)\n readings = m.get_readings(yesterday)\n\n for timestamp, consumed, produced, consumed_net, produced_net in readings:\n print(timestamp, consumed, produced, consumed_net, produced_net)\n```\n\n\n## Notes on APIs and the `--api` command line switch\n\nTauron exposes two API endpoints for retrieving meter readings -- one for downloading CSV (and XLS) data,\nthe other is a back-end supporting the charts in the Web UI. In theory, both endpoints are equivalent.\nThey can be used to get exactly the same data. In practice, the endpoint for downloading CSV data seems\nmore stable -- in contrast to the chart one, which changed a few times in the past. The CSV endpoint is\nalso more robust and allows downloading more data with fewer requests.\n\nThis project supports fetching data from both. CSV is the default and recommended one, but it's possible\nto switch to the chart API endpoint in case of problems.\n\nThis can be done by adding `--api=chart` on the command line:\n```\n$ elicznik --api=chart freddy@example.com secretpassword 2021-07-10\n```\n\nBoth APIs can also be used explicitly from code. The `elicznik` module defines two classes for that `ELicznikChart`\nand `ELicznikCSV`. `ELicznik` is just an alias for `ELicznikCSV`:\n```\nimport elicznik\n\nwith elicznik.ELicznikChart(\"freddy@example.com\", \"secretpassword\") as m:\n ...\n```\n\n\n## TODO & bugs\n\n* Convert the dates to UTC and handle switches from and to DST properly\n* Make the dependency on tabulate optional\n\n\n## Similar projects\n\nThis project is based on the excellent\n[tauron-elicznik-scrapper](https://github.com/MichalZaniewicz/tauron-elicznik-scraper) project by\n[Micha\u0142 Zaniewicz](https://github.com/MichalZaniewicz), but there are several other available out there.\n\nAmong the other [similar eLicznik projects on GitHub](https://github.com/search?q=elicznik) there's one especially\nworth checking out:\nthe [Tauron AMIplus sensor](https://github.com/PiotrMachowski/Home-Assistant-custom-components-Tauron-AMIplus) -- it's\nan eLicznik Home Assistant integration.\n",
"bugtrack_url": null,
"license": null,
"summary": "Tauron eLicznik scrapper",
"version": "2.2.1",
"project_urls": {
"Homepage": "https://github.com/mlesniew/elicznik"
},
"split_keywords": [
"elicznik",
" tauron",
" scrapper"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "02cfc0a011fd1e9c0fa21a4cd057ce1bf8d01a19250184331ef190ded59313f3",
"md5": "4c0249f7b1ed5a4f417144be579a4137",
"sha256": "8917ae51bc36b297994e2ce1a8c0064f07e3264057c83a8698a18425e8159298"
},
"downloads": -1,
"filename": "elicznik-2.2.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "4c0249f7b1ed5a4f417144be579a4137",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4,>=3.6",
"size": 8098,
"upload_time": "2024-05-19T16:26:04",
"upload_time_iso_8601": "2024-05-19T16:26:04.730422Z",
"url": "https://files.pythonhosted.org/packages/02/cf/c0a011fd1e9c0fa21a4cd057ce1bf8d01a19250184331ef190ded59313f3/elicznik-2.2.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "6a2ae209bd51f99747da076d5abb43c57eece518f32e929e308417003d312a12",
"md5": "76f70994be8e92ea50d565a76025dbaa",
"sha256": "cbe03970f74e712fc2aa8606d926773170e05b324e307c539d273f121c30993f"
},
"downloads": -1,
"filename": "elicznik-2.2.1.tar.gz",
"has_sig": false,
"md5_digest": "76f70994be8e92ea50d565a76025dbaa",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4,>=3.6",
"size": 8992,
"upload_time": "2024-05-19T16:26:06",
"upload_time_iso_8601": "2024-05-19T16:26:06.337168Z",
"url": "https://files.pythonhosted.org/packages/6a/2a/e209bd51f99747da076d5abb43c57eece518f32e929e308417003d312a12/elicznik-2.2.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-05-19 16:26:06",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "mlesniew",
"github_project": "elicznik",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "elicznik"
}
JSON
