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
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.
eia API Query Browser
To find all EIA Datasets visit API Dashboard.
How to use
from myeia import API
eia = API()
Environment Variables
# 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.
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.
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:
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.
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:
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.
df = eia.get_series_via_route(
route="international",
series=["ARE", 55],
frequency="monthly",
facet=["countryRegionId", "productId"],
)
df.head()
Output Example:
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.
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:
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.
df = eia.get_series(
series_id="NG.RNGC1.D",
start_date="2021-01-01",
end_date="2021-01-31",
)
df.head()
Output Example:
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.
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:
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 to get started.
Metadata
Release files for myeia 0.4.8
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| myeia-0.4.8.tar.gz | 7.8 kB | Without provenance | Details for myeia-0.4.8.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| myeia-0.4.8-py2.py3-none-any.whl | Python 2, Python 3 | none | any | Details for myeia-0.4.8-py2.py3-none-any.whl |
Total release size: 14.7 kB
Release files / myeia-0.4.8.tar.gz
| Download URL | myeia-0.4.8.tar.gz |
|---|---|
| Size | 7.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
e636da2bae3b9fbf60c2cca74e408f0ba33e1fec42f1fc051e839f1c40f1e5af
|
|
BLAKE2b-256 checksum How to use checksums |
7409614fc99bade8bce6cef8cd5f6d4683c4158c40cd5ff7757134cb779faff8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.8.18
|
Release files / myeia-0.4.8-py2.py3-none-any.whl
| Download URL | myeia-0.4.8-py2.py3-none-any.whl |
|---|---|
| Size | 6.9 kB |
| Tags | Python 2 Python 3 |
|
SHA-256 checksum How to use checksums |
cc1076ecbfe6b93ca481078cace1fdb326e2e19136d56cde185f40f08e66270e
|
|
BLAKE2b-256 checksum How to use checksums |
3e946c4ac20df3c0ed296ec8029d34e306c554376ba4777a67db03199136b5bf
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.8.18
|
Security for myeia 0.4.8
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.