EIA categories

Top level categories

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.

library(eia)
# eia_set_key("yourkey") # set API key if not already set globally

Here is the top-level category information.

eia_cats()
#> $category
#> # A tibble: 1 x 3
#>   category_id name          notes
#>   <chr>       <chr>         <chr>
#> 1 371         EIA Data Sets ""   
#> 
#> $childcategories
#> # A tibble: 13 x 2
#>    category_id name                               
#>          <int> <chr>                              
#>  1           0 Electricity                        
#>  2       40203 State Energy Data System (SEDS)    
#>  3      714755 Petroleum                          
#>  4      714804 Natural Gas                        
#>  5      711224 Total Energy                       
#>  6      717234 Coal                               
#>  7      829714 Short-Term Energy Outlook          
#>  8     1292190 Crude Oil Imports                  
#>  9     2123635 U.S. Electric System Operating Data
#> 10     2134384 International Energy Data          
#> 11     2251604 CO2 Emissions                      
#> 12     2631064 International Energy Outlook       
#> 13     2889994 U.S. Nuclear Outages

Child categories

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

eia_cats(0)
#> $category
#> # A tibble: 1 x 4
#>   category_id parent_category_id name        notes
#>   <chr>       <chr>              <chr>       <chr>
#> 1 0           371                Electricity ""   
#> 
#> $childcategories
#> # A tibble: 19 x 2
#>    category_id name                                                              
#>          <int> <chr>                                                             
#>  1           1 Net generation                                                    
#>  2          35 Total consumption                                                 
#>  3          32 Total consumption (Btu)                                           
#>  4          36 Consumption for electricity generation                            
#>  5          33 Consumption for electricity generation (Btu)                      
#>  6          37 Consumption for useful thermal output                             
#>  7          34 Consumption for useful thermal output (Btu)                       
#>  8        1017 Plant level data                                                  
#>  9          38 Retail sales of electricity                                       
#> 10          39 Revenue from retail sales of electricity                          
#> 11          40 Average retail price of electricity                               
#> 12     1718389 Number of customer accounts                                       
#> 13       41137 Fossil-fuel stocks for electricity generation                     
#> 14       41138 Receipts of fossil fuels by electricity plants                    
#> 15       41139 Receipts of fossil fuels by electricity plants (Btu)              
#> 16       41140 Average cost of fossil fuels for electricity generation           
#> 17       41141 Average cost of fossil fuels for electricity generation (per Btu) 
#> 18       41142 Quality of fossil fuels in electricity generation : sulfur content
#> 19       41143 Quality of fossil fuels in electricity generation : ash content

View the immediate child categories for a given parent category.

eia_child_cats(389)
#> # A tibble: 4 x 2
#>   category_id name             
#>         <int> <chr>            
#> 1         742 Coal             
#> 2         743 Petroleum liquids
#> 3         744 Petroleum coke   
#> 4         745 Natural gas

Parent categories

View all parent categories for a given child category.

eia_parent_cats(742)
#> # A tibble: 6 x 4
#>   category_id name                    notes parent_category_id
#>   <chr>       <chr>                   <chr> <chr>             
#> 1 371         EIA Data Sets           ""    <NA>              
#> 2 0           Electricity             ""    371               
#> 3 32          Total consumption (Btu) ""    0                 
#> 4 372         By sector               ""    32                
#> 5 389         Electric utility        ""    372               
#> 6 742         Coal                    ""    389

Output format

The default is to return tidy data in a tibble data frame. For eia_cats you can set tidy = FALSE to return the list returned by jsonlite::fromJSON without any further processing or tidy = NA to return the raw JSON data as a character string.

eia_cats(tidy = FALSE)
#> $request
#> $request$category_id
#> [1] 371
#> 
#> $request$command
#> [1] "category"
#> 
#> 
#> $category
#> $category$category_id
#> [1] "371"
#> 
#> $category$parent_category_id
#> NULL
#> 
#> $category$name
#> [1] "EIA Data Sets"
#> 
#> $category$notes
#> [1] ""
#> 
#> $category$childcategories
#>    category_id                                name
#> 1            0                         Electricity
#> 2        40203     State Energy Data System (SEDS)
#> 3       714755                           Petroleum
#> 4       714804                         Natural Gas
#> 5       711224                        Total Energy
#> 6       717234                                Coal
#> 7       829714           Short-Term Energy Outlook
#> 8      1292190                   Crude Oil Imports
#> 9      2123635 U.S. Electric System Operating Data
#> 10     2134384           International Energy Data
#> 11     2251604                       CO2 Emissions
#> 12     2631064        International Energy Outlook
#> 13     2889994                U.S. Nuclear Outages
#> 
#> $category$childseries
#> list()
cat(eia_cats(tidy = NA))
#> {"request":{"category_id":371,"command":"category"},"category":{"category_id":"371","parent_category_id":null,"name":"EIA Data Sets","notes":"","childcategories":[{"category_id":0,"name":"Electricity"},{"category_id":40203,"name":"State Energy Data System (SEDS)"},{"category_id":714755,"name":"Petroleum"},{"category_id":714804,"name":"Natural Gas"},{"category_id":711224,"name":"Total Energy"},{"category_id":717234,"name":"Coal"},{"category_id":829714,"name":"Short-Term Energy Outlook"},{"category_id":1292190,"name":"Crude Oil Imports"},{"category_id":2123635,"name":"U.S. Electric System Operating Data"},{"category_id":2134384,"name":"International Energy Data"},{"category_id":2251604,"name":"CO2 Emissions"},{"category_id":2631064,"name":"International Energy Outlook"},{"category_id":2889994,"name":"U.S. Nuclear Outages"}],"childseries":[]}}