Introduction

library(fredr)

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       706360
#>  2 usa              geo      "United State… 2012-02-27 …        100       625980
#>  3 public domain: … cc        <NA>          2018-12-17 …        100       573978
#>  4 annual           freq     ""             2012-02-27 …         90       463698
#>  5 county           geot     "County or Co… 2012-02-27 …         80       327846
#>  6 nation           geot     ""             2012-02-27 …         99       238618
#>  7 census           src      "Census"       2012-02-27 …         80       236146
#>  8 monthly          freq     ""             2012-02-27 …         93       212218
#>  9 copyrighted: ci… cc        <NA>          2018-12-17 …         88       206560
#> 10 bls              src      "Bureau of La… 2012-02-27 …         87       155344

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        74226
#> 2 oecd  src      Org. for Economic Co-ope… 2012-02-27 1…         77        63972

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       625788
#>  2 tx    geo      Texas               2012-02-27 10:18:…         58        35852
#>  3 ga    geo      Georgia (U.S. stat… 2012-02-27 10:18:…         49        21024
#>  4 ca    geo      California          2012-02-27 10:18:…         61        17946
#>  5 va    geo      Virginia            2012-02-27 10:18:…         49        17108
#>  6 nc    geo      North Carolina      2012-02-27 10:18:…         50        16690
#>  7 oh    geo      Ohio                2012-02-27 10:18:…         50        16212
#>  8 il    geo      Illinois            2012-02-27 10:18:…         49        16024
#>  9 ky    geo      Kentucky            2012-02-27 10:18:…         45        15376
#> 10 mo    geo      Missouri            2012-02-27 10:18:…         47        15282
#> # … 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        32614
#> 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        44884
#>  2 usa            geo      "United States o… 2012-02-27…        100        40460
#>  3 public domain… cc        <NA>             2018-12-17…        100        40004
#>  4 bls            src      "Bureau of Labor… 2012-02-27…         87        36196
#>  5 unemployment   gen      ""                2012-02-27…         78        32722
#>  6 county         geot     "County or Count… 2012-02-27…         80        28428
#>  7 annual         freq     ""                2012-02-27…         90        22168
#>  8 household sur… gen      "Current Populat… 2012-06-18…         65        19970
#>  9 monthly        freq     ""                2012-02-27…         93        19096
#> 10 rate           gen      ""                2012-02-27…         87        14902
#> # … with 90 more rows

Get related series tags

The function fredr_related_tags() returns a list of tags related to the set of tags matching the request. The data returned is a tibble in which each row represents a tag related to the tags specified in tag_names. For example, to get the set of tags related to the tags "monetary aggregates" and "weekly":

fredr_related_tags(tag_names = "monetary aggregates;weekly")
#> # A tibble: 15 x 6
#>    name             group_id notes          created      popularity series_count
#>    <chr>            <chr>    <chr>          <chr>             <int>        <int>
#>  1 nation           geot     ""             2012-02-27 …         99           14
#>  2 usa              geo      "United State… 2012-02-27 …        100           14
#>  3 frb              src      "Board of Gov… 2012-02-27 …         80           10
#>  4 h6               rls      "H.6 Money St… 2012-08-16 …         51           10
#>  5 public domain: … cc        <NA>          2018-12-17 …        100           10
#>  6 sa               seas     "Seasonally A… 2012-02-27 …         88            8
#>  7 nsa              seas     "Not Seasonal… 2012-02-27 …        100            6
#>  8 copyrighted: ci… cc        <NA>          2018-12-17 …         88            4
#>  9 frb stl          src      "St. Louis Fe… 2012-02-27 …         68            4
#> 10 m1               gen      "M1 Money Sto… 2012-02-27 …         47            4
#> 11 m2               gen      "M2 Money Sto… 2012-02-27 …         43            4
#> 12 mzm              gen      "MZM Money St… 2012-02-27 …         27            4
#> 13 currency         gen      ""             2012-02-27 …         62            2
#> 14 discontinued     gen      ""             2012-02-27 …         67            2
#> 15 m3               gen      "M3 Money Sto… 2012-02-27 …         39            2

