# myeia
[](https://badge.fury.io/py/myeia)
[](https://github.com/philsv/myeia/blob/main/LICENSE)
[](https://pepy.tech/project/myeia)
[](https://pepy.tech/project/myeia)
[](https://pepy.tech/project/myeia)
myeia is a simple Python wrapper for the U.S. Energy Information Administration (EIA) APIv2. It is designed to be simple to use and to provide a consistent interface for accessing EIA data.
## Installation
```ini
pip install myeia
```
## Requirements
* pandas
* requests
* python-dotenv
## eia OPEN DATA Registration
To obtain an API Key you need to register on the [EIA website](https://www.eia.gov/opendata/register.php).
## eia API Query Browser
To find all EIA Datasets visit [API Dashboard](https://www.eia.gov/opendata/browser/).
## How to use
```python
from myeia.api import API
eia = API()
```
By Default the EIA class will look for your API `EIA_TOKEN`.
If you have registered for an API key you can set it in your `.env` file.
```ini
EIA_TOKEN=YOUR_TOKEN_HERE
```
## Get Series
Lets look at an example of how to get the *EIA Natural Gas Futures*.
You can use the simpler v1 API method where you only need to pass the `series_id` or you can use the newer v2 API method where you need to pass the `route`, `series`, and `frequency`.
```python
df = eia.get_series(series_id="NG.RNGC1.D")
df = eia.get_series_via_route(
route="natural-gas/pri/fut",
series="RNGC1",
frequency="daily",
)
df.head()
```
Output Example:
```ini
Natural Gas Futures Contract 1 (Dollars per Million Btu)
Date
2022-09-13 8.284
2022-09-12 8.249
2022-09-09 7.996
2022-09-08 7.915
2022-09-07 7.842
...
```
## Different Facets
Lets look at another example the *Total OPEC Petroleum Supply* where the facet is available as `seriesId`. By Default it is set as `series` but we can define the facet as `seriesId`.
```python
df = eia.get_series(series_id="STEO.PAPR_OPEC.M")
df = eia.get_series_via_route(
route="steo",
series="PAPR_OPEC",
frequency="monthly",
facet="seriesId",
)
df.head()
```
Output Example:
```ini
Total OPEC Petroleum Supply
Date
2023-12-01 34.517314
2023-11-01 34.440397
2023-10-01 34.376971
2023-09-01 34.416242
2023-08-01 34.451823
```
## Get Multiple Series
You can also get a list of series for a specific route.
You have to make sure they are both in the same frequency and facet type.
```python
df = eia.get_series_via_route(
route="natural-gas/pri/fut",
series=["RNGC1", "RNGC1"],
frequency="daily",
facet="series",
)
df.head()
```
Output Example:
```ini
Natural Gas Futures Contract 1 (Dollars per Million Btu) Natural Gas Futures Contract 2 (Dollars per Million Btu)
Date
2023-08-29 2.556 2.662
2023-08-28 2.579 2.665
2023-08-25 2.540 2.657
2023-08-24 2.519 2.636
2023-08-23 2.497 2.592
... ... ...
```
## Define a Start and End Date
You can define a start and end date for your query.
```python
df = eia.get_series(
series_id="NG.RNGC1.D",
start_date="2021-01-01",
end_date="2021-01-31",
)
df.head()
```
Output Example:
```ini
Natural Gas Futures Contract 1 (Dollars per Million Btu)
Date
2021-01-29 2.564
2021-01-28 2.664
2021-01-27 2.760
2021-01-26 2.656
2021-01-25 2.602
... ...
```
This also works for the `get_series_via_route` method.
```python
df = eia.get_series_via_route(
route="natural-gas/pri/fut",
series=["RNGC1", "RNGC2"],
frequency="daily",
start_date="2021-01-01",
end_date="2021-01-31",
)
df.head()
```
Output Example:
```ini
Natural Gas Futures Contract 1 (Dollars per Million Btu) Natural Gas Futures Contract 2 (Dollars per Million Btu)
Date
2021-01-29 2.564 2.592
2021-01-28 2.664 2.675
2021-01-27 2.760 2.702
2021-01-26 2.656 2.636
2021-01-25 2.602 2.598
... ... ...
```
Raw data
{
"_id": null,
"home_page": "https://github.com/philsv/myeia",
"name": "myeia",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "eia,eia-api,open-data,python",
"author": "philsv",
"author_email": "frphsv@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/d3/4f/3c9d067312dc638a45c04cc0e36fae8a8aab4b87e7d99d4241527435b2cc/myeia-0.3.5.tar.gz",
"platform": null,
"description": "# myeia\n\n[](https://badge.fury.io/py/myeia)\n[](https://github.com/philsv/myeia/blob/main/LICENSE)\n[](https://pepy.tech/project/myeia)\n[](https://pepy.tech/project/myeia)\n[](https://pepy.tech/project/myeia)\n\nmyeia is a simple Python wrapper for the U.S. Energy Information Administration (EIA) APIv2. It is designed to be simple to use and to provide a consistent interface for accessing EIA data.\n\n## Installation\n\n```ini\npip install myeia\n```\n\n## Requirements\n\n* pandas\n* requests\n* python-dotenv\n\n## eia OPEN DATA Registration\n\nTo obtain an API Key you need to register on the [EIA website](https://www.eia.gov/opendata/register.php).\n\n## eia API Query Browser\n\nTo find all EIA Datasets visit [API Dashboard](https://www.eia.gov/opendata/browser/).\n\n## How to use\n\n```python\nfrom myeia.api import API\n\neia = API()\n```\n\nBy Default the EIA class will look for your API `EIA_TOKEN`.\n\nIf you have registered for an API key you can set it in your `.env` file.\n\n```ini\nEIA_TOKEN=YOUR_TOKEN_HERE\n```\n\n## Get Series\n\nLets look at an example of how to get the *EIA Natural Gas Futures*.\nYou can use the simpler v1 API method where you only need to pass the `series_id` or you can use the newer v2 API method where you need to pass the `route`, `series`, and `frequency`.\n\n```python\ndf = eia.get_series(series_id=\"NG.RNGC1.D\")\n\ndf = eia.get_series_via_route(\n route=\"natural-gas/pri/fut\",\n series=\"RNGC1\",\n frequency=\"daily\",\n)\n\ndf.head()\n```\n\nOutput Example:\n\n```ini\n Natural Gas Futures Contract 1 (Dollars per Million Btu)\nDate\n2022-09-13 8.284\n2022-09-12 8.249\n2022-09-09 7.996\n2022-09-08 7.915\n2022-09-07 7.842\n...\n```\n\n## Different Facets\n\nLets look at another example the *Total OPEC Petroleum Supply* where the facet is available as `seriesId`. By Default it is set as `series` but we can define the facet as `seriesId`.\n\n```python\ndf = eia.get_series(series_id=\"STEO.PAPR_OPEC.M\")\n\ndf = eia.get_series_via_route(\n route=\"steo\",\n series=\"PAPR_OPEC\",\n frequency=\"monthly\",\n facet=\"seriesId\",\n)\n\ndf.head()\n```\n\n Output Example:\n\n```ini\n Total OPEC Petroleum Supply\nDate\n2023-12-01 34.517314\n2023-11-01 34.440397\n2023-10-01 34.376971\n2023-09-01 34.416242\n2023-08-01 34.451823\n```\n\n## Get Multiple Series\n\nYou can also get a list of series for a specific route.\n\nYou have to make sure they are both in the same frequency and facet type.\n\n```python\ndf = eia.get_series_via_route(\n route=\"natural-gas/pri/fut\",\n series=[\"RNGC1\", \"RNGC1\"],\n frequency=\"daily\",\n facet=\"series\",\n)\n\ndf.head()\n```\n\nOutput Example:\n\n```ini\n Natural Gas Futures Contract 1 (Dollars per Million Btu) Natural Gas Futures Contract 2 (Dollars per Million Btu)\nDate \n2023-08-29 2.556 2.662 \n2023-08-28 2.579 2.665 \n2023-08-25 2.540 2.657 \n2023-08-24 2.519 2.636 \n2023-08-23 2.497 2.592 \n... ... ...\n```\n\n## Define a Start and End Date\n\nYou can define a start and end date for your query.\n\n```python\ndf = eia.get_series(\n series_id=\"NG.RNGC1.D\",\n start_date=\"2021-01-01\",\n end_date=\"2021-01-31\",\n)\n\ndf.head()\n```\n\nOutput Example:\n\n```ini\n Natural Gas Futures Contract 1 (Dollars per Million Btu)\nDate \n2021-01-29 2.564 \n2021-01-28 2.664 \n2021-01-27 2.760 \n2021-01-26 2.656 \n2021-01-25 2.602 \n... ... \n```\n\nThis also works for the `get_series_via_route` method.\n\n```python\ndf = eia.get_series_via_route(\n route=\"natural-gas/pri/fut\",\n series=[\"RNGC1\", \"RNGC2\"],\n frequency=\"daily\",\n start_date=\"2021-01-01\",\n end_date=\"2021-01-31\",\n)\n\ndf.head()\n```\n\nOutput Example:\n\n```ini\n Natural Gas Futures Contract 1 (Dollars per Million Btu) Natural Gas Futures Contract 2 (Dollars per Million Btu)\nDate\n2021-01-29 2.564 2.592\n2021-01-28 2.664 2.675\n2021-01-27 2.760 2.702\n2021-01-26 2.656 2.636\n2021-01-25 2.602 2.598\n... ... ...\n```\n\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "",
"version": "0.3.5",
"project_urls": {
"Homepage": "https://github.com/philsv/myeia"
},
"split_keywords": [
"eia",
"eia-api",
"open-data",
"python"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "28db2313bd4cad0c802325f815c2b63858f72b14c6ec975515ff86de8ea61874",
"md5": "9ef36f7734aa369e682726b99e79723b",
"sha256": "51dc456d9d5f1080ead8c804b0ff71765e49a2d6a1793026534d79a3b5af81bb"
},
"downloads": -1,
"filename": "myeia-0.3.5-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "9ef36f7734aa369e682726b99e79723b",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": null,
"size": 6054,
"upload_time": "2023-09-08T13:39:55",
"upload_time_iso_8601": "2023-09-08T13:39:55.427757Z",
"url": "https://files.pythonhosted.org/packages/28/db/2313bd4cad0c802325f815c2b63858f72b14c6ec975515ff86de8ea61874/myeia-0.3.5-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "d34f3c9d067312dc638a45c04cc0e36fae8a8aab4b87e7d99d4241527435b2cc",
"md5": "ec734a008160932a77b157944673689c",
"sha256": "52de3c4c7d2d8897cb0256e0c95e9b15b6144b74813a9146e3810de311329bbe"
},
"downloads": -1,
"filename": "myeia-0.3.5.tar.gz",
"has_sig": false,
"md5_digest": "ec734a008160932a77b157944673689c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 6851,
"upload_time": "2023-09-08T13:39:56",
"upload_time_iso_8601": "2023-09-08T13:39:56.470537Z",
"url": "https://files.pythonhosted.org/packages/d3/4f/3c9d067312dc638a45c04cc0e36fae8a8aab4b87e7d99d4241527435b2cc/myeia-0.3.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-09-08 13:39:56",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "philsv",
"github_project": "myeia",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "myeia"
}
JSON
