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:
series_id = "UNRATE")series_id = "GNPCA")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.
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: 399 × 5
#> date series_id value realtime_start realtime_end
#> <date> <chr> <dbl> <date> <date>
#> 1 1990-01-01 UNRATE 5.4 2023-04-17 2023-04-17
#> 2 1990-02-01 UNRATE 5.3 2023-04-17 2023-04-17
#> 3 1990-03-01 UNRATE 5.2 2023-04-17 2023-04-17
#> 4 1990-04-01 UNRATE 5.4 2023-04-17 2023-04-17
#> 5 1990-05-01 UNRATE 5.4 2023-04-17 2023-04-17
#> 6 1990-06-01 UNRATE 5.2 2023-04-17 2023-04-17
#> 7 1990-07-01 UNRATE 5.5 2023-04-17 2023-04-17
#> 8 1990-08-01 UNRATE 5.7 2023-04-17 2023-04-17
#> 9 1990-09-01 UNRATE 5.9 2023-04-17 2023-04-17
#> 10 1990-10-01 UNRATE 5.9 2023-04-17 2023-04-17
#> # ℹ 389 more rowsUse 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_start observation_end
#> <chr> <chr> <chr> <chr> <chr> <chr>
#> 1 UNRATE 2023-04-17 2023-04-17 Unem… 1948-01-01 2023-03-01
#> 2 UNRATENSA 2023-04-17 2023-04-17 Unem… 1948-01-01 2023-03-01
#> 3 NROU 2023-04-17 2023-04-17 Nonc… 1949-01-01 2033-10-01
#> 4 CCSA 2023-04-17 2023-04-17 Cont… 1967-01-07 2023-04-01
#> 5 UNEMPLOY 2023-04-17 2023-04-17 Unem… 1948-01-01 2023-03-01
#> 6 CCNSA 2023-04-17 2023-04-17 Cont… 1967-01-07 2023-04-01
#> 7 LNS14000… 2023-04-17 2023-04-17 Unem… 1972-01-01 2023-03-01
#> 8 LNU03000… 2023-04-17 2023-04-17 Unem… 1948-01-01 2023-03-01
#> 9 LNU04000… 2023-04-17 2023-04-17 Unem… 1972-01-01 2023-03-01
#> 10 U6RATE 2023-04-17 2023-04-17 Tota… 1994-01-01 2023-03-01
#> # ℹ 90 more rows
#> # ℹ 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_start observation_end
#> <chr> <chr> <chr> <chr> <chr> <chr>
#> 1 UNRATE 2023-04-17 2023-04-17 Unem… 1948-01-01 2023-03-01
#> 2 UNRATECTH 2023-04-17 2023-04-17 FOMC… 2023-01-01 2025-01-01
#> 3 UNRATECT… 2023-04-17 2023-04-17 Long… 2009-02-18 2023-03-22
#> 4 UNRATECTL 2023-04-17 2023-04-17 FOMC… 2023-01-01 2025-01-01
#> 5 UNRATECT… 2023-04-17 2023-04-17 Long… 2009-02-18 2023-03-22
#> 6 UNRATECTM 2023-04-17 2023-04-17 FOMC… 2023-01-01 2025-01-01
#> 7 UNRATECT… 2023-04-17 2023-04-17 Long… 2009-02-18 2023-03-22
#> 8 UNRATEMD 2023-04-17 2023-04-17 FOMC… 2023-01-01 2025-01-01
#> 9 UNRATEMD… 2023-04-17 2023-04-17 Long… 2015-06-17 2023-03-22
#> 10 UNRATENSA 2023-04-17 2023-04-17 Unem… 1948-01-01 2023-03-01
#> 11 UNRATERH 2023-04-17 2023-04-17 FOMC… 2023-01-01 2025-01-01
#> 12 UNRATERH… 2023-04-17 2023-04-17 Long… 2009-02-18 2023-03-22
#> 13 UNRATERL 2023-04-17 2023-04-17 FOMC… 2023-01-01 2025-01-01
#> 14 UNRATERL… 2023-04-17 2023-04-17 Long… 2009-02-18 2023-03-22
#> 15 UNRATERM 2023-04-17 2023-04-17 FOMC… 2023-01-01 2025-01-01
#> 16 UNRATERM… 2023-04-17 2023-04-17 Long… 2009-02-18 2023-03-22
#> # ℹ 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_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… 99 44396
#> 2 usa geo "Uni… 2012-0… 100 41728
#> 3 public domain: citation reque… cc NA 2018-1… 99 41412
#> 4 bls src "Bur… 2012-0… 88 37482
#> 5 unemployment gen "" 2012-0… 72 32748
#> 6 county geot "Cou… 2012-0… 76 28198
#> 7 annual freq "" 2012-0… 88 24022
#> 8 household survey gen "Cur… 2012-0… 62 19848
#> 9 monthly freq "" 2012-0… 94 18814
#> 10 rate gen "" 2012-0… 85 14938
#> # ℹ 90 more rowsUse 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 × 6
#> name group_id notes created popularity series_count
#> <chr> <chr> <chr> <chr> <int> <int>
#> 1 nation geot "" 2012-0… 99 74
#> 2 gnp gen "Gro… 2012-0… 34 60
#> 3 public domain: citation reque… cc NA 2018-1… 99 56
#> 4 quarterly freq "" 2012-0… 84 54
#> 5 sa seas "Sea… 2012-0… 89 48
#> 6 bea src "Bur… 2012-0… 78 46
#> 7 nipa rls "Nat… 2012-0… 70 46
#> 8 gdp gen "Gro… 2012-0… 81 40
#> 9 nsa seas "Not… 2012-0… 99 26
#> 10 annual freq "" 2012-0… 88 20
#> # ℹ 20 more rowsThe 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_start observation_end
#> <chr> <chr> <chr> <chr> <chr> <chr>
#> 1 UNRATE 2023-04-17 2023-04-17 Unemploy… 1948-01-01 2023-03-01
#> # ℹ 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_start 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 Unemploy… 1948-01-01 2023-03-01
#> # ℹ 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>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…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 2023-04-16 2023-04-16 Employment Situation TRUE http://w…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… 58 5812
#> 2 bls src "Bur… 2012-0… 88 175524
#> 3 civilian gen "" 2012-0… 53 9638
#> 4 headline figure gen "" 2013-1… 53 50
#> 5 household survey gen "Cur… 2012-0… 62 21528
#> 6 labor gen "" 2012-0… 61 33822
#> 7 labor underutilization gen "" 2012-0… 35 748
#> 8 monthly freq "" 2012-0… 94 213768
#> 9 nation geot "" 2012-0… 99 262536
#> 10 public domain: citation reque… cc NA 2018-1… 99 608914
#> 11 rate gen "" 2012-0… 85 47028
#> 12 sa seas "Sea… 2012-0… 89 93932
#> 13 unemployment gen "" 2012-0… 72 32722
#> 14 usa geo "Uni… 2012-0… 100 655680The 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 × 15
#> id realtime_start realtime_end title observation_start observation_end
#> <chr> <chr> <chr> <chr> <chr> <chr>
#> 1 NASDAQCOM 2023-04-17 2023-04-17 NASD… 1971-02-05 2023-04-14
#> 2 NASDAQ100 2023-04-17 2023-04-17 NASD… 1986-01-02 2023-04-14
#> 3 WILL4500… 2023-04-17 2023-04-17 Wils… 1986-12-31 2023-04-14
#> 4 WILL4500… 2023-04-17 2023-04-17 Wils… 1983-12-30 2023-04-14
#> 5 WILL2500… 2023-04-17 2023-04-17 Wils… 1991-12-31 2023-04-14
#> 6 WILLMIDC… 2023-04-17 2023-04-17 Wils… 1991-12-31 2023-04-14
#> 7 WILLMIDC… 2023-04-17 2023-04-17 Wils… 1991-12-31 2023-04-14
#> 8 WILLLRGC… 2023-04-17 2023-04-17 Wils… 1991-12-31 2023-04-14
#> 9 WILL2500… 2023-04-17 2023-04-17 Wils… 1991-12-31 2023-04-14
#> 10 WILL2500… 2023-04-17 2023-04-17 Wils… 1991-12-31 2023-04-14
#> # ℹ 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 × 15
#> id realtime_start realtime_end title observation_start observation_end
#> <chr> <chr> <chr> <chr> <chr> <chr>
#> 1 NASDAQCOM 2023-04-17 2023-04-17 NASD… 1971-02-05 2023-04-14
#> 2 NASDAQ100 2023-04-17 2023-04-17 NASD… 1986-01-02 2023-04-14
#> 3 WILL4500… 2023-04-17 2023-04-17 Wils… 1983-12-30 2023-04-14
#> 4 WILL4500… 2023-04-17 2023-04-17 Wils… 1986-12-31 2023-04-14
#> 5 WILL2500… 2023-04-17 2023-04-17 Wils… 1991-12-31 2023-04-14
#> 6 WILLMIDC… 2023-04-17 2023-04-17 Wils… 1991-12-31 2023-04-14
#> 7 WILLMIDC… 2023-04-17 2023-04-17 Wils… 1991-12-31 2023-04-14
#> 8 WILLLRGC… 2023-04-17 2023-04-17 Wils… 1991-12-31 2023-04-14
#> 9 WILLLRGC… 2023-04-17 2023-04-17 Wils… 1991-12-31 2023-04-14
#> 10 WILL2500… 2023-04-17 2023-04-17 Wils… 1991-12-31 2023-04-14
#> # ℹ 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>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: 758 × 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
#> # ℹ 748 more rows