# eiapy
[](https://pypi.org/project/eiapy/) [](https://pypi.org/project/eiapy/) [](https://pypi.org/project/eiapy/)
Python 3 wrapper for the U.S. Energy Information Administration API.
### Quick start
```bash
pip install eiapy
```
Get the last 5 measurements of the electricity flow between California and Mexico.
```python3
>>> from eiapy import Series
>>> cal_to_mex = Series('EBA.CISO-CFE.ID.H')
>>> cal_to_mex.last(5)
{'request': {'command': 'series', 'series_id': 'EBA.CISO-CFE.ID.H'},
'series': [{'data': [['20180401T07Z', -11],
['20180401T06Z', -16],
['20180401T05Z', -11],
['20180401T04Z', -7],
['20180401T03Z', -5]],
'description': 'Timestamps follow the ISO8601 standard '
'(https://en.wikipedia.org/wiki/ISO_8601). Hourly '
'representations are provided in Universal Time.',
'end': '20180401T07Z',
'f': 'H',
'name': 'Actual Net Interchange for California Independent System '
'Operator (CISO) to Comision Federal de Electricidad '
'(CFE), Hourly',
'series_id': 'EBA.CISO-CFE.ID.H',
'start': '20150701T00Z',
'units': 'megawatthours',
'updated': '2018-04-02T08:43:16-0400'}]}
```
Further examples can be found [in this gist](https://gist.github.com/systemcatch/019cf50302093b9b51838c62b99623df).
To find more details about the API go to the EIA's [Open Data](https://www.eia.gov/opendata/) page. To find interesting data (and identifiers) [browse the data sets](https://www.eia.gov/opendata/qb.php).
For specific information about the [real-time grid display](https://www.eia.gov/beta/electricity/gridmonitor/dashboard/electric_overview/US48/US48) please see [this guide](https://www.eia.gov/realtime_grid/docs/userguide-knownissues.pdf).
Go [here](https://www.eia.gov/opendata/register.cfm#terms_of_service) to see the
API terms of service and [here](https://www.eia.gov/about/copyrights_reuse.cfm)
for an explanation of copyright and reuse of their data.
### Setting up your API key
An API key is needed to access the EIA's data, you can get one [here](https://www.eia.gov/opendata/register.php). eiapy needs this key to be manually set in the operating system environmental variables.
**Mac & Linux**
Open a terminal and enter the following;
```bash
export EIA_KEY=type_your_api_key_here
```
To set it permanently follow the instructions on this [stackexchange question](https://unix.stackexchange.com/questions/117467/how-to-permanently-set-environmental-variables).
**Windows**
Open a Command Prompt and enter the following;
```bat
setx EIA_KEY "type_your_api_key_within_the_quotes"
```
### Notes on API behaviour
- When providing invalid time limits for a series data request an empty data list is returned.
- For data requests num & start cannot be used together but num & end can.
- When an invalid series id is passed this is the response.
```python3
{'request': {'series_id': 'eba.ciso-cfe.id.', 'command': 'series', 'num': '5'},
'data': {'error': 'invalid series_id. For key registration, documentation, and
examples see https://www.eia.gov/developer/'}}
```
- The API expects timestamps in ISO 8601 format (YYYYMMDDTHHZ) with Z meaning UTC, [bad timestamps](https://github.com/systemcatch/eiapy/issues/16) will not raise errors.
### Changelog
**0.1.6**
- Changed URLs to https as http is no longer supported by EIA.
- Added python 3.9 and 3.10 to classifiers, removed 3.5.
**0.1.5**
- Added Python 3.8 to supported versions.
- Updated readme with advice about bad timestamps.
- Disabled broken Relation class.
- Made handling of no api key more human friendly.
**0.1.4**
- Fixed broken Search `repr`.
- Added Python 3.7 to supported versions.
- Mention real-time grid in readme.
**0.1.3**
- Simplify construction and use of the Search class.
- Explain how to set up the API key.
- Added gist of examples to readme.
**0.1.2**
- Rename several methods for extra clarity.
- data -> get_data
- get -> get_updates
**0.1.1**
- Started using requests session functionality to improve performance.
- Fixed a mistake in the MultiSeries class that stopped it working entirely.
- Added a version attribute to the package.
- Overhaul of readme.
Raw data
{
"_id": null,
"home_page": "https://github.com/systemcatch/eiapy",
"name": "eiapy",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3",
"maintainer_email": "",
"keywords": "EIA Data API Energy",
"author": "Chris Brown",
"author_email": "cebrown999@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/0f/ac/8685ae153856c332db874f888d1aa32fc3de7a9ebaf73f0b47ac56e27fc0/eiapy-0.1.6.tar.gz",
"platform": "",
"description": "\n# eiapy\n[](https://pypi.org/project/eiapy/) [](https://pypi.org/project/eiapy/) [](https://pypi.org/project/eiapy/) \n\nPython 3 wrapper for the U.S. Energy Information Administration API. \n\n### Quick start\n```bash\npip install eiapy\n```\n\nGet the last 5 measurements of the electricity flow between California and Mexico.\n\n```python3\n>>> from eiapy import Series\n>>> cal_to_mex = Series('EBA.CISO-CFE.ID.H')\n>>> cal_to_mex.last(5)\n{'request': {'command': 'series', 'series_id': 'EBA.CISO-CFE.ID.H'},\n 'series': [{'data': [['20180401T07Z', -11],\n ['20180401T06Z', -16],\n ['20180401T05Z', -11],\n ['20180401T04Z', -7],\n ['20180401T03Z', -5]],\n 'description': 'Timestamps follow the ISO8601 standard '\n '(https://en.wikipedia.org/wiki/ISO_8601). Hourly '\n 'representations are provided in Universal Time.',\n 'end': '20180401T07Z',\n 'f': 'H',\n 'name': 'Actual Net Interchange for California Independent System '\n 'Operator (CISO) to Comision Federal de Electricidad '\n '(CFE), Hourly',\n 'series_id': 'EBA.CISO-CFE.ID.H',\n 'start': '20150701T00Z',\n 'units': 'megawatthours',\n 'updated': '2018-04-02T08:43:16-0400'}]}\n\n```\n\nFurther examples can be found [in this gist](https://gist.github.com/systemcatch/019cf50302093b9b51838c62b99623df).\n\nTo find more details about the API go to the EIA's [Open Data](https://www.eia.gov/opendata/) page. To find interesting data (and identifiers) [browse the data sets](https://www.eia.gov/opendata/qb.php).\n\nFor specific information about the [real-time grid display](https://www.eia.gov/beta/electricity/gridmonitor/dashboard/electric_overview/US48/US48) please see [this guide](https://www.eia.gov/realtime_grid/docs/userguide-knownissues.pdf).\n\nGo [here](https://www.eia.gov/opendata/register.cfm#terms_of_service) to see the\nAPI terms of service and [here](https://www.eia.gov/about/copyrights_reuse.cfm)\nfor an explanation of copyright and reuse of their data.\n\n### Setting up your API key\nAn API key is needed to access the EIA's data, you can get one [here](https://www.eia.gov/opendata/register.php). eiapy needs this key to be manually set in the operating system environmental variables.\n\n**Mac & Linux** \nOpen a terminal and enter the following;\n```bash\nexport EIA_KEY=type_your_api_key_here\n```\nTo set it permanently follow the instructions on this [stackexchange question](https://unix.stackexchange.com/questions/117467/how-to-permanently-set-environmental-variables).\n\n**Windows** \nOpen a Command Prompt and enter the following;\n```bat\nsetx EIA_KEY \"type_your_api_key_within_the_quotes\"\n```\n\n### Notes on API behaviour\n- When providing invalid time limits for a series data request an empty data list is returned.\n- For data requests num & start cannot be used together but num & end can.\n- When an invalid series id is passed this is the response.\n```python3\n{'request': {'series_id': 'eba.ciso-cfe.id.', 'command': 'series', 'num': '5'},\n 'data': {'error': 'invalid series_id. For key registration, documentation, and\n examples see https://www.eia.gov/developer/'}}\n```\n- The API expects timestamps in ISO 8601 format (YYYYMMDDTHHZ) with Z meaning UTC, [bad timestamps](https://github.com/systemcatch/eiapy/issues/16) will not raise errors.\n\n### Changelog\n**0.1.6**\n- Changed URLs to https as http is no longer supported by EIA.\n- Added python 3.9 and 3.10 to classifiers, removed 3.5.\n\n**0.1.5**\n- Added Python 3.8 to supported versions.\n- Updated readme with advice about bad timestamps.\n- Disabled broken Relation class.\n- Made handling of no api key more human friendly.\n\n**0.1.4**\n- Fixed broken Search `repr`.\n- Added Python 3.7 to supported versions.\n- Mention real-time grid in readme.\n\n**0.1.3**\n- Simplify construction and use of the Search class.\n- Explain how to set up the API key.\n- Added gist of examples to readme.\n\n**0.1.2**\n- Rename several methods for extra clarity.\n- data -> get_data\n- get -> get_updates\n\n**0.1.1** \n- Started using requests session functionality to improve performance.\n- Fixed a mistake in the MultiSeries class that stopped it working entirely.\n- Added a version attribute to the package.\n- Overhaul of readme.\n\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A simple wrapper for the U.S. Energy Information Administration (EIA) API.",
"version": "0.1.6",
"project_urls": {
"Homepage": "https://github.com/systemcatch/eiapy"
},
"split_keywords": [
"eia",
"data",
"api",
"energy"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "5d8e34e3ea2a05a4a41a88b6e3b7542e0ec701d2a9252453c9fb8037f5ee181d",
"md5": "e9e076af3a98482754179214671f4e7a",
"sha256": "b91a3c7ecc69b9da3373ae6f0c83fc2e04de11a8291d8210c2ac9666b636147e"
},
"downloads": -1,
"filename": "eiapy-0.1.6-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "e9e076af3a98482754179214671f4e7a",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": ">=3",
"size": 6758,
"upload_time": "2022-02-18T10:16:52",
"upload_time_iso_8601": "2022-02-18T10:16:52.757248Z",
"url": "https://files.pythonhosted.org/packages/5d/8e/34e3ea2a05a4a41a88b6e3b7542e0ec701d2a9252453c9fb8037f5ee181d/eiapy-0.1.6-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "0fac8685ae153856c332db874f888d1aa32fc3de7a9ebaf73f0b47ac56e27fc0",
"md5": "b4e1f5f112758f4aff1ded35d8ac2e82",
"sha256": "78d17600dd4a9ae6fe6d4a720ba34b6259f1f5e46e7bea3287d089cbbe694335"
},
"downloads": -1,
"filename": "eiapy-0.1.6.tar.gz",
"has_sig": false,
"md5_digest": "b4e1f5f112758f4aff1ded35d8ac2e82",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3",
"size": 6907,
"upload_time": "2022-02-18T10:16:54",
"upload_time_iso_8601": "2022-02-18T10:16:54.621051Z",
"url": "https://files.pythonhosted.org/packages/0f/ac/8685ae153856c332db874f888d1aa32fc3de7a9ebaf73f0b47ac56e27fc0/eiapy-0.1.6.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2022-02-18 10:16:54",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "systemcatch",
"github_project": "eiapy",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"tox": true,
"lcname": "eiapy"
}
JSON
