Author: Sam Boysel
Date: 2021-01-29

# FRED Series

#### Sam Boysel

#### 2021-01-29

# Introduction

    library(fredr)

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: 372 x 5
    #>    date       series_id value realtime_start realtime_end
    #>    <date>     <chr>     <dbl> <date>         <date>
    #>  1 1990-01-01 UNRATE      5.4 2021-01-29     2021-01-29
    #>  2 1990-02-01 UNRATE      5.3 2021-01-29     2021-01-29
    #>  3 1990-03-01 UNRATE      5.2 2021-01-29     2021-01-29
    #>  4 1990-04-01 UNRATE      5.4 2021-01-29     2021-01-29
    #>  5 1990-05-01 UNRATE      5.4 2021-01-29     2021-01-29
    #>  6 1990-06-01 UNRATE      5.2 2021-01-29     2021-01-29
    #>  7 1990-07-01 UNRATE      5.5 2021-01-29     2021-01-29
    #>  8 1990-08-01 UNRATE      5.7 2021-01-29     2021-01-29
    #>  9 1990-09-01 UNRATE      5.9 2021-01-29     2021-01-29
    #> 10 1990-10-01 UNRATE      5.9 2021-01-29     2021-01-29
    #> # … with 362 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 x 16
    #>    id    realtime_start realtime_end title observation_sta… observation_end
    #>    <chr> <chr>          <chr>        <chr> <chr>            <chr>
    #>  1 UNRA… 2021-01-29     2021-01-29   Unem… 1948-01-01       2020-12-01
    #>  2 UNRA… 2021-01-29     2021-01-29   Unem… 1948-01-01       2020-12-01
    #>  3 LNS1… 2021-01-29     2021-01-29   Unem… 1972-01-01       2020-12-01
    #>  4 CCSA  2021-01-29     2021-01-29   Cont… 1967-01-07       2021-01-16
    #>  5 CCNSA 2021-01-29     2021-01-29   Cont… 1967-01-07       2021-01-16
    #>  6 NROU  2021-01-29     2021-01-29   Natu… 1949-01-01       2030-10-01
    #>  7 LNU0… 2021-01-29     2021-01-29   Unem… 1972-01-01       2020-12-01
    #>  8 LNS1… 2021-01-29     2021-01-29   Unem… 1972-01-01       2020-12-01
    #>  9 LNU0… 2021-01-29     2021-01-29   Unem… 1972-01-01       2020-12-01
    #> 10 UNEM… 2021-01-29     2021-01-29   Unem… 1948-01-01       2020-12-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 x 16
    #>    id    realtime_start realtime_end title observation_sta… observation_end
    #>    <chr> <chr>          <chr>        <chr> <chr>            <chr>
    #>  1 UNRA… 2021-01-29     2021-01-29   Unem… 1948-01-01       2020-12-01
    #>  2 UNRA… 2021-01-29     2021-01-29   FOMC… 2020-01-01       2023-01-01
    #>  3 UNRA… 2021-01-29     2021-01-29   Long… 2009-02-18       2020-12-16
    #>  4 UNRA… 2021-01-29     2021-01-29   FOMC… 2020-01-01       2023-01-01
    #>  5 UNRA… 2021-01-29     2021-01-29   Long… 2009-02-18       2020-12-16
    #>  6 UNRA… 2021-01-29     2021-01-29   FOMC… 2020-01-01       2023-01-01
    #>  7 UNRA… 2021-01-29     2021-01-29   Long… 2009-02-18       2020-12-16
    #>  8 UNRA… 2021-01-29     2021-01-29   FOMC… 2020-01-01       2023-01-01
    #>  9 UNRA… 2021-01-29     2021-01-29   Long… 2015-06-17       2020-12-16
    #> 10 UNRA… 2021-01-29     2021-01-29   Unem… 1948-01-01       2020-12-01
    #> 11 UNRA… 2021-01-29     2021-01-29   FOMC… 2020-01-01       2023-01-01
    #> 12 UNRA… 2021-01-29     2021-01-29   Long… 2009-02-18       2020-12-16
    #> 13 UNRA… 2021-01-29     2021-01-29   FOMC… 2020-01-01       2023-01-01
    #> 14 UNRA… 2021-01-29     2021-01-29   Long… 2009-02-18       2020-12-16
    #> 15 UNRA… 2021-01-29     2021-01-29   FOMC… 2020-01-01       2023-01-01
    #> 16 UNRA… 2021-01-29     2021-01-29   Long… 2009-02-18       2020-12-16
    #> # … 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 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

## Search for FRED series by related tags

