Introduction

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

FRED series are the primary data objects in the FRED database. Each FRED series is assigned a string identifier. For example:

  • Civilian Unemployment Rate (series_id = "UNRATE")
  • Real Gross National Product (series_id = "GNPCA")
  • Effective Federal Funds Rate (series_id = "FEDFUNDS")

FRED series are assigned categories and tags attributes for organization and classification. The following examples illustrate usage of the Series endpoint functions in fredr.

Retrieve observations

The function fredr(), an alias for fredr_series_observations(), is the core function in fredr for fetching FRED data series. See the Get started article and ?fredr() for many usage examples.

fredr(
  series_id = "UNRATE",
  observation_start = as.Date("1990-01-01")
)
#> # A tibble: 381 × 5
#>    date       series_id value realtime_start realtime_end
#>    <date>     <chr>     <dbl> <date>         <date>      
#>  1 1990-01-01 UNRATE      5.4 2021-10-11     2021-10-11  
#>  2 1990-02-01 UNRATE      5.3 2021-10-11     2021-10-11  
#>  3 1990-03-01 UNRATE      5.2 2021-10-11     2021-10-11  
#>  4 1990-04-01 UNRATE      5.4 2021-10-11     2021-10-11  
#>  5 1990-05-01 UNRATE      5.4 2021-10-11     2021-10-11  
#>  6 1990-06-01 UNRATE      5.2 2021-10-11     2021-10-11  
#>  7 1990-07-01 UNRATE      5.5 2021-10-11     2021-10-11  
#>  8 1990-08-01 UNRATE      5.7 2021-10-11     2021-10-11  
#>  9 1990-09-01 UNRATE      5.9 2021-10-11     2021-10-11  
#> 10 1990-10-01 UNRATE      5.9 2021-10-11     2021-10-11  
#> # … with 371 more rows

Search for FRED series

Use fredr_series_search_text() to search for a series by text in the series description. The data returned is a tibble where each row represents series with description text that matches the text specified by search_text. For example, to search for series with description text that matches “UNRATE”:

fredr_series_search_text(
  search_text = "unemployment",
  limit = 100L
)
#> # A tibble: 100 × 16
#>    id          realtime_start realtime_end title observation_sta… observation_end
#>    <chr>       <chr>          <chr>        <chr> <chr>            <chr>          
#>  1 UNRATE      2021-10-11     2021-10-11   Unem… 1948-01-01       2021-09-01     
#>  2 UNRATENSA   2021-10-11     2021-10-11   Unem… 1948-01-01       2021-09-01     
#>  3 NROU        2021-10-11     2021-10-11   Nonc… 1949-01-01       2031-10-01     
#>  4 CCSA        2021-10-11     2021-10-11   Cont… 1967-01-07       2021-09-25     
#>  5 UNEMPLOY    2021-10-11     2021-10-11   Unem… 1948-01-01       2021-09-01     
#>  6 LNS14000006 2021-10-11     2021-10-11   Unem… 1972-01-01       2021-09-01     
#>  7 CCNSA       2021-10-11     2021-10-11   Cont… 1967-01-07       2021-09-25     
#>  8 LNU04000006 2021-10-11     2021-10-11   Unem… 1972-01-01       2021-09-01     
#>  9 NROUST      2021-10-11     2021-10-11   Natu… 1949-01-01       2031-10-01     
#> 10 U6RATE      2021-10-11     2021-10-11   Tota… 1994-01-01       2021-09-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>

Use fredr_series_search_id() to search for a series by character ID of the series. The data returned is a tibble where each row represents series with an ID that matches the text specified by search_text. For example, to search for series with an ID that matches "UNRATE":

fredr_series_search_id(
  search_text = "UNRATE",
  limit = 100L
)
#> # A tibble: 16 × 16
#>    id          realtime_start realtime_end title observation_sta… observation_end
#>    <chr>       <chr>          <chr>        <chr> <chr>            <chr>          
#>  1 UNRATE      2021-10-11     2021-10-11   Unem… 1948-01-01       2021-09-01     
#>  2 UNRATECTH   2021-10-11     2021-10-11   FOMC… 2021-01-01       2024-01-01     
#>  3 UNRATECTHLR 2021-10-11     2021-10-11   Long… 2009-02-18       2021-09-22     
#>  4 UNRATECTL   2021-10-11     2021-10-11   FOMC… 2021-01-01       2024-01-01     
#>  5 UNRATECTLLR 2021-10-11     2021-10-11   Long… 2009-02-18       2021-09-22     
#>  6 UNRATECTM   2021-10-11     2021-10-11   FOMC… 2021-01-01       2024-01-01     
#>  7 UNRATECTMLR 2021-10-11     2021-10-11   Long… 2009-02-18       2021-09-22     
#>  8 UNRATEMD    2021-10-11     2021-10-11   FOMC… 2021-01-01       2024-01-01     
#>  9 UNRATEMDLR  2021-10-11     2021-10-11   Long… 2015-06-17       2021-09-22     
#> 10 UNRATENSA   2021-10-11     2021-10-11   Unem… 1948-01-01       2021-09-01     
#> 11 UNRATERH    2021-10-11     2021-10-11   FOMC… 2021-01-01       2024-01-01     
#> 12 UNRATERHLR  2021-10-11     2021-10-11   Long… 2009-02-18       2021-09-22     
#> 13 UNRATERL    2021-10-11     2021-10-11   FOMC… 2021-01-01       2024-01-01     
#> 14 UNRATERLLR  2021-10-11     2021-10-11   Long… 2009-02-18       2021-09-22     
#> 15 UNRATERM    2021-10-11     2021-10-11   FOMC… 2021-01-01       2024-01-01     
#> 16 UNRATERMLR  2021-10-11     2021-10-11   Long… 2009-02-18       2021-09-22     
#> # … 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>

