Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/philsv/myeia
Python wrapper for the U.S. Energy Information Administration (EIA) API v2
https://github.com/philsv/myeia
eia eia-api energy python statistics
Last synced: 5 days ago
JSON representation
Python wrapper for the U.S. Energy Information Administration (EIA) API v2
- Host: GitHub
- URL: https://github.com/philsv/myeia
- Owner: philsv
- License: mit
- Created: 2022-03-02T18:19:24.000Z (almost 3 years ago)
- Default Branch: main
- Last Pushed: 2024-10-21T00:35:42.000Z (2 months ago)
- Last Synced: 2024-11-21T11:18:35.650Z (about 1 month ago)
- Topics: eia, eia-api, energy, python, statistics
- Language: Python
- Homepage: https://pypi.org/project/myeia/
- Size: 385 KB
- Stars: 14
- Watchers: 1
- Forks: 5
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# 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.