EIA

An R package wrapping the US Energy Information Administration open data API.
https://github.com/ropensci/eia

Category: Energy Systems
Sub Category: Energy Data Accessibility and Integration

Keywords

cran eia eia-api energy-data energy-information-administration open-data r-package

Keywords from Contributors

geocoding

Last synced: about 3 hours ago
JSON representation

Repository metadata

An R package wrapping the US Energy Information Administration open data API.

README.Rmd

          ---
output: github_document
---



```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE, comment = "#>", out.width = "100%",
  fig.path = "man/figures/README-", fig.width = 7, fig.height = 4, dpi = 150,
  message = FALSE, warning = FALSE, error = FALSE
)
library(eia)
library(ggplot2)
```

# eia 


[![Project Status: Active – The project has reached a stable, usable state and is being actively developed.](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/)
[![R-CMD-check](https://github.com/ropensci/eia/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/ropensci/eia/actions/workflows/R-CMD-check.yaml)
[![Codecov test coverage](https://codecov.io/gh/ropensci/eia/branch/master/graph/badge.svg)](https://app.codecov.io/gh/ropensci/eia?branch=master)
[![](https://badges.ropensci.org/342_status.svg)](https://github.com/ropensci/software-review/issues/342)
[![CRAN status](https://www.r-pkg.org/badges/version/eia)](https://cran.r-project.org/package=eia)
[![CRAN RStudio mirror downloads](https://cranlogs.r-pkg.org/badges/eia)](https://cran.r-project.org/package=eia)
[![Github Stars](https://img.shields.io/github/stars/ropensci/eia.svg?style=social&label=Github)](https://github.com/ropensci/eia)


The `eia` package provides API access to data from the US [Energy Information Administration](https://www.eia.gov/) (EIA).

Pulling data from the US Energy Information Administration (EIA) API requires a registered API key.
A key can be obtained at no cost [here](https://www.eia.gov/opendata/register.php).
A valid email and agreement to the API Terms of Service is required to obtain a key.

`eia` includes functions for searching the EIA API data directory and importing various datasets.
Datasets returned by these functions are provided in a tidy format or alternatively in more raw form.
It also offers helper functions for working with EIA API date strings and time formats and for
inspecting different summaries of data metadata. The package also provides control over API key
storage and caching of API request results.

## Installation

Install the CRAN release of `eia` with

```{r instl1, eval=FALSE}
install.packages("eia")
```

or install the development version from GitHub with

```{r instl2, eval=FALSE}
# install.packages("remotes")
remotes::install_github("ropensci/eia")
```

## Example

After obtaining the API key, store it somewhere such as `.Renviron` and never have
to do anything with the key when using the package. Alternatively, set it manually
with `eia_set_key()` in the current R session. Further, it can always be passed
explicitly to the `key` argument of a given `eia` function.

### Load package and set key

```{r xmpl1, eval=FALSE}
library(eia)

# not run
eia_set_key("yourkey") # set API key if not already set globally
```

### Explore the API directory

Get a list of the EIA's data directory (and sub-directories) with `eia_dir()`.

```{r xmpl2}
# Top-level directory
eia_dir()

# Electricity sub-directory
eia_dir("electricity")
```

### Get data

Get annual retail electric sales for the Ohio residential sector since 2010

```{r xmpl3}
(d <- eia_data(
  dir = "electricity/retail-sales",
  data = "sales",
  facets = list(stateid = "OH", sectorid = "RES"),
  freq = "annual",
  start = "2010",
  sort = list(cols = "period", order = "asc"),
))
```

and make a nice plot.

```{r plt}
library(ggplot2)
ggplot(d, aes(x = period, y = sales / 1e3)) +
  geom_bar(col = "steelblue", fill = "steelblue", stat = "identity") +
  theme_bw() +
  labs(
    title = "Annual Retail Sales of Electricity (GWh)",
    subtitle = "State: Ohio; Sector: Residential",
    x = "Year", y = "Sales (GWh)"
  )
```

## References

See the collection of vignette tutorials and examples as well as complete package
documentation available at the `eia` package [website](https://docs.ropensci.org/eia/).

---

Please note that the `eia` project is released with
a [Contributor Code of Conduct](https://github.com/ropensci/eia/blob/master/CODE_OF_CONDUCT.md).
By contributing to this project, you agree to abide by its terms.

[![ropensci_footer](https://ropensci.org/public_images/ropensci_footer.png)](https://ropensci.org)

        

Owner metadata


GitHub Events

Total
Last Year

Committers metadata

Last synced: 8 days ago

Total Commits: 296
Total Committers: 6
Avg Commits per committer: 49.333
Development Distribution Score (DDS): 0.453

Commits in past year: 191
Committers in past year: 3
Avg Commits per committer in past year: 63.667
Development Distribution Score (DDS) in past year: 0.152

Name Email Commits
Matthew Hoff m****f@g****m 162
leonawicz m****z@e****m 102
leonawicz m****z@g****m 28
Maëlle Salmon m****n@y****e 2
David Ranzolin d****n@g****m 1
James Lamb j****0@g****m 1

Committer domains:


Issue and Pull Request metadata

Last synced: 1 day ago

Total issues: 13
Total pull requests: 12
Average time to close issues: 9 months
Average time to close pull requests: 5 days
Total issue authors: 9
Total pull request authors: 5
Average comments per issue: 3.31
Average comments per pull request: 0.25
Merged pull request: 12
Bot issues: 0
Bot pull requests: 0

Past year issues: 0
Past year pull requests: 1
Past year average time to close issues: N/A
Past year average time to close pull requests: 1 day
Past year issue authors: 0
Past year pull request authors: 1
Past year average comments per issue: 0
Past year average comments per pull request: 0.0
Past year merged pull request: 1
Past year bot issues: 0
Past year bot pull requests: 0

More stats: https://issues.ecosyste.ms/repositories/lookup?url=https://github.com/ropensci/eia

Top Issue Authors

  • leonawicz (4)
  • jameelalsalam (2)
  • msgoussi (1)
  • mtkerbeR (1)
  • rdavis120 (1)
  • leungi (1)
  • tanga94 (1)
  • bobweeks (1)
  • morrisseyj (1)

Top Pull Request Authors

  • mghoff (5)
  • leonawicz (3)
  • maelle (2)
  • daranzolin (1)
  • jameslamb (1)

Top Issue Labels

  • help wanted (2)
  • documentation (1)

Top Pull Request Labels


Package metadata

cran.r-project.org: eia

API Wrapper for U.S. Energy Information Administration ('EIA') Open Data

  • Homepage: https://docs.ropensci.org/eia/
  • Documentation: http://cran.r-project.org/web/packages/eia/eia.pdf
  • Licenses: MIT + file LICENSE
  • Latest release: 0.4.2 (published about 1 year ago)
  • Last Synced: 2025-04-29T14:02:53.957Z (1 day ago)
  • Versions: 8
  • Dependent Packages: 0
  • Dependent Repositories: 1
  • Downloads: 305 Last month
  • Rankings:
    • Dependent repos count: 23.981%
    • Downloads: 24.253%
    • Average: 25.662%
    • Dependent packages count: 28.751%
  • Maintainers (1)

Dependencies

DESCRIPTION cran
  • dplyr * imports
  • httr * imports
  • jsonlite * imports
  • lubridate * imports
  • magrittr * imports
  • memoise * imports
  • purrr * imports
  • readxl * imports
  • tibble * imports
  • covr * suggests
  • ggplot2 * suggests
  • knitr * suggests
  • rmarkdown * suggests
  • testthat * suggests
  • tidyr * suggests
.github/workflows/R-CMD-check.yaml actions
  • actions/checkout v3 composite
  • r-lib/actions/check-r-package v2 composite
  • r-lib/actions/setup-pandoc v2 composite
  • r-lib/actions/setup-r v2 composite
  • r-lib/actions/setup-r-dependencies v2 composite
.github/workflows/test-coverage.yaml actions
  • actions/checkout v3 composite
  • actions/upload-artifact v3 composite
  • r-lib/actions/setup-r v2 composite
  • r-lib/actions/setup-r-dependencies v2 composite

Score: 11.36875481852531