You can configure pyeia with your API key either at runtime.
- Set an environment variable explicitly,
- If you are using dynaconf, you can include an
[eia]environment in your
settings.tomlfile (or any other configured settings files.)
[eia] apikey = "my apikey"
The U.S. Energy Information Adminsitration provides an API for access to commonly used datasets for policy makers and researchers. See the EIA API documentation for more information.
Warning : This package is a work in progress! A substantial update is expected in January 2020, with a published version on PyPi. The author took a break from this domain area, but is returning! Hoping to have a similar or identical R interface/API as well, but that may be much farther down the pipeline.
Since this package is still under active development, it has not been pushed to PyPi. That said, I believe it is stable and reliable enough for immediate use. You can install this via git+https, i.e. :
pip install pyeia pip show pyeia
There are two main strategies for interacting with this package.
EIA provides a web-based data browser Since most interactions for discovering data via the API will likely occur through this browser, this motivated a programmatic version.
The general strategy is to traverse a datapath or multiple datapaths, and
when you arrive to the desired node, you flag one or more dataseries.
There is also the ability to add in meta information as you flag a dataseries.
export method on a Browser object will make a request to the
Series API to collect data you've flagged.
There's currently a separate class for each dataset which is mostly syntactic. In the future, there will likely be methods and visualizations builtin that are specific to the datasets described at the root category level from EIA.
Direct API usage
Each endpoint has a corresponding class in
eia.api. Every class has a
query method that makes a call to EIA.
The returned result is always the response body. Metadata about the request is dropped. The
classes have a special
query_df method since their response bodies have a naturally tabular schema.
from eia import api myapikey = "" # Register here : www.eia.gov/opendata/register.cfm # Make a call to the Category endpoint category = api.Category(myapikey) category.query() # Make a call to the Series endpoint series = api.Series( "AEO.2015.REF2015.CNSM_DEU_TOTD_NA_DEU_NA_ENC_QBTU.A", "AEO.2015.REF2015.CNSM_ENU_ALLS_NA_DFO_DELV_ENC_QBTU.A", api_key=myapikey, ) series.to_dict() # Export data from its json response # Make the same query, but get results as a pandas DataFrame series.to_dataframe() # Make a call to the Geoset endpoint geoset = api.Geoset("ELEC.GEN.ALL-99.A", "USA-CA", "USA-FL", "USA-MN", api_key=myapikey) geoset.to_dict() geoset.query_df() # Make a call to the SeriesCategory endpoint seriescategory = api.SeriesCategory( "AEO.2015.REF2015.CNSM_DEU_TOTD_NA_DEU_NA_ENC_QBTU.A", "AEO.2015.REF2015.CNSM_ENU_ALLS_NA_DFO_DELV_ENC_QBTU.A", api_key=myapikey, ) seriescategory.to_dict() # Make a call to the Updates endpoint updates = api.Updates( category_id=2102358, rows=0, firstrow="currently_not_used", deep=False, api_key=myapikey, ) updates.to_dict() # Make a call to the Search endpoint search = api.Search(api_key=myapikey) # Make a series_id search search.to_dict("series_id", "EMI_CO2_COMM_NA_CL_NA_NA_MILLMETNCO2.A", "all") # Make a name search search.to_dict("name", "crude oil", 25) # Make a date-range search # Dates can be input as a list/tuple of any valid pd.to_datetime argument search.to_dict("last_updated", ["Dec. 1st, 2014", "06/14/2015 3:45PM"])