Introduction

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

FRED series are assigned tags as an attribute for classification. Each FRED tag is identified by a string ID. For example:

  • “annual”, “monthly”
  • “census”, “bls”
  • “usa”, “county”
  • “manufacturing”, “exports”, “households”
  • “sa” (i.e. “seasonally adjusted”)

The following examples illustrate usage of the Tags endpoint functions in fredr.

Get series tags

The function fredr_tags() returns a list of tags matching the request. The data returned is a tibble in which each row represents a FRED tag. For example, running fredr_tags() without any parameters returns the top 1000 FRED tags ordered by number of series who are assigned the tag (but here we limit to just 10):

fredr_tags(limit = 10)
#> # A tibble: 10 x 6
#>    name             group_id notes          created      popularity series_count
#>    <chr>            <chr>    <chr>          <chr>             <int>        <int>
#>  1 nsa              seas     "Not Seasonal… 2012-02-27 …        100       709208
#>  2 usa              geo      "United State… 2012-02-27 …        100       629224
#>  3 public domain: … cc        <NA>          2018-12-17 …        100       580070
#>  4 annual           freq     ""             2012-02-27 …         90       464814
#>  5 county           geot     "County or Co… 2012-02-27 …         80       328066
#>  6 nation           geot     ""             2012-02-27 …         99       239864
#>  7 census           src      "Census"       2012-02-27 …         80       237874
#>  8 monthly          freq     ""             2012-02-27 …         93       214086
#>  9 copyrighted: ci… cc        <NA>          2018-12-17 …         88       207230
#> 10 bls              src      "Bureau of La… 2012-02-27 …         87       156090

To return specific tags by tag name, specify multiple tags in a single string by delimiting with a semicolon:

fredr_tags(tag_names = "gdp;oecd", limit = 10)
#> # A tibble: 2 x 6
#>   name  group_id notes                     created       popularity series_count
#>   <chr> <chr>    <chr>                     <chr>              <int>        <int>
#> 1 gdp   gen      Gross Domestic Product    2012-02-27 1…         82        74324
#> 2 oecd  src      Org. for Economic Co-ope… 2012-02-27 1…         77        63882

Return tags for a given group ID:

fredr_tags(
  tag_group_id = "geo",
  limit = 50L
)
#> # A tibble: 50 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       628558
#>  2 tx    geo      Texas               2012-02-27 10:18:…         58        35500
#>  3 ga    geo      Georgia (U.S. stat… 2012-02-27 10:18:…         49        20684
#>  4 ca    geo      California          2012-02-27 10:18:…         61        18022
#>  5 nc    geo      North Carolina      2012-02-27 10:18:…         50        17220
#>  6 va    geo      Virginia            2012-02-27 10:18:…         49        17162
#>  7 oh    geo      Ohio                2012-02-27 10:18:…         50        16540
#>  8 il    geo      Illinois            2012-02-27 10:18:…         49        16310
#>  9 ky    geo      Kentucky            2012-02-27 10:18:…         45        15352
#> 10 mo    geo      Missouri            2012-02-27 10:18:…         47        15214
#> # … with 40 more rows

Search for tags by text:

fredr_tags(search_text = "unemployment")
#> # A tibble: 2 x 6
#>   name     group_id notes                   created      popularity series_count
#>   <chr>    <chr>    <chr>                   <chr>             <int>        <int>
#> 1 unemplo… gen      ""                      2012-02-27 …         78        32672
#> 2 nairu    gen      "Non-Accelerating Infl… 2012-08-10 …         19            2

Note that the example above searches for tags matching "unemployment". To search for the set of series with tags matching "unemployment", use fredr_series_search_tags():

