Author: Sam Boysel
Date: 2021-01-29

# FRED Releases

#### Sam Boysel

#### 2021-01-29

# Introduction

    library(fredr)

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: 293 x 7
    #>       id realtime_start realtime_end name       press_release link     notes
    #>    <int> <chr>          <chr>        <chr>      <lgl>         <chr>    <chr>
    #>  1     9 2021-01-28     2021-01-28   Advance M… TRUE          http://… "The U.S…
    #>  2    10 2021-01-28     2021-01-28   Consumer … TRUE          http://…  <NA>
    #>  3    11 2021-01-28     2021-01-28   Employmen… TRUE          http://…  <NA>
    #>  4    13 2021-01-28     2021-01-28   G.17 Indu… TRUE          http://…  <NA>
    #>  5    14 2021-01-28     2021-01-28   G.19 Cons… TRUE          http://…  <NA>
    #>  6    15 2021-01-28     2021-01-28   G.5 Forei… TRUE          http://…  <NA>
    #>  7    17 2021-01-28     2021-01-28   H.10 Fore… TRUE          http://…  <NA>
    #>  8    18 2021-01-28     2021-01-28   H.15 Sele… TRUE          http://…  <NA>
    #>  9    19 2021-01-28     2021-01-28   H.3 Aggre… TRUE          http://… "The Boa…
    #> 10    20 2021-01-28     2021-01-28   H.4.1 Fac… TRUE          http://…  <NA>
    #> # … with 283 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: 643 x 3
    #>    release_id release_name                                date
    #>         <int> <chr>                                       <chr>
    #>  1        333 Chicago Fed Midwest Economy Index           2021-01-29
    #>  2         72 Daily Treasury Inflation-Indexed Securities 2021-01-29
    #>  3        279 Economic Policy Uncertainty                 2021-01-29
    #>  4         11 Employment Cost Index                       2021-01-29
    #>  5        378 Federal Funds Data                          2021-01-29
    #>  6        101 FOMC Press Release                          2021-01-29
    #>  7        287 Nikkei Indexes                              2021-01-29
    #>  8        375 Overnight Bank Funding Rate Data            2021-01-29
    #>  9         54 Personal Income and Outlays                 2021-01-29
    #> 10        445 Secured Overnight Financing Rate Data       2021-01-29
    #> # … with 633 more rows

To instead order the results by ascending release ID:

    fredr_releases_dates(
      sort_order = "asc",
      order_by = "release_id"
    )
    #> # A tibble: 643 x 3
    #>    release_id release_name                                        date
    #>         <int> <chr>                                               <chr>
    #>  1          9 Advance Monthly Sales for Retail and Food Services  2021-01-15
    #>  2         10 Consumer Price Index                                2021-01-13
    #>  3         11 Employment Cost Index                               2021-01-29
    #>  4         13 G.17 Industrial Production and Capacity Utilization 2021-01-15
    #>  5         14 G.19 Consumer Credit                                2021-01-08
    #>  6         15 G.5 Foreign Exchange Rates                          2021-01-04
    #>  7         17 H.10 Foreign Exchange Rates                         2021-01-04
    #>  8         17 H.10 Foreign Exchange Rates                         2021-01-11
    #>  9         17 H.10 Foreign Exchange Rates                         2021-01-19
    #> 10         17 H.10 Foreign Exchange Rates                         2021-01-25
    #> # … with 633 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 x 6
    #>      id realtime_start realtime_end name          press_release link
    #>   <int> <chr>          <chr>        <chr>         <lgl>         <chr>
    #> 1    11 2021-01-29     2021-01-29   Employment C… TRUE          http://www.bls.…

