Package overview

This vignette provides a brief overview to the most important functions in eia. Other vignettes go into greater depth on specific topics and API endpoints.

Note: This package version of the introduction vignette does not show the results of examples. Code is not executed because an API key is not present. See the full set of examples with code execution at the package website

API key

Register a key with EIA

Obtaining an API key is easy and free.

Pulling data from the US Energy Information Administration (EIA) API requires a registered API key. A key can be obtained at no cost here. A valid email and agreement to the API Terms of Service is required to obtain a key.

It is important to store your API key somewhere secure. Do not commit it to a repository or otherwise share it. For example, you could store it in your .Renviron file.

Key storage and retrieval

You can always provide the key argument to every API function call, but you do not have to. There are getter and setter helpers available to make using eia functions a more seamless experience.

eia_set_key gives you the option of storing your key for the duration of your R session:

If the key already exists in the system environment and you plan to pass key to functions explicitly, you could start as follows:

See the vignette on API details for more information about all the options you have for key storage.

EIA categories

Once you have your EIA registered API key and have it in place for your R session by whichever method you prefer, you are ready to begin accessing data from the EIA API.

It is helpful to be aware of various categories of data that are available. Each category has a unique ID number that is required to access associated data. The first call below does not include an ID. The result is a list of two data frames. The first is metadata associated with that position in the category hierarchy. The second is the child category information.

Here is the top-level category information:

eia_cats()

The child category IDs can be used to query results from that category.

eia_cats(0)

EIA time series data

Time series data is obtained by series ID. Most columns contain metadata. The data column contains the time series data.

id <- "ELEC.GEN.ALL-AK-99.A"
(x1 <- eia_series(id, n = 5))

x1$data[[1]]

You can provide arguments like the following:

eia_series(id) # max results
eia_series(id, n = 5) # most recent five
eia_series(id, end = 2016, n = 5) # ending in 2016
eia_series(id, start = 2000, end = 2016) # specific period

As with eia_cats, the output format does not need to be tidy:

eia_series(id, n = 5, tidy = FALSE) # results of jsonlite::fromJSON
eia_series(id, n = 5, tidy = NA) # origina JSON as character string

This allows you to use the returned results with existing code you may have that requires data in one of these less processed structures.

EIA geosets

Geosets are metadata structures organizing time series datasets that can be mapped. Arguments to eia_geoset are the same as eia_series with the addition of region. Like id, region can be a vector. Most of the details are the same as before.

In the example below using total electricity generation, get the last two data points for each of and two US states. dplyr and tidyr are used here to clean up the result a bit for purposes of display.

id <- c("ELEC.GEN.ALL-99.A")
region <- c("USA-CA", "USA-NY")
(x <- eia_geoset(id, region, n = 2))

library(dplyr)
library(tidyr)
select(x, region, data) %>% unnest()

Another convenience of eia_geoset is the ability to provide regions in the following forms:

These shortcuts make it easier to construct an API call involving several states:

region <- c("AK", "New England")
(x <- eia_geoset(id, region, n = 2))

select(x, region, data) %>% unnest()

Even more convenient is that these names are available in R. See the datasets::state.* functions and the geoset vignette.