fredr_series_search_tags(
  series_search_text = "unemployment",
  limit = 100L
)
#> # A tibble: 100 x 6
#>    name           group_id notes             created     popularity series_count
#>    <chr>          <chr>    <chr>             <chr>            <int>        <int>
#>  1 nsa            seas     "Not Seasonally … 2012-02-27…        100        44598
#>  2 usa            geo      "United States o… 2012-02-27…        100        40164
#>  3 public domain… cc        <NA>             2018-12-17…        100        39872
#>  4 bls            src      "Bureau of Labor… 2012-02-27…         87        35950
#>  5 unemployment   gen      ""                2012-02-27…         78        32434
#>  6 county         geot     "County or Count… 2012-02-27…         80        28244
#>  7 annual         freq     ""                2012-02-27…         90        22144
#>  8 household sur… gen      "Current Populat… 2012-06-18…         65        19936
#>  9 monthly        freq     ""                2012-02-27…         93        18890
#> 10 rate           gen      ""                2012-02-27…         87        14648
#> # … with 90 more rows

Get series by tag names

The function fredr_tags_series() returns a list of series assigned tags matching the request. As with the functions for the Series endpoint, the data returned is a tibble in which each row represents a series. For example, to get all series tagged with "gdp":

fredr_tags_series(tag_names = "gdp")
#> # A tibble: 1,000 x 16
#>    id     realtime_start realtime_end title     observation_sta… observation_end
#>    <chr>  <chr>          <chr>        <chr>     <chr>            <chr>          
#>  1 A001R… 2021-04-05     2021-04-05   Gross na… 1929-01-01       2020-01-01     
#>  2 A001R… 2021-04-05     2021-04-05   Gross na… 1929-01-01       2020-01-01     
#>  3 A001R… 2021-04-05     2021-04-05   Gross Na… 1930-01-01       2020-01-01     
#>  4 A001R… 2021-04-05     2021-04-05   Gross Na… 1947-04-01       2020-10-01     
#>  5 A001R… 2021-04-05     2021-04-05   Real Gro… 1930-01-01       2020-01-01     
#>  6 A001R… 2021-04-05     2021-04-05   Real Gro… 1947-04-01       2020-10-01     
#>  7 A001R… 2021-04-05     2021-04-05   Real Gro… 1948-01-01       2020-10-01     
#>  8 A001R… 2021-04-05     2021-04-05   Gross Na… 1930-01-01       2020-01-01     
#>  9 A001R… 2021-04-05     2021-04-05   Gross Na… 1947-04-01       2020-10-01     
#> 10 A001R… 2021-04-05     2021-04-05   Gross Na… 1930-01-01       2020-01-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>

To get the top 100 most popular non-quarterly series tagged with "gdp":

fredr_tags_series(
  tag_names = "gdp",
  exclude_tag_names = "quarterly",
  order_by = "popularity",
  limit = 100L
)
#> # A tibble: 100 x 16
#>    id     realtime_start realtime_end title     observation_sta… observation_end
#>    <chr>  <chr>          <chr>        <chr>     <chr>            <chr>          
#>  1 B4067… 2021-04-05     2021-04-05   Compensa… 1929-01-01       1948-01-01     
#>  2 B4023… 2021-04-05     2021-04-05   Compensa… 1987-01-01       2000-01-01     
#>  3 H4023… 2021-04-05     2021-04-05   Compensa… 1929-01-01       1947-01-01     
#>  4 B4018… 2021-04-05     2021-04-05   Compensa… 1987-01-01       2000-01-01     
#>  5 H4030… 2021-04-05     2021-04-05   Compensa… 1929-01-01       1948-01-01     
#>  6 J4074… 2021-04-05     2021-04-05   Compensa… 1948-01-01       1987-01-01     
#>  7 H4071… 2021-04-05     2021-04-05   Compensa… 1929-01-01       1948-01-01     
#>  8 B4072… 2021-04-05     2021-04-05   Compensa… 1987-01-01       2000-01-01     
#>  9 N4048… 2021-04-05     2021-04-05   Compensa… 1998-01-01       2019-01-01     
#> 10 B4050… 2021-04-05     2021-04-05   Compensa… 1987-01-01       2000-01-01     
#> # … with 90 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>