## 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: 109 x 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 99 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 x 16
    #>    id    realtime_start realtime_end title observation_sta… observation_end
    #>    <chr> <chr>          <chr>        <chr> <chr>            <chr>
    #>  1 CPIA… 2021-01-29     2021-01-29   Cons… 1914-12-01       2020-12-01
    #>  2 CPIA… 2021-01-29     2021-01-29   Cons… 1947-01-01       2020-12-01
    #>  3 CPIA… 2021-01-29     2021-01-29   Cons… 1913-01-01       2020-12-01
    #>  4 CPIA… 2021-01-29     2021-01-29   Cons… 1947-01-01       2020-12-01
    #>  5 CPIE… 2021-01-29     2021-01-29   Cons… 1993-01-01       2020-12-01
    #>  6 CPIE… 2021-01-29     2021-01-29   Cons… 1993-01-01       2020-12-01
    #>  7 CPIE… 2021-01-29     2021-01-29   Cons… 1957-01-01       2020-12-01
    #>  8 CPIE… 2021-01-29     2021-01-29   Cons… 1957-01-01       2020-12-01
    #>  9 CPIF… 2021-01-29     2021-01-29   Cons… 1967-01-01       2020-12-01
    #> 10 CPIF… 2021-01-29     2021-01-29   Cons… 1967-01-01       2020-12-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 x 16
    #>    id    realtime_start realtime_end title observation_sta… observation_end
    #>    <chr> <chr>          <chr>        <chr> <chr>            <chr>
    #>  1 CPIA… 2021-01-29     2021-01-29   Cons… 1947-01-01       2020-12-01
    #>  2 CPIL… 2021-01-29     2021-01-29   Cons… 1957-01-01       2020-12-01
    #>  3 CPIA… 2021-01-29     2021-01-29   Cons… 1913-01-01       2020-12-01
    #>  4 CUUR… 2021-01-29     2021-01-29   Cons… 1913-01-01       2020-12-01
    #>  5 CPIM… 2021-01-29     2021-01-29   Cons… 1947-01-01       2020-12-01
    #>  6 CUUR… 2021-01-29     2021-01-29   Cons… 1914-12-01       2020-12-01
    #>  7 CPIF… 2021-01-29     2021-01-29   Cons… 1967-01-01       2020-12-01
    #>  8 CWUR… 2021-01-29     2021-01-29   Cons… 1913-01-01       2020-12-01
    #>  9 CUSR… 2021-01-29     2021-01-29   Cons… 1953-01-01       2020-12-01
    #> 10 CUUR… 2021-01-29     2021-01-29   Cons… 1947-03-01       2020-12-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: 65 x 6
    #>    name  group_id notes               created            popularity series_count
    #>    <chr> <chr>    <chr>               <chr>                   <int>        <int>
    #>  1 usa   geo      United States of A… 2012-02-27 10:18:…        100         4464
    #>  2 ca    geo      California          2012-02-27 10:18:…         61          246
    #>  3 tx    geo      Texas               2012-02-27 10:18:…         58          206
    #>  4 fl    geo      Florida             2012-02-27 10:18:…         55          142
    #>  5 pa    geo      Pennsylvania        2012-02-27 10:18:…         55          254
    #>  6 ny    geo      New York            2012-02-27 10:18:…         55          114
    #>  7 wi    geo      Wisconsin           2012-02-27 10:18:…         54          208
    #>  8 mi    geo      Michigan            2012-02-27 10:18:…         52           98
    #>  9 oh    geo      Ohio                2012-02-27 10:18:…         50          162
    #> 10 il    geo      Illinois            2012-02-27 10:18:…         49          156
    #> # … with 55 more rows

## Get the related FRED tags for one or more FRED tags within a release

The function `fredr_release_related_tags()` returns a set of tags assigned to series belonging to the FRED release specified by `release_id` that are related to tags specified in `tag_names`. The data returned is a tibble where each row represents a related tag. For example, to get frequency tags assigned to series in the Consumer Price Index release that are also related to the tag `bls` and not the `annual` tag:

    fredr_release_related_tags(
      release_id = 10L,
      tag_names = "bls",
      tag_group_id = "freq",
      exclude_tag_names = "annual",
      order_by = "popularity",
      sort_order = "desc"
    )
    #> # A tibble: 2 x 6
    #>   name       group_id notes created                popularity series_count
    #>   <chr>      <chr>    <chr> <chr>                       <int>        <int>
    #> 1 monthly    freq     ""    2012-02-27 10:18:19-06         93         2158
    #> 2 semiannual freq     ""    2012-02-27 10:18:19-06         32         1874

## 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 x 5
    #>      id realtime_start realtime_end name                       link
    #>   <int> <chr>          <chr>        <chr>                      <chr>
    #> 1    22 2021-01-29     2021-01-29   U.S. Bureau of Labor Stat… https://www.bls.…

## 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 x 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)
    #> Warning: package 'tibble' was built under R version 4.0.2

    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 x 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]>