Search for FRED series by tags

Use fredr_series_search_tags() to search for series tags. The data returned is a tibble where each row represents a tag matching the text in series_search_text. For example, to return the top 100 tags (by series count) matching the text "unemployment":

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 basic information for a FRED series

The fredr_series() function returns information for a single series specified by series_id. The data returned is a tibble in which each row represents the series specified. For example, to get information for the UNRATE series:

fredr_series(series_id = "UNRATE")
#> # A tibble: 1 × 15
#>   id     realtime_start realtime_end title             observation_sta… observation_end
#>   <chr>  <chr>          <chr>        <chr>             <chr>            <chr>          
#> 1 UNRATE 2021-10-11     2021-10-11   Unemployment Rate 1948-01-01       2021-09-01     
#> # … with 9 more variables: frequency <chr>, frequency_short <chr>, units <chr>,
#> #   units_short <chr>, seasonal_adjustment <chr>,
#> #   seasonal_adjustment_short <chr>, last_updated <chr>, popularity <int>,
#> #   notes <chr>

Note that there may potentially be more than one row returned if the series has been revised and real time periods are adjusted:

fredr_series(
  series_id = "UNRATE",
  realtime_start = as.Date("1950-01-01")
)
#> # A tibble: 4 × 15
#>   id     realtime_start realtime_end title      observation_sta… observation_end
#>   <chr>  <chr>          <chr>        <chr>      <chr>            <chr>          
#> 1 UNRATE 1960-03-15     1967-02-08   Civilian … 1948-01-01       1966-12-01     
#> 2 UNRATE 1967-02-09     2012-02-02   Civilian … 1948-01-01       2011-12-01     
#> 3 UNRATE 2012-02-03     2019-09-05   Civilian … 1948-01-01       2019-07-01     
#> 4 UNRATE 2019-09-06     9999-12-31   Unemploym… 1948-01-01       2021-09-01     
#> # … with 9 more variables: frequency <chr>, frequency_short <chr>, units <chr>,
#> #   units_short <chr>, seasonal_adjustment <chr>,
#> #   seasonal_adjustment_short <chr>, last_updated <chr>, popularity <int>,
#> #   notes <chr>

Get the categories for a FRED series

The fredr_series_categories() function returns a list of categories for the series specified by series_id. The data returned is a tibble in which each row represents a category that the series belongs to. For example, to get the categories for the UNRATE series:

fredr_series_categories(series_id = "UNRATE")
#> # A tibble: 1 × 4
#>      id name              parent_id notes                                       
#>   <int> <chr>                 <int> <chr>                                       
#> 1 32447 Unemployment Rate        12 The ratio of unemployed to the civilian lab…

Get the release for a FRED series

The fredr_series_release() function returns a list of releases that the series specified by series_id belongs to. The data returned is a tibble in which each row represents a release that the series belongs to. For example, to get the release for the UNRATE series:

fredr_series_release(series_id = "UNRATE")
#> # A tibble: 1 × 6
#>      id realtime_start realtime_end name                 press_release link     
#>   <int> <chr>          <chr>        <chr>                <lgl>         <chr>    
#> 1    50 2021-10-11     2021-10-11   Employment Situation TRUE          http://w…

Get the tags for a FRED series

The fredr_series_tags() function returns a list of tags that are assigned to the series specified by series_id. The data returned is a tibble in which each row represents a tag assigned to the series. For example, to get the tags for the UNRATE series:

fredr_series_tags(
  series_id = "UNRATE",
  order_by = "name"
)
#> # A tibble: 14 × 6
#>    name                              group_id notes created popularity series_count
#>    <chr>                             <chr>    <chr> <chr>        <int>        <int>
#>  1 16 years +                        gen      ""    2012-0…         59         5822
#>  2 bls                               src      "Bur… 2012-0…         87       174778
#>  3 civilian                          gen      ""    2012-0…         55         9666
#>  4 headline figure                   gen      ""    2013-1…         53           54
#>  5 household survey                  gen      "Cur… 2012-0…         65        21572
#>  6 labor                             gen      ""    2012-0…         61        33608
#>  7 labor underutilization            gen      ""    2012-0…         37          734
#>  8 monthly                           freq     ""    2012-0…         93       213910
#>  9 nation                            geot     ""    2012-0…         99       259706
#> 10 public domain: citation requested cc        <NA> 2018-1…        100       606070
#> 11 rate                              gen      ""    2012-0…         87        47288
#> 12 sa                                seas     "Sea… 2012-0…         88        82588
#> 13 unemployment                      gen      ""    2012-0…         78        32814
#> 14 usa                               geo      "Uni… 2012-0…        100       653248

