Introduction

This vignette is intended to introduce the user to fredr functions for the Releases endpoint of the FRED API.

FRED series are added to the FRED database over time in releases. Each FRED release is assigned an integer identifier. The following examples illustrate usage of the Releases endpoint functions in fredr.

Get all releases of economic data

The function fredr_releases() returns a set of all FRED releases matching the request. The data returned is a tibble in which each row represents a FRED release. The default call returns all FRED releases:

fredr_releases()
#> # A tibble: 306 × 7
#>       id realtime_start realtime_end name       press_release link     notes    
#>    <int> <chr>          <chr>        <chr>      <lgl>         <chr>    <chr>    
#>  1     9 2021-10-10     2021-10-10   Advance M… TRUE          http://… "The U.S…
#>  2    10 2021-10-10     2021-10-10   Consumer … TRUE          http://…  <NA>    
#>  3    11 2021-10-10     2021-10-10   Employmen… TRUE          http://…  <NA>    
#>  4    13 2021-10-10     2021-10-10   G.17 Indu… TRUE          http://…  <NA>    
#>  5    14 2021-10-10     2021-10-10   G.19 Cons… TRUE          http://…  <NA>    
#>  6    15 2021-10-10     2021-10-10   G.5 Forei… TRUE          http://…  <NA>    
#>  7    17 2021-10-10     2021-10-10   H.10 Fore… TRUE          http://…  <NA>    
#>  8    18 2021-10-10     2021-10-10   H.15 Sele… TRUE          http://…  <NA>    
#>  9    19 2021-10-10     2021-10-10   H.3 Aggre… TRUE          http://… "The Boa…
#> 10    20 2021-10-10     2021-10-10   H.4.1 Fac… TRUE          http://…  <NA>    
#> # … with 296 more rows

Get release dates for all releases of economic data.

The function fredr_releases_dates() returns a set of release dates for all FRED releases. The data returned is a tibble where each row represents a release date for a release. For example, to get all release dates (up to the limit of 1000) ordered by descending release date:

fredr_releases_dates()
#> # A tibble: 1,000 × 3
#>    release_id release_name                  date      
#>         <int> <chr>                         <chr>     
#>  1        101 FOMC Press Release            2021-10-11
#>  2        484 Key ECB Interest Rates        2021-10-11
#>  3        492 SONIA Interest Rate Benchmark 2021-10-11
#>  4        441 Coinbase Cryptocurrencies     2021-10-10
#>  5        101 FOMC Press Release            2021-10-10
#>  6        441 Coinbase Cryptocurrencies     2021-10-09
#>  7        101 FOMC Press Release            2021-10-09
#>  8        441 Coinbase Cryptocurrencies     2021-10-08
#>  9         86 Commercial Paper              2021-10-08
#> 10        402 Corporate Bond Yield Curve    2021-10-08
#> # … with 990 more rows

To instead order the results by ascending release ID:

fredr_releases_dates(
  sort_order = "asc",
  order_by = "release_id"
)
#> # A tibble: 1,000 × 3
#>    release_id release_name                                       date      
#>         <int> <chr>                                              <chr>     
#>  1          9 Advance Monthly Sales for Retail and Food Services 2021-01-15
#>  2          9 Advance Monthly Sales for Retail and Food Services 2021-02-17
#>  3          9 Advance Monthly Sales for Retail and Food Services 2021-03-16
#>  4          9 Advance Monthly Sales for Retail and Food Services 2021-04-15
#>  5          9 Advance Monthly Sales for Retail and Food Services 2021-04-26
#>  6          9 Advance Monthly Sales for Retail and Food Services 2021-05-14
#>  7          9 Advance Monthly Sales for Retail and Food Services 2021-06-15
#>  8          9 Advance Monthly Sales for Retail and Food Services 2021-07-16
#>  9          9 Advance Monthly Sales for Retail and Food Services 2021-08-17
#> 10          9 Advance Monthly Sales for Retail and Food Services 2021-09-16
#> # … with 990 more rows

Get a release of economic data

The function fredr_release() returns data for a single FRED release specified by release_id. The data returned is a tibble where each row represents the specified release. For example, to get release data for the Employment Cost Index release:

fredr_release(release_id = 11L)
#> # A tibble: 1 × 6
#>      id realtime_start realtime_end name                  press_release link    
#>   <int> <chr>          <chr>        <chr>                 <lgl>         <chr>   
#> 1    11 2021-10-11     2021-10-11   Employment Cost Index TRUE          http://…

