| Title: | API Wrapper for U.S. Energy Information Administration ('EIA')Open Data |
| Version: | 0.4.2 |
| Description: | Provides API access to data from the U.S. Energy Information Administration ('EIA')https://www.eia.gov/. Use of the EIA's API and this package requires a free API key obtainable athttps://www.eia.gov/opendata/register.php. This package includes functions for searching the EIA data directory and returning time series and geoset time series datasets. Datasets returned by these functions are provided by default in a tidy format, or alternatively, in more raw formats. It also offers helper functions for working with EIA date strings and time formats and for inspecting different summaries of series metadata. The package also provides control over API key storage and caching of API request results. |
| License: | MIT + file LICENSE |
| URL: | https://docs.ropensci.org/eia/,https://github.com/ropensci/eia |
| BugReports: | https://github.com/ropensci/eia/issues |
| Imports: | tibble, httr, jsonlite, memoise, lubridate |
| Suggests: | testthat (≥ 3.0.0), knitr, covr, rmarkdown, dplyr, tidyr,ggplot2, spelling |
| VignetteBuilder: | knitr |
| Config/testthat/edition: | 3 |
| Encoding: | UTF-8 |
| Language: | en-US |
| RoxygenNote: | 7.3.1 |
| NeedsCompilation: | no |
| Packaged: | 2024-04-15 16:05:25 UTC; mghoff |
| Author: | Matthew Leonawicz [aut], Matthew Hoff [aut, cre] |
| Maintainer: | Matthew Hoff <matthew.g.hoff@gmail.com> |
| Repository: | CRAN |
| Date/Publication: | 2024-04-15 19:10:13 UTC |
eia: EIA API wrapper
Description
This package provides API access to data from the USEnergy Information Administration (EIA).
Author(s)
Maintainer: Matthew Hoffmatthew.g.hoff@gmail.com
Authors:
Matthew Leonawicz (ORCID)
See Also
Useful links:
Report bugs athttps://github.com/ropensci/eia/issues
Clear API results cache
Description
Reset the results of API calls that are currently cached in memory.
Usage
eia_clear_cache()eia_clear_dir()eia_clear_metadata()eia_clear_data()eia_clear_facets()Details
eia_clear_cache() clears the entire cache. The other functions clear thecache associated with specific endpoints.
Examples
## Not run: key <- Sys.getenv("EIA_KEY") # your stored API keysystem.time(eia_dir(key))system.time(eia_dir(key))eia_clear_cache()system.time(eia_dir(key))## End(Not run)EIA data
Description
Obtain data from the EIA.
Usage
eia_data( dir, data = NULL, facets = NULL, freq = NULL, start = NULL, end = NULL, sort = NULL, length = NULL, offset = NULL, tidy = TRUE, check_metadata = FALSE, cache = TRUE, key = eia_get_key())Arguments
dir | character, directory path. |
data | character or
|
facets | character list or |
freq | character or |
start,end | character or |
sort | named list of two.
|
length | numeric or |
offset | numeric or |
tidy | logical or |
check_metadata | logical, if |
cache | logical, cache result for duration of R session using memoization.See details. |
key | API key: character if set explicitly; not needed if key is setglobally. See |
Details
By default,data,facets, andfreq are set toNULL. To obtain validinput values for each of these arguments, use the specific ID labelsas provided byeia_metadata().
The use ofstart andend require some input tofreq.By default (check_metadata = FALSE), the resulting data will match thetemporal resolution provided tofreq, however,check_metadata = TRUE appliesfurther restrictions such that the format of values provided tostart/end must matchthat offreq. Furthermore, regardless of the input format provided tostart/end,the resulting data will always match the specification offreq. And lastly,regardless of chosen format,end must be strictly greater thanstart to return data.
By default, additional processing is done to return a list containing tibble data frames.Settidy = FALSE to return only the initial list result ofjsonlite::fromJSON.Settidy = NA to return the original JSON as a character string.
Set tocache = FALSE to force a new API call for updated data.UsingFALSE always makes a new API call and returns the result from the server.TRUE uses memoization on a per R session basis, caching the result of thefunction call in memory for the duration of the R session.You can reset the entire cache by callingeia_clear_cache().
Value
data frame
Examples
## Not run: eia_data( dir = "electricity/retail-sales", data = "price", facets = list(sectorid = c("COM", "RES"), stateid = "OH"))## End(Not run)EIA directory
Description
Obtain EIA directory listing.
Usage
eia_dir(dir = NULL, tidy = TRUE, cache = TRUE, key = eia_get_key())Arguments
dir | character, directory path, if |
tidy | logical, return a tidier result. See details. |
cache | logical, cache result for duration of R session using memoization.See details. |
key | API key: character if set explicitly; not needed if key is setglobally. See |
Details
By default, additional processing is done to return a list containing tibble data frames.Settidy = FALSE to return only the initial list result ofjsonlite::fromJSON().Settidy = NA to return the original JSON as a character string.
Set tocache = FALSE to force a new API call for updated data.UsingFALSE always makes a new API call and returns the result from the server.TRUE uses memoization on a per R session basis, caching the result of thefunction call in memory for the duration of the R session.You can reset the entire cache by callingeia_clear_cache().
Value
data frame, list, or character; see details.
Examples
## Not run: # use eia_set_key() to store API keyeia_dir()eia_dir("electricity")eia_dir("electricity/rto")## End(Not run)EIA facets
Description
Obtain facets for a given set of EIA data.
Usage
eia_facets(dir, facet, tidy = TRUE, cache = TRUE, key = eia_get_key())Arguments
dir | character, directory path. |
facet | character |
tidy | logical, return a tidier result. See details. |
cache | logical, cache result for duration of R session using memoization.See details. |
key | API key: character if set explicitly; not needed if key is setglobally. See |
Details
By default, additional processing is done to return a list containing tibble data frames.Settidy = FALSE to return only the initial list result ofjsonlite::fromJSON().Settidy = NA to return the original JSON as a character string.
Set tocache = FALSE to force a new API call for updated data.UsingFALSE always makes a new API call and returns the result from the server.TRUE uses memoization on a per R session basis, caching the result of thefunction call in memory for the duration of the R session.You can reset the entire cache by callingeia_clear_cache().
Value
data frame, list, or character; see details.
Examples
## Not run: eia_facets("electricity/retail-sales", facet = "sectorid")## End(Not run)Set and get API key
Description
Set and get API key
Usage
eia_set_key(key, store = c("env", "options", "sysenv"))eia_get_key(store = c("env", "options", "sysenv"))Arguments
key | character, API key. |
store | character, method for storing API key. See details. |
Details
Setter and getter helpers allow you to store your EIA API key in one ofthree ways. Their use is optional. You can always pass the API key string tothekey argument of any package function that requires it, but you do nothave to.
By default thekey argument for these functions iskey = eia_get_key().If your key has been stored in a manner that can be retrieved, then you cancall all the package API functions without having to provide thekeyargument repeatedly.
Value
eia_get_key() returns the key string orNULL with a warning.eia_set_key() returns a success message or an error.
Key storage methods
If you have already set your key globally somewhere usingeia_set_key(),eia_get_key() will retrieve it. You can add theEIA_KEY = "yourkey"key-value pair tooptions() or as a system environment variable yourselfandeia_get_key() will pick it up as long as you use the nameEIA_KEY.For convenience you can do this in your R session witheia_set_key(). Itgives you three options for how to store the key. The default is to use theeia package environment that is created when the package is loaded.
Precedence
Choose one method when setting a key. When getting the key, the threelocations are checked in the order: package environment,options(), thenthe system environment. To override the order, specify the method explicitlyand the check will only occur there. This also makes it possible to overridea system level key by working with one stored in the package environment oroptions().
Persistence
Note that none of these three storage methods, including"sysenv" arepersistent; the stored key is lost when the R session is terminated. A keythat is stored outside of R as a system environment variable is retrievablewitheia_get_key(), just like those set in an R session witheia_set_key()andstore = "sysenv". However, if you truly want the key to persist as anenvironment variable when R terminates, you must manually add it somewherelike.Renviron;Sys.setenv in R cannot achieve this.
Examples
eia_set_key("fake")eia_get_key()# eia_get_key("options") # `NULL` with warning if not set where specifiedEIA metadata
Description
Obtain EIA data metadata
Usage
eia_metadata(dir, tidy = TRUE, cache = TRUE, key = eia_get_key())Arguments
dir | character, directory path. |
tidy | logical, return a tidier result. See details. |
cache | logical, cache result for duration of R session using memoization.See details. |
key | API key: character if set explicitly; not needed if key is setglobally. See |
Details
By default, additional processing is done to return a list containing tibble data frames.Settidy = FALSE to return only the initial list result ofjsonlite::fromJSON().Settidy = NA to return the original JSON as a character string.
Set tocache = FALSE to force a new API call for updated data.UsingFALSE always makes a new API call and returns the result from the server.TRUE uses memoization on a per R session basis, caching the result of thefunction call in memory for the duration of the R session.You can reset the entire cache by callingeia_clear_cache().
Value
named list or character; see details.
Examples
## Not run: eia_dir("electricity/retail-sales")eia_metadata("electricity/retail-sales")## End(Not run)EIA date parsing
Description
Helper functions for manipulating and converting between regularyear-month-day date strings and EIA date string notation.
Usage
eiadate_to_date(x)date_to_eiadate(x, date_format = c("A", "Q", "M", "W", "D", "H"))eiadate_to_date_seq(start, end, weekly = FALSE)Arguments
x | character, EIA date string; character or date object for regulardates. See details. |
date_format | EIA date format: "A", "Q", "M", "W", "D", "H".These stand for annual, quarterly, monthly, weekly, daily, hourly. See details. |
start | start EIA date or date. |
end | end EIA date or date. |
weekly | logical. See details. |
Details
There is no reason to mix EIA date formats in this context. Functions thattake EIA date strings expect a consistent format. Also, EIA date formats areparsed automatically from the dates themselves. However, daily and weekly usethe same format. Too avoid ambiguity ineia_date_seq(), daily is assumed;setweekly = TRUE to treat as weekly.
When providing a real date or date string, such as todate_to_eiadate(),dates should be inYYYY-MM-DD format, or at least any format that can beparsed bylubridate::ymd orlubridate::ymd_hms for dates and hourly datetimes, respectively.
"LH" is not a supported date format. Use"H". The API does not translatethe date and time when using"LH" anyhow; it simply appends the date stringwith the number of hours time difference.
Examples
eiadate_to_date(c("2018-03", "2018-04"))date_to_eiadate("2018-05-14", "A")date_to_eiadate("2018-05-14", "Q")date_to_eiadate("2018-05-14", "M")(x <- eiadate_to_date_seq("2018-Q1", "2018-Q4"))date_to_eiadate(x, "Q")date_to_eiadate(x, "M")(x <- eiadate_to_date("2019-01-02T16Z"))date_to_eiadate(x, "H")(x <- eiadate_to_date_seq("2019-01-02T16Z", "2019-01-02T19Z"))date_to_eiadate(x, "H")