Data

Tools

Indexes

Applications

Experiments

Open Source Science

pyEIA

An Energy Information Administration (EIA) API python client for researchers who just need data.

https://github.com/thomastu/pyEIA

Science Score: 10.0%

This score indicates how likely this project is to be science-related based on various indicators:

  • ○
    CITATION.cff file
  • ○
    codemeta.json file
  • ○
    .zenodo.json file
  • ○
    DOI references
  • ○
    Academic publication links
  • ✓
    Committers with academic emails
    1 of 3 committers (33.3%) from academic institutions
  • ○
    Institutional organization owner
  • ○
    JOSS paper metadata
  • ○
    Scientific vocabulary similarity
    Low similarity (15.5%) to scientific vocabulary

Keywords

eia eia-api energy energy-data python

Keywords from Contributors

projection interactive serializer measurement cycles packaging charts network-simulation archival shellcodes
Last synced: 6 months ago · JSON representation

Repository

An Energy Information Administration (EIA) API python client for researchers who just need data.

Basic Info
  • Host: GitHub
  • Owner: thomastu
  • Language: Python
  • Default Branch: main
  • Homepage:
  • Size: 154 KB
Statistics
  • Stars: 29
  • Watchers: 3
  • Forks: 6
  • Open Issues: 5
  • Releases: 0
Topics
eia eia-api energy energy-data python
Created almost 11 years ago · Last pushed about 3 years ago
Metadata Files
Readme

README.md

Configuration

You can configure pyeia with your API key either at runtime.

  • Declare EIA_APIKEY="myapikey" in a .env file
  • Set an environment variable explicitly, export EIA_APIKEY="myapikey"
  • If you are using dynaconf, you can include an [eia] environment in your settings.toml file (or any other configured settings files.)

toml [eia] apikey = "my apikey"

About

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.

Basic Usage

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. :

bash pip install pyeia pip show pyeia

There are two main strategies for interacting with this package.

EIA Browser

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.

Running the 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.

  1. Browser Quickstart to Collect AEO data
  2. Computing Marginal Values for AEO data

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 Series and Geoset classes have a special query_df method since their response bodies have a naturally tabular schema.

```python 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.CNSMDEUTOTDNADEUNAENCQBTU.A", "AEO.2015.REF2015.CNSMENUALLSNADFODELVENCQBTU.A", apikey=myapikey, ) series.todict() # 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", apikey=myapikey) geoset.todict() geoset.query_df()

Make a call to the SeriesCategory endpoint

seriescategory = api.SeriesCategory( "AEO.2015.REF2015.CNSMDEUTOTDNADEUNAENCQBTU.A", "AEO.2015.REF2015.CNSMENUALLSNADFODELVENCQBTU.A", apikey=myapikey, ) seriescategory.todict()

Make a call to the Updates endpoint

updates = api.Updates( categoryid=2102358, rows=0, firstrow="currentlynotused", deep=False, apikey=myapikey, ) updates.to_dict()

Make a call to the Search endpoint

search = api.Search(api_key=myapikey)

Make a series_id search

search.todict("seriesid", "EMICO2COMMNACLNANA_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.todict("lastupdated", ["Dec. 1st, 2014", "06/14/2015 3:45PM"]) ```

Owner

  • Name: Thomas Tu
  • Login: thomastu
  • Kind: user
  • Location: Berkeley, CA

Software/data engineer working in energy efficiency.

GitHub Events

Total
  • Watch event: 4
Last Year
  • Watch event: 4

Committers

Last synced: 6 months ago

All Time
  • Total Commits: 57
  • Total Committers: 3
  • Avg Commits per committer: 19.0
  • Development Distribution Score (DDS): 0.474
Past Year
  • Commits: 0
  • Committers: 0
  • Avg Commits per committer: 0.0
  • Development Distribution Score (DDS): 0.0
Top Committers
Name Email Commits
Thomas Tu t****u@g****m 30
Thomas Tu t****u@l****v 25
dependabot[bot] 4****] 2
Committer Domains (Top 20 + Academic)
lbl.gov: 1

Issues and Pull Requests

Last synced: 6 months ago

All Time
  • Total issues: 16
  • Total pull requests: 9
  • Average time to close issues: 10 months
  • Average time to close pull requests: about 2 months
  • Total issue authors: 3
  • Total pull request authors: 3
  • Average comments per issue: 1.06
  • Average comments per pull request: 0.0
  • Merged pull requests: 5
  • Bot issues: 0
  • Bot pull requests: 5
Past Year
  • Issues: 0
  • Pull requests: 0
  • Average time to close issues: N/A
  • Average time to close pull requests: N/A
  • Issue authors: 0
  • Pull request authors: 0
  • Average comments per issue: 0
  • Average comments per pull request: 0
  • Merged pull requests: 0
  • Bot issues: 0
  • Bot pull requests: 0
View more stats
Top Authors
Issue Authors
  • thomastu (14)
  • MattEwen (1)
  • lydonjj (1)
Pull Request Authors
  • dependabot[bot] (5)
  • thomastu (3)
  • gitter-badger (1)
Top Labels
Issue Labels
Pull Request Labels
dependencies (5)

Packages

  • Total packages: 1
  • Total downloads:
    • pypi 18 last-month
  • Total dependent packages: 0
  • Total dependent repositories: 1
  • Total versions: 6
  • Total maintainers: 1
pypi.org: pyeia

Python client for the Energy Information Administration (EIA) API

  • Versions: 6
  • Dependent Packages: 0
  • Dependent Repositories: 1
  • Downloads: 18 Last month
Rankings
Dependent packages count: 7.4%
Stargazers count: 12.2%
Forks count: 14.3%
Average: 20.0%
Dependent repos count: 22.2%
Downloads: 43.8%
Maintainers (1)
thtu
Last synced: 6 months ago

Dependencies

poetry.lock pypi
  • appdirs 1.4.4 develop
  • atomicwrites 1.4.0 develop
  • attrs 20.2.0 develop
  • black 19.10b0 develop
  • iniconfig 1.1.1 develop
  • packaging 20.4 develop
  • pathspec 0.8.0 develop
  • pluggy 0.13.1 develop
  • py 1.10.0 develop
  • pyparsing 2.4.7 develop
  • pytest 6.1.2 develop
  • regex 2020.10.28 develop
  • toml 0.10.2 develop
  • typed-ast 1.4.1 develop
  • certifi 2020.6.20
  • chardet 3.0.4
  • click 7.1.2
  • colorama 0.4.4
  • dynaconf 3.1.2
  • h11 0.9.0
  • h2 3.2.0
  • hpack 3.0.0
  • hstspreload 2020.10.20
  • httpcore 0.9.1
  • httpx 0.13.3
  • hyperframe 5.2.0
  • idna 2.10
  • loguru 0.5.3
  • numpy 1.21.0
  • pandas 1.1.4
  • python-dateutil 2.8.1
  • pytz 2020.4
  • rfc3986 1.4.0
  • six 1.15.0
  • sniffio 1.2.0
  • win32-setctime 1.0.3
pyproject.toml pypi
  • black ^19.10b0 develop
  • pytest ^6.0.1 develop
  • click ^7.1.2
  • dynaconf ^3.0.0
  • httpx ^0.13.3
  • loguru ^0.5.1
  • pandas ^1.1.0
  • python ^3.8
.github/workflows/codeql-analysis.yml actions
  • actions/checkout v2 composite
  • github/codeql-action/analyze v1 composite
  • github/codeql-action/autobuild v1 composite
  • github/codeql-action/init v1 composite