API details

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.

Key storage and retrieval

It is important to store your API key somewhere secure. Do not commit it to a repository or otherwise share it. For example, you can store it in your .Renviron file. This is the recommended method for simplicity and persistent availability. If you do this, you do not have to do anything else. Other approaches that allow for emphemeral storage or overriding a default key with another key are outlined below.

You can always provide the key argument to every API function call, but you do not have to. There are environmental getter and setter functions available. Whichever method you use to set your key environmentally, eia API functions can get the key implicitly.

eia_set_key() gives you the option of storing your key in any of three places via the store argument:

• store = "env": the package environment that is created when the package is loaded (default method)
• store = "options": in the global options()
• store = "sysenv": as a system environment variable via Sys.setenv().

The last two options require the name-value pair to be named EIA_KEY = "yourkey". These three options also are the order of precedence if you do not specify the store argument.

This setup also allows you to store a key that will override another key. This is because eia_get_key() checks these three storage methods in this order and stops as soon as it finds a key. If you need it to check a specific location, you can specify store.

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

library(eia)
key <- Sys.getenv("EIA_KEY")
# or:
key <- eia_get_key()

If you need to set it, you can do so as follows.

# eia_set_key("yourkey")
# eia_get_key() # retrieve it

API functions in eia use eia_get_key() with no arguments as the default value of their key argument, checking in the order shown above for an existing key. This way you do not need to repeatedly provide it.

Note that despite the name and behavior, storing an environment variable with Sys.setenv() (and thus eia_set_key(key, store = "sysenv")) is not persistent; the key is lost when the R session terminates, just as it is with the other two session-based options. If you want a persistent key, you must manually add your key somewhere like .Renviron. In that cases, you never need eia_set_key() and eia_get_key() will retrieve the EIA_KEY environment variable. See the package documentation for more details on key options.

In this and subsequent vignettes, you will not see a key being set because it is already an environment variable. You will also not see it used explicitly by any functions because the default behavior is to look up the key in the environment.

API requests

The EIA API can of course impose its own rate-limiting and other limitations on usage by a given API key. If you use the API improperly or otherwise violate any Terms of Service, the EIA may withdraw your API access. However, the eia package also helps prevent accidental overuse by having default settings that limit the potential for making unnecessary API calls. It does this in two ways, both of which allow optional configuration:

• caching API results in memory using session-based memoization
• minimum delay between API calls

By default the eia package prevents you from accidentally making too many requests too quickly, but it also offers sensible flexibility.

Memoization

All functions in eia that make API calls use memoization by default. They will not make the same API call twice in one R session. A call is made once and the result is cached. Calling the same function with the identical arguments again will only returned the cached result.

This approach limits the potential for accidentally using the EIA API more than necessary. This is fine for most uses cases. However, if you use your API key to access data that is updated very often, or you have a long-running R process such as a Shiny app on a server that may need to periodically update the data associated with a specific API call, you can set cache = FALSE.

Run this example of the same request made with and without memoization. You will notice the cached result by the immediate return.

system.time(eia_dir()) # API call; cache result
system.time(eia_dir()) # read from cache
system.time(eia_dir(cache = FALSE)) # API call

Results are cached in memory for the duration of the R session, but you can clear the cache at any time.

eia_clear_cache()
system.time(eia_dir())

This allows you to update the cached result. You can reset the cache for only specific endpoints using the following functions.

• eia_clear_dir()
• eia_clear_metadata()
• eia_clear_data()
• eia_clear_facets()

Anti-DOS measures

Regardless of overall rate limiting imposed by the EIA API, the eia package sets a minimum wait time of one second between successive API calls. In most cases this is an irrelevant safeguard. Most eia functions make a single API call and requests for data often take a full second anyway once you factor in the subsequent data manipulation in R.

However, there are cases where you might want to make multiple calls back to back programmatically and perhaps you are initially unsure how many requests will be made or how quickly these requests may execute. The default minimum wait between API calls is a precaution that helps you be a good neighbor.

You can turn this off with options() if not needed; for example, a case where you know that your API calls will be small in number and you have no reason to be concerned about exceeding the request limits associated with your API key. The default requires you to make an active decision about how to use the API with your own key and API limits in mind.