Get a set of recently updated FRED series

The fredr_series_updates() function returns a list of series recently updated on the FRED server. The data returned is a tibble in which each row represents a series. For example, the default call simply lists 1000 recent updates (the default for the limit parameter), most recent updates appearing first (but here we limit to 10):

fredr_series_updates(limit = 10L)
#> # A tibble: 10 × 14
#>    id              realtime_start realtime_end title observation_sta… observation_end
#>    <chr>           <chr>          <chr>        <chr> <chr>            <chr>          
#>  1 NINVRNSAXDCMXQ  2021-10-11     2021-10-11   Real… 1993-01-01       2021-04-01     
#>  2 NINVRNSAXDCARQ  2021-10-11     2021-10-11   Real… 2004-01-01       2021-04-01     
#>  3 NINVNSAXDCMXQ   2021-10-11     2021-10-11   Nomi… 1993-01-01       2021-04-01     
#>  4 NINVPRSAXDCMXQ  2021-10-11     2021-10-11   Real… 1993-01-01       2021-04-01     
#>  5 NINVPNSAXDCMXQ  2021-10-11     2021-10-11   Nomi… 1993-01-01       2021-04-01     
#>  6 NINSAXDCMXQ     2021-10-11     2021-10-11   Nomi… 1993-01-01       2021-04-01     
#>  7 NFISAXDCMXQ     2021-10-11     2021-10-11   Nomi… 1993-01-01       2021-04-01     
#>  8 NFIOTRNSAXDCMXQ 2021-10-11     2021-10-11   Real… 1993-01-01       2021-04-01     
#>  9 NINSAXDCARQ     2021-10-11     2021-10-11   Nomi… 2004-01-01       2021-04-01     
#> 10 NFIRSAXDCMXQ    2021-10-11     2021-10-11   Real… 1993-01-01       2021-04-01     
#> # … with 8 more variables: frequency <chr>, frequency_short <chr>, units <chr>,
#> #   units_short <chr>, seasonal_adjustment <chr>,
#> #   seasonal_adjustment_short <chr>, last_updated <chr>, popularity <int>

Use the start_time and end_time parameters to filter the results by time. For example, to get all the macroeconomic times series updated in the last day:

fredr_series_updates(
  start_time = Sys.time() - 60 * 60 * 24,
  end_time = Sys.time(),
  filter_value = "macro",
  limit = 10L
)
#> # A tibble: 10 × 14
#>    id              realtime_start realtime_end title observation_sta… observation_end
#>    <chr>           <chr>          <chr>        <chr> <chr>            <chr>          
#>  1 NINVRNSAXDCARQ  2021-10-11     2021-10-11   Real… 2004-01-01       2021-04-01     
#>  2 NINVRNSAXDCMXQ  2021-10-11     2021-10-11   Real… 1993-01-01       2021-04-01     
#>  3 NINSAXDCMXQ     2021-10-11     2021-10-11   Nomi… 1993-01-01       2021-04-01     
#>  4 NINVNSAXDCMXQ   2021-10-11     2021-10-11   Nomi… 1993-01-01       2021-04-01     
#>  5 NINVPNSAXDCMXQ  2021-10-11     2021-10-11   Nomi… 1993-01-01       2021-04-01     
#>  6 NINVPRSAXDCMXQ  2021-10-11     2021-10-11   Real… 1993-01-01       2021-04-01     
#>  7 NFIOTRNSAXDCMXQ 2021-10-11     2021-10-11   Real… 1993-01-01       2021-04-01     
#>  8 NFIRSAXDCMXQ    2021-10-11     2021-10-11   Real… 1993-01-01       2021-04-01     
#>  9 NFISAXDCMXQ     2021-10-11     2021-10-11   Nomi… 1993-01-01       2021-04-01     
#> 10 NINSAXDCARQ     2021-10-11     2021-10-11   Nomi… 2004-01-01       2021-04-01     
#> # … with 8 more variables: frequency <chr>, frequency_short <chr>, units <chr>,
#> #   units_short <chr>, seasonal_adjustment <chr>,
#> #   seasonal_adjustment_short <chr>, last_updated <chr>, popularity <int>

Get the vintage dates for a FRED series

The fredr_series_vintagedates() function returns a sequence of dates in history when the series specified by series_id was revised or appended to. The data returned is a tibble where each row is a date. For example, to get the vintage dates for the series UNRATE:

fredr_series_vintagedates(series_id = "UNRATE")
#> # A tibble: 740 × 1
#>    vintage_dates
#>    <chr>        
#>  1 1960-03-15   
#>  2 1960-04-12   
#>  3 1960-05-11   
#>  4 1960-06-13   
#>  5 1960-07-12   
#>  6 1960-08-10   
#>  7 1960-09-09   
#>  8 1960-10-10   
#>  9 1960-11-10   
#> 10 1960-12-12   
#> # … with 730 more rows