# 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
* backoff
* pandas
* python-dateutil
* python-dotenv
* requests
## 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 import API
eia = API()
```
## Environment Variables
```bash
# Create a .env file in your projects root directory
touch .env
```
By default the `API` class will look for your `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
... ...
```
## Filter by multiple facets
You can also filter by multiple facets. Lets look at the *UAE Crude oil, NGPL, and other liquids* where the facets we choose are `countryRegionId` and `productId`.
The difference here is that both facet columns are present in the dataframe, unlike the previous examples where only one facet was present.
```python
df = eia.get_series_via_route(
route="international",
series=["ARE", 55],
frequency="monthly",
facet=["countryRegionId", "productId"],
)
df.head()
```
Output Example:
```ini
countryRegionId productId Crude oil, NGPL, and other liquids
Date
2024-03-01 ARE 55 4132.394334
2024-02-01 ARE 55 4132.394334
2024-01-01 ARE 55 4142.394334
2023-12-01 ARE 55 4082.394334
2023-11-01 ARE 55 4082.394334
... ... ... ...
```
## Get Multiple Series
For multiple series you have to loop through the series and append the data to a list.
```python
data = []
for item in ["RNGC1", "RNGC2"]:
df = eia.get_series_via_route(
route="natural-gas/pri/fut",
series=item,
frequency="daily",
facet="series",
)
data.append(df)
df = pd.concat(data, axis=1)
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",
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)
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
... ...
```
## Contributing
We love your input! We want to make contributing to this project as easy and transparent as possible.
Read our [CONTRIBUTING.md](CONTRIBUTING.md) to get started.
Raw data
{
"_id": null,
"home_page": "https://github.com/philsv/myeia",
"name": "myeia",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "eia, eia-api, open-data, python",
"author": "philsv",
"author_email": "frphsv@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/54/e3/18b81b8b675f6c1b212441cf6a26c89cedad496afb6205eac8f2be5fc3e8/myeia-0.4.6.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* backoff\n* pandas\n* python-dateutil\n* python-dotenv\n* requests\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 import API\n\neia = API()\n```\n\n## Environment Variables\n\n```bash\n# Create a .env file in your projects root directory\ntouch .env\n```\n\nBy default the `API` class will look for your `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\n## Filter by multiple facets\n\nYou can also filter by multiple facets. Lets look at the *UAE Crude oil, NGPL, and other liquids* where the facets we choose are `countryRegionId` and `productId`.\nThe difference here is that both facet columns are present in the dataframe, unlike the previous examples where only one facet was present.\n\n```python\ndf = eia.get_series_via_route(\n route=\"international\",\n series=[\"ARE\", 55],\n frequency=\"monthly\",\n facet=[\"countryRegionId\", \"productId\"],\n)\n\ndf.head()\n```\n\nOutput Example:\n\n```ini\n countryRegionId productId Crude oil, NGPL, and other liquids\nDate \n2024-03-01 ARE 55 4132.394334\n2024-02-01 ARE 55 4132.394334\n2024-01-01 ARE 55 4142.394334\n2023-12-01 ARE 55 4082.394334\n2023-11-01 ARE 55 4082.394334\n... ... ... ...\n```\n\n## Get Multiple Series\n\nFor multiple series you have to loop through the series and append the data to a list.\n\n```python\ndata = []\nfor item in [\"RNGC1\", \"RNGC2\"]:\n df = eia.get_series_via_route(\n route=\"natural-gas/pri/fut\",\n series=item,\n frequency=\"daily\",\n facet=\"series\",\n )\n data.append(df)\n\ndf = pd.concat(data, axis=1)\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\",\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)\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\n## Contributing\nWe love your input! We want to make contributing to this project as easy and transparent as possible.\nRead our [CONTRIBUTING.md](CONTRIBUTING.md) to get started.\n\n\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Python Wrapper for the U.S. Energy Information Administration (EIA) APIv2.",
"version": "0.4.6",
"project_urls": {
"Homepage": "https://github.com/philsv/myeia"
},
"split_keywords": [
"eia",
" eia-api",
" open-data",
" python"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "f09f0611a6cef60d66203a20a3dbe080bc63e27411ddce5b46482e543872dba2",
"md5": "14bc242761cb4554d0cffb33eb148662",
"sha256": "115c6081a9dc7701e1c2345489de6d577fc03056ab1105bd73433ba4787eafe7"
},
"downloads": -1,
"filename": "myeia-0.4.6-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "14bc242761cb4554d0cffb33eb148662",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": null,
"size": 6919,
"upload_time": "2024-10-21T00:36:09",
"upload_time_iso_8601": "2024-10-21T00:36:09.449399Z",
"url": "https://files.pythonhosted.org/packages/f0/9f/0611a6cef60d66203a20a3dbe080bc63e27411ddce5b46482e543872dba2/myeia-0.4.6-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "54e318b81b8b675f6c1b212441cf6a26c89cedad496afb6205eac8f2be5fc3e8",
"md5": "3c532727e95b3eebe4a5dd2560facd84",
"sha256": "d7bdf88c70003e7b019d9c603316fbeac8c3ec4ee72d8ca4e622a9e5d0ecdbae"
},
"downloads": -1,
"filename": "myeia-0.4.6.tar.gz",
"has_sig": false,
"md5_digest": "3c532727e95b3eebe4a5dd2560facd84",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 7885,
"upload_time": "2024-10-21T00:36:10",
"upload_time_iso_8601": "2024-10-21T00:36:10.978417Z",
"url": "https://files.pythonhosted.org/packages/54/e3/18b81b8b675f6c1b212441cf6a26c89cedad496afb6205eac8f2be5fc3e8/myeia-0.4.6.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-21 00:36:10",
"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