Get release dates for a single release of economic data

The function fredr_release_dates() returns a set of release dates for a single FRED release specified by release_id. The data returned is a tibble where each row represents a release date for the release specified. For example, to get release dates for the Employment Cost Index release:

fredr_release_dates(release_id = 11L)
#> # A tibble: 111 × 2
#>    release_id date      
#>         <int> <chr>     
#>  1         11 1996-10-29
#>  2         11 1997-01-28
#>  3         11 1997-04-29
#>  4         11 1997-07-29
#>  5         11 1997-10-28
#>  6         11 1998-01-27
#>  7         11 1998-04-30
#>  8         11 1998-07-30
#>  9         11 1998-10-29
#> 10         11 1999-01-28
#> # … with 101 more rows

Get the series in a release of economic data

The function fredr_release_series() returns a set of series belonging to the FRED release specified by release_id. The data returned is a tibble where each row represents a series in the release specified. For example, to get series in the Employment Cost Index release:

fredr_release_series(release_id = 10L)
#> # A tibble: 1,000 × 16
#>    id       realtime_start realtime_end title   observation_sta… observation_end
#>    <chr>    <chr>          <chr>        <chr>   <chr>            <chr>          
#>  1 CPIAPPNS 2021-10-11     2021-10-11   Consum… 1914-12-01       2021-08-01     
#>  2 CPIAPPSL 2021-10-11     2021-10-11   Consum… 1947-01-01       2021-08-01     
#>  3 CPIAUCNS 2021-10-11     2021-10-11   Consum… 1913-01-01       2021-08-01     
#>  4 CPIAUCSL 2021-10-11     2021-10-11   Consum… 1947-01-01       2021-08-01     
#>  5 CPIEDUNS 2021-10-11     2021-10-11   Consum… 1993-01-01       2021-08-01     
#>  6 CPIEDUSL 2021-10-11     2021-10-11   Consum… 1993-01-01       2021-08-01     
#>  7 CPIENGNS 2021-10-11     2021-10-11   Consum… 1957-01-01       2021-08-01     
#>  8 CPIENGSL 2021-10-11     2021-10-11   Consum… 1957-01-01       2021-08-01     
#>  9 CPIFABNS 2021-10-11     2021-10-11   Consum… 1967-01-01       2021-08-01     
#> 10 CPIFABSL 2021-10-11     2021-10-11   Consum… 1967-01-01       2021-08-01     
#> # … with 990 more rows, and 10 more variables: frequency <chr>,
#> #   frequency_short <chr>, units <chr>, units_short <chr>,
#> #   seasonal_adjustment <chr>, seasonal_adjustment_short <chr>,
#> #   last_updated <chr>, popularity <int>, group_popularity <int>, notes <chr>

Note the parameters available to filter series belonging to a release:

fredr_release_series(
  release_id = 10L,
  filter_variable = "frequency",
  filter_value = "Monthly",
  order_by = "popularity",
  sort_order = "desc",
  limit = 10L
)
#> # A tibble: 10 × 16
#>    id             realtime_start realtime_end title observation_sta… observation_end
#>    <chr>          <chr>          <chr>        <chr> <chr>            <chr>          
#>  1 CPIAUCSL       2021-10-11     2021-10-11   Cons… 1947-01-01       2021-08-01     
#>  2 CPILFESL       2021-10-11     2021-10-11   Cons… 1957-01-01       2021-08-01     
#>  3 CPIAUCNS       2021-10-11     2021-10-11   Cons… 1913-01-01       2021-08-01     
#>  4 CUSR0000SETA02 2021-10-11     2021-10-11   Cons… 1953-01-01       2021-08-01     
#>  5 CUUR0000SA0R   2021-10-11     2021-10-11   Cons… 1913-01-01       2021-08-01     
#>  6 CUUR0000SEHA   2021-10-11     2021-10-11   Cons… 1914-12-01       2021-08-01     
#>  7 CPIMEDSL       2021-10-11     2021-10-11   Cons… 1947-01-01       2021-08-01     
#>  8 CPIFABSL       2021-10-11     2021-10-11   Cons… 1967-01-01       2021-08-01     
#>  9 CUUR0000SETA01 2021-10-11     2021-10-11   Cons… 1947-03-01       2021-08-01     
#> 10 CPIAPPSL       2021-10-11     2021-10-11   Cons… 1947-01-01       2021-08-01     
#> # … with 10 more variables: frequency <chr>, frequency_short <chr>,
#> #   units <chr>, units_short <chr>, seasonal_adjustment <chr>,
#> #   seasonal_adjustment_short <chr>, last_updated <chr>, popularity <int>,
#> #   group_popularity <int>, notes <chr>

