Fetching Data from FRED

Christopher Mann

2021-01-12

The eFRED package makes it easy to import any number of series from the FRED website into a single data.frame.

First, you will need an API key. You can freely obtain one by following the instructions at https://fred.stlouisfed.org/docs/api/api_key.html. The API key is a 32 character, lower-cased string. Once you have registered for one, assign it to a variable or use the set_fred_key function.

library(eFRED)
#> Loading required package: jsonlite
#> Loading required package: httr
api_key <- "abcdefghijklmnopqrstuvwxyz123456"
set_fred_key(api_key)

Almost all of the eFRED functions require an API key. The set_fred_key function sets the default key that is used by the functions so that you do not need to directly pass the key each time the function is called.

FRED data can be extracted by using the fred function. The general format of the function is fred(name1 = "code1", name2 = "code2", ...), where "code" is the unique series ID that can be found next to each series’ title at https://fred.stlouisfed.org/, and name is the new label for the series in the resulting data.frame. If no name is provided, then the code will be used. Any number of series can be used and each code can be a character vector containing with multiple entries.

The following searches for two series: “GDPC1” (Real GDP) and “UNRATE” (unemployment rate).

df <- fred(y = "GDPC1", "unrate", all=FALSE)
head(df)
#>         date        y UNRATE
#> 1 1948-01-01 2086.017    3.4
#> 2 1948-04-01 2120.450    3.9
#> 3 1948-07-01 2132.598    3.6
#> 4 1948-10-01 2134.981    3.7
#> 5 1949-01-01 2105.562    4.3
#> 6 1949-04-01 2098.380    5.3

The column containing the data for GDP is named "y". Since no name was provided for "UNRATE", the column name is the same as the series. Note that the codes are not case sensitive. The fred function automatically converts all codes to uppercase. The last argument, all=FALSE, is included because GDP and the unemployment rate have different frequencies (quarterly vs annual) and different starting periods. When all=FALSE is used, the data.frame forces each value to the shortest series; otherwise, the frequency would be monthly with many NA values for y.

The raw information about each series is contained within the data.frame’s info attribute, unless info=FALSE is included.

attr(df, "info")
#>       id realtime_start realtime_end                       title
#> 1  GDPC1     2021-01-12   2021-01-12 Real Gross Domestic Product
#> 2 UNRATE     2021-01-12   2021-01-12           Unemployment Rate
#>   observation_start observation_end frequency frequency_short
#> 1        1947-01-01      2020-07-01 Quarterly               Q
#> 2        1948-01-01      2020-12-01   Monthly               M
#>                              units         units_short
#> 1 Billions of Chained 2012 Dollars Bil. of Chn. 2012 $
#> 2                          Percent                   %
#>               seasonal_adjustment seasonal_adjustment_short        last_updated
#> 1 Seasonally Adjusted Annual Rate                      SAAR 2020-12-22 07:59:38
#> 2             Seasonally Adjusted                        SA 2021-01-08 07:43:02
#>   popularity
#> 1         95
#> 2         99
#>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             notes
#> 1                                                                                                                                                                                    BEA Account Code: A191RX\n\nReal gross domestic product is the inflation adjusted value of the goods and services produced by labor and property located in the United States.For more information see the Guide to the National Income and Product Accounts of the United States (NIPA). For more information, please visit the Bureau of Economic Analysis (http://www.bea.gov/national/pdf/nipaguid.pdf).
#> 2 The unemployment rate represents the number of unemployed as a percentage of the labor force. Labor force data are restricted to people 16 years of age and older, who currently reside in 1 of the 50 states or the District of Columbia, who do not reside in institutions (e.g., penal and mental facilities, homes for the aged), and who are not on active duty in the Armed Forces.\r\n\r\nThis rate is also defined as the U-3 measure of labor underutilization.\r\n\r\nThe series comes from the 'Current Population Survey (Household Survey)'\r\n\r\nThe source code is: LNS14000000
#>    group
#> 1      y
#> 2 UNRATE

The eFRED package contains a variety of other functions to interact with the FRED API. For example, the fred_search function can be used to search for various series. The example below searches for series based on the query "unemployment". The args parameter is a list containing other search parameters. In this case, search is limited to only the top three results.

search_results <- fred_search("unemployment", args = list(limit = 3))
search_results
#>            id realtime_start realtime_end
#> 1      UNRATE     2021-01-12   2021-01-12
#> 2   UNRATENSA     2021-01-12   2021-01-12
#> 3 LNS14000031     2021-01-12   2021-01-12
#>                                                               title
#> 1                                                 Unemployment Rate
#> 2                                                 Unemployment Rate
#> 3 Unemployment Rate - 20 Yrs. & Over, Black or African American Men
#>   observation_start observation_end frequency frequency_short   units
#> 1        1948-01-01      2020-12-01   Monthly               M Percent
#> 2        1948-01-01      2020-12-01   Monthly               M Percent
#> 3        1972-01-01      2020-12-01   Monthly               M Percent
#>   units_short     seasonal_adjustment seasonal_adjustment_short
#> 1           %     Seasonally Adjusted                        SA
#> 2           % Not Seasonally Adjusted                       NSA
#> 3           %     Seasonally Adjusted                        SA
#>             last_updated popularity group_popularity
#> 1 2021-01-08 07:43:02-06         99               99
#> 2 2021-01-08 07:44:49-06         60               99
#> 3 2021-01-08 07:44:06-06         82               82
#>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             notes
#> 1 The unemployment rate represents the number of unemployed as a percentage of the labor force. Labor force data are restricted to people 16 years of age and older, who currently reside in 1 of the 50 states or the District of Columbia, who do not reside in institutions (e.g., penal and mental facilities, homes for the aged), and who are not on active duty in the Armed Forces.\r\n\r\nThis rate is also defined as the U-3 measure of labor underutilization.\r\n\r\nThe series comes from the 'Current Population Survey (Household Survey)'\r\n\r\nThe source code is: LNS14000000
#> 2             The unemployment rate represents the number of unemployed as a percentage of the labor force. Labor force data are restricted to people 16 years of age and older, who currently reside in 1 of the 50 states or the District of Columbia, who do not reside in institutions (e.g., penal and mental facilities, homes for the aged), and who are not on active duty in the Armed Forces.\n\nThis rate is also defined as the U-3 measure of labor underutilization.\n\nThe series comes from the 'Current Population Survey (Household Survey)'\n\nThe source code is: LNU04000000
#> 3                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     The series comes from the 'Current Population Survey (Household Survey)'\n\nThe source code is: LNS14000031

To grab each of these series, we can use the command fred(search_results$id, info=FALSE). The information about each is not needed since we have it from the search results.

The eFRED package also contains functions to search across tags, categories, releases, and much more.