Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/jameelalsalam/eia2
R package wrapping the US Energy Information Administration API version 2
https://github.com/jameelalsalam/eia2
Last synced: about 1 month ago
JSON representation
R package wrapping the US Energy Information Administration API version 2
- Host: GitHub
- URL: https://github.com/jameelalsalam/eia2
- Owner: jameelalsalam
- License: other
- Created: 2023-01-13T17:37:36.000Z (almost 2 years ago)
- Default Branch: main
- Last Pushed: 2023-10-24T19:00:45.000Z (about 1 year ago)
- Last Synced: 2023-10-25T19:40:15.779Z (about 1 year ago)
- Language: R
- Homepage: https://jameelalsalam.github.io/eia2/
- Size: 392 KB
- Stars: 6
- Watchers: 2
- Forks: 2
- Open Issues: 0
-
Metadata Files:
- Readme: README.Rmd
- License: LICENSE
Awesome Lists containing this project
- jimsghstars - jameelalsalam/eia2 - R package wrapping the US Energy Information Administration API version 2 (R)
README
---
output: github_document
---
```{r, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "man/figures/README-",
out.width = "100%"
)
```
# eia2
[](https://github.com/jameelalsalam/eia2/actions/workflows/R-CMD-check.yaml)
[](https://app.codecov.io/gh/jameelalsalam/eia2?branch=main)
The `eia2` package provides functions to download data from the [US Energy Information Administration Open Data API version 2](https://www.eia.gov/opendata/).
Using the EIA API (via this package or other means) requires a registered API key.
The EIA provides a data browser and documentation of API concepts that is helpful to understanding usage of this package.
## Installation
You can install the development version of eia2 from [GitHub](https://github.com/jameelalsalam/eia2) with:
``` r
# install.packages("devtools")
devtools::install_github("jameelalsalam/eia2")
```
## Authentication
Ensure your API key is available by setting it as an environment variable. You can add it to your user-level .Renviron file by:
``` r
usethis::edit_r_environ("user")
```
And adding a line such as:
EIA_KEY=
After restarting, running `Sys.getenv("EIA_KEY")` or `eia_get_key()` should return your key.
Alternatively, your key can be stored in the package environment or options using `eia_set_key()`. For security, make sure you do not record your API key in files tracked by git or your .Rhistory.
## Explore Available Data
You can browse available datasets:
```{r}
library(eia2)
eia2()
```
And iteratively explore routes within a dataset, such as:
```{r}
eia2("electricity")
```
When you get to the bottom of a route, there won't be any further routes, but you need to specify other parameters to retrieve data, such as which data columns to retrieve.
```{r}
eia2("electricity/retail-sales")
```
And finally download data such as:
```{r}
elec_retail_sales_annual_data <-
eia2("electricity/retail-sales", frequency = "annual", data_cols = "revenue")
elec_retail_sales_annual_data
```
A full API call can also specify facet filters and different start and end dates.
```{r}
elec_retail_CO <-
eia2("electricity/retail-sales",
frequency = "monthly",
facets = list(
stateid = c("CO", "WY")
),
data_cols = c("revenue"),
start = "2020-01",
end = "2020-03")
elec_retail_CO
```
## Moving from API version 1
The EIA version 2 API provides a mechanism to retrieve similar data as was available via the series ID API endpoint in the version 1 API. This web form on the EIA Open Data website can help translate version 1 series IDs into version 2 routes. In addition, this package provides a function `eia1_series` which can make requests using legacy series id's.
```{r}
eia1_series("ELEC.SALES.CO-RES.A")
```
## Specifying Related Data via Parameters and Facets
The EIA version 2 API organizes dataset topics using routes, and then allows specification of various parameters and facets to narrow the specific data being requested.
...
## Acknowledgements
eia2 is based on previous work by Matthew Leonawicz on the [eia](https://github.com/ropensci/eia) package. It has benefited from many useful packages and resources including httr2, ropensci package guide, and HTTP testing for R.
## Disclaimer
This package and its authors are not affiliated with the Energy Information Administration. If you reproduce data it should include an acknowledgement with the publication date, such as: "Source: U.S. Energy Information Administration (Oct 2008)." For more information, please see [EIA's Copyrights and Reuse page](https://www.eia.gov/about/copyrights_reuse.php).