Type: Package
Title: Query Data from the 'EIA' API
Version: 0.2.0
Maintainer: Rami Krispin <rami.krispin@gmail.com>
Description: Provides a function to query and extract data from the 'US Energy Information Administration' ('EIA') API V2 https://www.eia.gov/opendata/. The 'EIA' API provides a variety of information, in a time series format, about the energy sector in the US. The API is open, free, and requires an access key and registration at https://www.eia.gov/opendata/.
License: MIT + file LICENSE
Encoding: UTF-8
RoxygenNote: 7.3.2
Depends: R (≥ 4.1.0)
Imports: data.table (≥ 1.14.2), dplyr (≥ 1.0.9), jsonlite (≥ 1.8.2), lubridate (≥ 1.8.0)
Suggests: knitr, plotly (≥ 4.10.0), rmarkdown
SystemRequirements: The package required the jq command line library. Please check https://stedolan.github.io/jq/download/ for download instructions.
URL: https://github.com/RamiKrispin/EIAapi
BugReports: https://github.com/RamiKrispin/EIAapi/issues
NeedsCompilation: no
Packaged: 2025-06-30 06:10:49 UTC; root
Author: Rami Krispin [aut, cre]
Repository: CRAN
Date/Publication: 2025-06-30 06:20:02 UTC

Pull a Large Number of Observations with a Sequential Query

Description

This function allows users to overcome the API's observation limit per query by breaking down the query into smaller sequential sub-queries and appending back the results. The main use case of this function is for backfilling hourly series.

Usage

eia_backfill(start, end, offset, api_key, api_path, facets, data, frequency)

Arguments

start

defines the start time of the series, should use a POSIXt class for hourly series or Date format for non-hourly series (daily, monthly, etc.)

end

defines the end time of the series, should use a POSIXt class for hourly series or Date format for non-hourly series (daily, monthly, etc.)

offset

An integer, defines the number of observations limitation per query. In line with the API limitation of up to 5000 observations per query, the offset argument's upper limit is 5000 observations.

api_key

A string, EIA API key, see https://www.eia.gov/opendata/ for registration to the API service

api_path

A string, the API path to follow the API endpoint https://api.eia.gov/v2/. The path can be found on the EIA API dashboard, for more details see https://www.eia.gov/opendata/browser/

facets

A list, optional, set the filtering argument (defined as 'facets' on the API header), following the structure of list(facet_name_1 = value_1, facet_name_2 = value_2)

data

A string, the metric type, defined as 'data' on the API header

frequency

A string, the series frequency, can be one of the following - hourly, monthly, quarterly, and yearly

Details

The function use start, end, and offset arguments to define a sequence of queries.

Value

A time series

Examples

## Not run: 
start <- as.POSIXlt("2018-06-19T00", tz = "UTC")
end <- lubridate::floor_date(Sys.time() - lubridate::days(2), unit = "day")
attr(end, "tzone") <- "UTC"
offset <- 2000
api_key <- Sys.getenv("eia_key")
api_path <- "electricity/rto/region-sub-ba-data/data/"

facets <- list(
  parent = "NYIS",
  subba = "ZONA"
)

df <- eia_backfill(
  start = start,
  end = end,
  offset = offset,
  api_key = api_key,
  api_path = api_path,
  facets = facets
)

at_y <- pretty(df$value)[c(2, 4, 6)]
at_x <- seq.POSIXt(
  from = start,
  to = end,
  by = "2 years"
)
plot(df$time, df$value,
  col = "#1f77b4",
  type = "l",
  frame.plot = FALSE,
  axes = FALSE,
  panel.first = abline(h = at_y, col = "grey80"),
  main = "NY Independent System Operator (West) - Hourly Generation of Electricity",
  xlab = "Source: https://www.eia.gov/",
  ylab = "MegaWatt/Hours"
)

mtext(
  side = 1, text = format(at_x, format = "%Y"), at = at_x,
  col = "grey20", line = 1, cex = 0.8
)

mtext(
  side = 2, text = format(at_y, scientific = FALSE), at = at_y,
  col = "grey20", line = 1, cex = 0.8
)

## End(Not run)

Query the EIA API

Description

Function to query and extract data from the EIA API v2

Usage

eia_get(
  api_key,
  api_path,
  data = "value",
  facets = NULL,
  start = NULL,
  end = NULL,
  length = NULL,
  offset = NULL,
  frequency = NULL,
  format = "data.frame"
)

Arguments

api_key

A string, EIA API key, see https://www.eia.gov/opendata/ for registration to the API service

api_path

A string, the API path to follow the API endpoint https://api.eia.gov/v2/. The path can be found on the EIA API dashboard, for more details see https://www.eia.gov/opendata/browser/

data

A string, the metric type, by default uses 'value' (defined as 'data' on the API header)

facets

A list, optional, set the filtering argument (defined as 'facets' on the API header), following the structure of list(facet_name_1 = value_1, facet_name_2 = value_2)

start

A string, optional, set the starting date or time of the series using "YYYY-MM-DD" format for date and "YYYY-MM-DDTHH" format for hourly time series

end

A string, optional, set the ending date or time of the series using "YYYY-MM-DD" format for date and "YYYY-MM-DDTHH" format for hourly time series

length

An integer, optional, defines the length of the series, if set to NULL (default), will default to the API default value of 5000 observations per pull. The API enables a pull of up to 100K observations per call. If needed to pull more than the API limit per call, recommend to iterate the call with the use of the start, end and/or offset arguments

offset

An integer, optional, set the number of observations to offset from the default starting point of the series. If set to NULL (default), will default to the API default value of 0

frequency

A string, optional, define the API frequency argument (e.g., hourly, monthly, annual, etc.). If set to NULL (default), will default to the API default value

format

A string, defines the output of the return object to either "data.frame" (default) or "data.table"

Value

data.table/data.frame object

Examples

## Not run: 
# Required an EIA API key to send a query
api_key <- "YOUR_API_KEY"

df <- eia_get(
  api_key = api_key,
  api_path = "electricity/rto/fuel-type-data/data/",
  data = "value"
)

## End(Not run)

Pull Metadata from EIA API

Description

Get data descriptions and metadata from the EIA API

Usage

eia_metadata(api_path = NULL, api_key)

Arguments

api_path

A string, the API category/route path following the API endpoint (i.e., 'https://api.eia.gov/v2/') If set to NULL (default) or as empty string "" it returns the main categories available on the API. The path can be found on the EIA API dashboard, for more details see https://www.eia.gov/opendata/browser/

api_key

A string, EIA API key, see https://www.eia.gov/opendata/ for registration to the API service

Details

The function enables to explore the different data categories and available routes inline with the API dashboard (https://www.eia.gov/opendata/browser/)

Value

a list object with the series description and metadata

Examples

## Not run: 
electricity_metadata <- eia_metadata(api_key = Sys.getenv("eia_key"),
                                     api_path = "electricity")

electricity_metadata$response$description
electricity_metadata$response$id
electricity_metadata$response$name
electricity_metadata$response$routes


## End(Not run)