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 × 6
#>    name                              group_id notes created popularity series_count
#>    <chr>                             <chr>    <chr> <chr>        <int>        <int>
#>  1 nsa                               seas     "Not… 2012-0…        100       735030
#>  2 usa                               geo      "Uni… 2012-0…        100       654342
#>  3 public domain: citation requested cc        <NA> 2018-1…        100       606112
#>  4 annual                            freq     ""    2012-0…         90       489702
#>  5 county                            geot     "Cou… 2012-0…         80       330616
#>  6 nation                            geot     ""    2012-0…         99       261462
#>  7 census                            src      "Cen… 2012-0…         80       237162
#>  8 monthly                           freq     ""    2012-0…         93       214046
#>  9 copyrighted: citation required    cc        <NA> 2018-1…         88       207112
#> 10 bls                               src      "Bur… 2012-0…         87       175954

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

Return tags for a given group ID:

fredr_tags(
  tag_group_id = "geo",
  limit = 50L
)
#> # A tibble: 50 × 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       654692
#>  2 tx    geo      Texas                    2012-02-27 1…         58        35398
#>  3 ga    geo      Georgia (U.S. state)     2012-02-27 1…         49        20632
#>  4 ca    geo      California               2012-02-27 1…         61        17990
#>  5 va    geo      Virginia                 2012-02-27 1…         49        17522
#>  6 nc    geo      North Carolina           2012-02-27 1…         50        17274
#>  7 il    geo      Illinois                 2012-02-27 1…         49        16398
#>  8 oh    geo      Ohio                     2012-02-27 1…         50        16284
#>  9 ky    geo      Kentucky                 2012-02-27 1…         45        15630
#> 10 in    geo      Indiana                  2012-02-27 1…         48        15430
#> # … with 40 more rows

Search for tags by text:

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

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 × 6
#>    name                              group_id notes created popularity series_count
#>    <chr>                             <chr>    <chr> <chr>        <int>        <int>
#>  1 nsa                               seas     "Not… 2012-0…        100        47110
#>  2 usa                               geo      "Uni… 2012-0…        100        42602
#>  3 public domain: citation requested cc        <NA> 2018-1…        100        42314
#>  4 bls                               src      "Bur… 2012-0…         87        38424
#>  5 unemployment                      gen      ""    2012-0…         78        32754
#>  6 county                            geot     "Cou… 2012-0…         80        28414
#>  7 annual                            freq     ""    2012-0…         90        24218
#>  8 household survey                  gen      "Cur… 2012-0…         65        20080
#>  9 monthly                           freq     ""    2012-0…         93        19012
#> 10 rate                              gen      ""    2012-0…         87        15058
#> # … 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 × 16
#>    id              realtime_start realtime_end title observation_sta… observation_end
#>    <chr>           <chr>          <chr>        <chr> <chr>            <chr>          
#>  1 A001RD3A086NBEA 2021-10-11     2021-10-11   Gros… 1929-01-01       2020-01-01     
#>  2 A001RG3A086NBEA 2021-10-11     2021-10-11   Gros… 1929-01-01       2020-01-01     
#>  3 A001RI1A225NBEA 2021-10-11     2021-10-11   Gros… 1930-01-01       2020-01-01     
#>  4 A001RI1Q225SBEA 2021-10-11     2021-10-11   Gros… 1947-04-01       2021-04-01     
#>  5 A001RL1A225NBEA 2021-10-11     2021-10-11   Real… 1930-01-01       2020-01-01     
#>  6 A001RL1Q225SBEA 2021-10-11     2021-10-11   Real… 1947-04-01       2021-04-01     
#>  7 A001RO1Q156NBEA 2021-10-11     2021-10-11   Real… 1948-01-01       2021-04-01     
#>  8 A001RP1A027NBEA 2021-10-11     2021-10-11   Gros… 1930-01-01       2020-01-01     
#>  9 A001RP1Q027SBEA 2021-10-11     2021-10-11   Gros… 1947-04-01       2021-04-01     
#> 10 A001RV1A225NBEA 2021-10-11     2021-10-11   Gros… 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 × 16
#>    id                  realtime_start realtime_end title observation_sta… observation_end
#>    <chr>               <chr>          <chr>        <chr> <chr>            <chr>          
#>  1 ILACCFDQGSP         2021-10-11     2021-10-11   Chai… 1997-01-01       2020-01-01     
#>  2 ILACCOMDQGSP        2021-10-11     2021-10-11   Chai… 1997-01-01       2020-01-01     
#>  3 IDBRDTELEQGSP       2021-10-11     2021-10-11   Chai… 1997-01-01       2020-01-01     
#>  4 AKEDHLTHSOCASSQGSP  2021-10-11     2021-10-11   Chai… 1997-01-01       2020-01-01     
#>  5 OREDHLTHSOCASSQGSP  2021-10-11     2021-10-11   Chai… 1997-01-01       2020-01-01     
#>  6 ORFABRMETQGSP       2021-10-11     2021-10-11   Chai… 1997-01-01       2020-01-01     
#>  7 OKGOVFEDCIVQGSP     2021-10-11     2021-10-11   Chai… 1997-01-01       2020-01-01     
#>  8 SCFOODBEVTOBMANQGSP 2021-10-11     2021-10-11   Chai… 1997-01-01       2020-01-01     
#>  9 WAINFOQGSP          2021-10-11     2021-10-11   Chai… 1997-01-01       2020-01-01     
#> 10 RKMTMACHMANQGSP     2021-10-11     2021-10-11   Chai… 1997-01-01       2020-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>