To filter these results to tags belonging to the “General” tag group:

fredr_related_tags(
  tag_names = "monetary aggregates;weekly",
  tag_group_id = "gen"
)
#> # A tibble: 6 x 6
#>   name        group_id notes          created            popularity series_count
#>   <chr>       <chr>    <chr>          <chr>                   <int>        <int>
#> 1 m1          gen      "M1 Money Sto… 2012-02-27 10:18:…         47            4
#> 2 m2          gen      "M2 Money Sto… 2012-02-27 10:18:…         43            4
#> 3 currency    gen      ""             2012-02-27 10:18:…         62            2
#> 4 discontinu… gen      ""             2012-02-27 10:18:…         67            2
#> 5 m3          gen      "M3 Money Sto… 2012-02-27 10:18:…         39            2
#> 6 mzm         gen      "MZM Money St… 2012-02-27 10:18:…         27            2

To filter these results even further, keep only the tags matching the string "money stock":

fredr_related_tags(
  tag_names = "monetary aggregates;weekly",
  tag_group_id = "gen",
  search_text = "money stock"
)
#> # A tibble: 4 x 6
#>   name  group_id notes           created                popularity series_count
#>   <chr> <chr>    <chr>           <chr>                       <int>        <int>
#> 1 m1    gen      M1 Money Stock  2012-02-27 10:18:19-06         47            4
#> 2 m2    gen      M2 Money Stock  2012-02-27 10:18:19-06         43            4
#> 3 m3    gen      M3 Money Stock  2012-02-27 10:18:19-06         39            4
#> 4 mzm   gen      MZM Money Stock 2012-02-27 10:18:19-06         27            4

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 A001… 2021-01-29     2021-01-29   Gros… 1929-01-01       2019-01-01     
#>  2 A001… 2021-01-29     2021-01-29   Gros… 1929-01-01       2019-01-01     
#>  3 A001… 2021-01-29     2021-01-29   Gros… 1930-01-01       2019-01-01     
#>  4 A001… 2021-01-29     2021-01-29   Gros… 1947-04-01       2020-07-01     
#>  5 A001… 2021-01-29     2021-01-29   Real… 1930-01-01       2019-01-01     
#>  6 A001… 2021-01-29     2021-01-29   Real… 1947-04-01       2020-07-01     
#>  7 A001… 2021-01-29     2021-01-29   Real… 1948-01-01       2020-07-01     
#>  8 A001… 2021-01-29     2021-01-29   Gros… 1930-01-01       2019-01-01     
#>  9 A001… 2021-01-29     2021-01-29   Gros… 1947-04-01       2020-07-01     
#> 10 A001… 2021-01-29     2021-01-29   Gros… 1930-01-01       2019-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 H407… 2021-01-29     2021-01-29   Comp… 1929-01-01       1948-01-01     
#>  2 B407… 2021-01-29     2021-01-29   Comp… 1987-01-01       2000-01-01     
#>  3 N404… 2021-01-29     2021-01-29   Comp… 1998-01-01       2019-01-01     
#>  4 B405… 2021-01-29     2021-01-29   Comp… 1987-01-01       2000-01-01     
#>  5 H405… 2021-01-29     2021-01-29   Comp… 1929-01-01       1948-01-01     
#>  6 J405… 2021-01-29     2021-01-29   Comp… 1948-01-01       1969-01-01     
#>  7 B490… 2021-01-29     2021-01-29   Empl… 1987-01-01       2000-01-01     
#>  8 J491… 2021-01-29     2021-01-29   Empl… 1948-01-01       1987-01-01     
#>  9 B480… 2021-01-29     2021-01-29   Empl… 1948-01-01       1987-01-01     
#> 10 J481… 2021-01-29     2021-01-29   Empl… 1948-01-01       1987-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>

FRED Tags

Sam Boysel

2021-01-29

Introduction

Get series tags

Get series by tag names