Get the FRED tags for a release

The function fredr_release_tags() returns a set of tags assigned to series belonging to the FRED release specified by release_id. The data returned is a tibble where each row represents a tag. For example, to get the geographic tags assigned to series in the Consumer Price Index release:

fredr_release_tags(
  release_id = 10L,
  tag_group_id = "geo",
  order_by = "popularity",
  sort_order = "desc"
)
#> # A tibble: 66 × 6
#>    name  group_id notes                    created       popularity series_count
#>    <chr> <chr>    <chr>                    <chr>              <int>        <int>
#>  1 usa   geo      United States of America 2012-02-27 1…        100         4614
#>  2 ca    geo      California               2012-02-27 1…         61          242
#>  3 tx    geo      Texas                    2012-02-27 1…         58          222
#>  4 fl    geo      Florida                  2012-02-27 1…         55          164
#>  5 pa    geo      Pennsylvania             2012-02-27 1…         55          268
#>  6 ny    geo      New York                 2012-02-27 1…         55          104
#>  7 wi    geo      Wisconsin                2012-02-27 1…         54          206
#>  8 mi    geo      Michigan                 2012-02-27 1…         52          100
#>  9 oh    geo      Ohio                     2012-02-27 1…         50          148
#> 10 il    geo      Illinois                 2012-02-27 1…         49          146
#> # … with 56 more rows

Get the sources for a release of economic data

The function fredr_release_sources() returns a set of FRED sources for the FRED release specified by release_id. The data returned is a tibble where each row represents a source. For example, to get the sources for the Consumer Price Index release:

fredr_release_sources(release_id = 10L)
#> # A tibble: 1 × 5
#>      id realtime_start realtime_end name                            link        
#>   <int> <chr>          <chr>        <chr>                           <chr>       
#> 1    22 2021-10-11     2021-10-11   U.S. Bureau of Labor Statistics https://www…

Get release table trees for a given release

The function fredr_release_tables() returns a set of FRED release table trees for the FRED release specified by release_id. The data returned is a tibble where each row represents an element of the table tree’s children: the column name gives the element ID and the column value stores data nodes for the element (e.g. element ID, release ID, parent ID, element type, element name, children, etc.). For example, to get the table tree for the Consumer Price Index release:

cpi_tbl <- fredr_release_tables(release_id = 10L)
cpi_tbl
#> # A tibble: 2 × 2
#>   name  value           
#>   <chr> <list>          
#> 1 34481 <named list [9]>
#> 2 36712 <named list [9]>

The above table has two elements: 34481 and 36712. Inspect an element (a list) by selecting its row and unnesting the row element value using tibble::deframe():

library(dplyr)
#> 
#> Attaching package: 'dplyr'
#> The following objects are masked from 'package:stats':
#> 
#>     filter, lag
#> The following objects are masked from 'package:base':
#> 
#>     intersect, setdiff, setequal, union
library(tibble)

cpi_tbl %>%
  slice(2) %>%
  deframe()
#> $`36712`
#> $`36712`$element_id
#> [1] 36712
#> 
#> $`36712`$release_id
#> [1] 10
#> 
#> $`36712`$series_id
#> NULL
#> 
#> $`36712`$parent_id
#> NULL
#> 
#> $`36712`$line
#> NULL
#> 
#> $`36712`$type
#> [1] "section"
#> 
#> $`36712`$name
#> [1] "Consumer Price Index Special Aggregate Indices"
#> 
#> $`36712`$level
#> [1] "0"
#> 
#> $`36712`$children
#> list()

You can extract the tree hierarchy of a deeper element in the table by specifying an element_id. From the previous example, if you wanted to get the subtree for child element 36712 of the Consumer Price Index table:

fredr_release_tables(
  release_id = 10L,
  element_id = 36712L
)
#> # A tibble: 4 × 2
#>   name  value           
#>   <chr> <list>          
#> 1 36713 <named list [9]>
#> 2 36801 <named list [9]>
#> 3 37003 <named list [9]>
#> 4 37691 <named list [9]>