Use `fredr_search_related_tags()` to search for series tags related to a given tag. The data returned is a tibble where each row represents a tag who’s series matches the text in `series_search_text` and related tags specified by `tag_names`. For example, to search for tags related to the tag `"usa"` in which the series text matches `"gnp"`, use the following:

    fredr_series_search_related_tags(
      series_search_text = "gnp",
      tag_names = "usa",
      limit = 30L
    )
    #> # A tibble: 30 x 6
    #>    name            group_id notes            created     popularity series_count
    #>    <chr>           <chr>    <chr>            <chr>            <int>        <int>
    #>  1 nation          geot     ""               2012-02-27…         99           78
    #>  2 gnp             gen      "Gross National… 2012-02-27…         38           60
    #>  3 public domain:… cc        <NA>            2018-12-17…        100           54
    #>  4 quarterly       freq     ""               2012-02-27…         85           46
    #>  5 sa              seas     "Seasonally Adj… 2012-02-27…         88           42
    #>  6 bea             src      "Bureau of Econ… 2012-02-27…         79           38
    #>  7 nipa            rls      "National Incom… 2012-08-16…         71           38
    #>  8 nsa             seas     "Not Seasonally… 2012-02-27…        100           36
    #>  9 annual          freq     ""               2012-02-27…         90           32
    #> 10 gdp             gen      "Gross Domestic… 2012-02-27…         82           30
    #> # … with 20 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 x 15
    #>   id    realtime_start realtime_end title observation_sta… observation_end
    #>   <chr> <chr>          <chr>        <chr> <chr>            <chr>
    #> 1 UNRA… 2021-01-29     2021-01-29   Unem… 1948-01-01       2020-12-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 x 15
    #>   id    realtime_start realtime_end title observation_sta… observation_end
    #>   <chr> <chr>          <chr>        <chr> <chr>            <chr>
    #> 1 UNRA… 1960-03-15     1967-02-08   Civi… 1948-01-01       1966-12-01
    #> 2 UNRA… 1967-02-09     2012-02-02   Civi… 1948-01-01       2011-12-01
    #> 3 UNRA… 2012-02-03     2019-09-05   Civi… 1948-01-01       2019-07-01
    #> 4 UNRA… 2019-09-06     9999-12-31   Unem… 1948-01-01       2020-12-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 x 4
    #>      id name          parent_id notes
    #>   <int> <chr>             <int> <chr>
    #> 1 32447 Unemployment…        12 The ratio of unemployed to the civilian labor f…

## 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 x 6
    #>      id realtime_start realtime_end name           press_release link
    #>   <int> <chr>          <chr>        <chr>          <lgl>         <chr>
    #> 1    50 2021-01-28     2021-01-28   Employment Si… TRUE          http://www.bls…

## 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 x 6
    #>    name           group_id notes             created     popularity series_count
    #>    <chr>          <chr>    <chr>             <chr>            <int>        <int>
    #>  1 16 years +     gen      ""                2012-02-27…         59         5810
    #>  2 bls            src      "Bureau of Labor… 2012-02-27…         87       155934
    #>  3 civilian       gen      ""                2012-02-27…         55         9542
    #>  4 headline figu… gen      ""                2013-11-19…         53           56
    #>  5 household sur… gen      "Current Populat… 2012-06-18…         65        21444
    #>  6 labor          gen      ""                2012-02-27…         61        30444
    #>  7 labor underut… gen      ""                2012-05-10…         37          702
    #>  8 monthly        freq     ""                2012-02-27…         93       211262
    #>  9 nation         geot     ""                2012-02-27…         99       238772
    #> 10 public domain… cc        <NA>             2018-12-17…        100       572628
    #> 11 rate           gen      ""                2012-02-27…         87        46828
    #> 12 sa             seas     "Seasonally Adju… 2012-02-27…         88        79660
    #> 13 unemployment   gen      ""                2012-02-27…         78        32512
    #> 14 usa            geo      "United States o… 2012-02-27…        100       625832

## 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 x 15
    #>    id    realtime_start realtime_end title observation_sta… observation_end
    #>    <chr> <chr>          <chr>        <chr> <chr>            <chr>
    #>  1 EVZC… 2021-01-29     2021-01-29   CBOE… 2007-11-01       2021-01-28
    #>  2 GVZC… 2021-01-29     2021-01-29   CBOE… 2008-06-03       2021-01-28
    #>  3 OVXC… 2021-01-29     2021-01-29   CBOE… 2007-05-10       2021-01-28
    #>  4 RVXC… 2021-01-29     2021-01-29   CBOE… 2004-01-02       2021-01-28
    #>  5 VXAP… 2021-01-29     2021-01-29   CBOE… 2010-06-01       2021-01-28
    #>  6 VIXC… 2021-01-29     2021-01-29   CBOE… 1990-01-02       2021-01-28
    #>  7 VXDC… 2021-01-29     2021-01-29   CBOE… 1997-10-07       2021-01-28
    #>  8 VXAZ… 2021-01-29     2021-01-29   CBOE… 2010-06-01       2021-01-28
    #>  9 VXEE… 2021-01-29     2021-01-29   CBOE… 2011-03-16       2021-01-28
    #> 10 VXFX… 2021-01-29     2021-01-29   CBOE… 2011-03-16       2021-01-28
    #> # … 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>

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 x 15
    #>    id    realtime_start realtime_end title observation_sta… observation_end
    #>    <chr> <chr>          <chr>        <chr> <chr>            <chr>
    #>  1 EVZC… 2021-01-29     2021-01-29   CBOE… 2007-11-01       2021-01-28
    #>  2 GVZC… 2021-01-29     2021-01-29   CBOE… 2008-06-03       2021-01-28
    #>  3 RVXC… 2021-01-29     2021-01-29   CBOE… 2004-01-02       2021-01-28
    #>  4 OVXC… 2021-01-29     2021-01-29   CBOE… 2007-05-10       2021-01-28
    #>  5 VIXC… 2021-01-29     2021-01-29   CBOE… 1990-01-02       2021-01-28
    #>  6 VXAP… 2021-01-29     2021-01-29   CBOE… 2010-06-01       2021-01-28
    #>  7 VXDC… 2021-01-29     2021-01-29   CBOE… 1997-10-07       2021-01-28
    #>  8 VXEE… 2021-01-29     2021-01-29   CBOE… 2011-03-16       2021-01-28
    #>  9 VXAZ… 2021-01-29     2021-01-29   CBOE… 2010-06-01       2021-01-28
    #> 10 VXFX… 2021-01-29     2021-01-29   CBOE… 2011-03-16       2021-01-28
    #> # … 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 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: 731 x 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 721 more rows