blsR (version 0.5.0)

get_n_series: Create and execute a query to retrieve one or more time series and their catalog data

Description

Create and execute a query to retrieve one or more time series and their catalog data

Usage

get_n_series(
  series_ids,
  api_key = bls_get_key(),
  start_year = NULL,
  end_year = NULL,
  year_limit = NULL,
  span = TRUE,
  catalog = FALSE,
  calculations = FALSE,
  annualaverage = FALSE,
  aspects = FALSE,
  series_limit = NULL,
  ...
)

Value

a list of series results. Each element of the returned list is a named list guaranteed to have two items, SeriesID and data and optionally catalog. The unnamed list data will have 0 or more elements, each one a named list representing an observation in the time series. Each observation is guaranteed to include the elements year, period, periodName, value, and footnotes. Footnotes are a list of named lists. The rest are scalar values. If the the most recent observation is included, that observation will have an element named latest which will contain the text 'true'. If calculations or aspects were requested they will be present as named elements in each observation.

Arguments

series_ids

a list or character vector of BLS time-series IDs. If the items are named then the names will be used in the returned list

api_key

Optional. An API key string. Defaults to the value returned by bls_get_key(). The preferred way to provide an API key is to use bls_set_key() or the BLS_API_KEY environment variable. Manually passing the key will be deprecated in future releases.

start_year, end_year

numeric 4-digit years. While optional, they are strongly recommended. If one is provided, the other is mandatory. end_year must be greater than start_year

year_limit

optional number of years to paginate request by. If not explicitly set, it will be set to 10 or 20 depending on if an api_key is available

span

when set to TRUE, requests where the number of years between start_year and end_year exceed year_limit will be performed as multiple requests automatically

catalog

boolean. If set to TRUE, element item in the list returned may include a named item catalog, a named list containing descriptive information about the series. Not all series have a catalog entry available.

calculations

boolean. If set to TRUE, each element in the data list for each series returned may include an additional named element calculations, a named list containing two items, net_changes and pct_changes, each of them a named list which may include items 1, 3, 6, 12 which represent 1, 3, 6, and 12 month net changes and percent changes respectively. Not all data series will have enough data points to include these calculations.

annualaverage

boolean. If set to TRUE, each data list may include an additional element for a an annual average of the time series, which is usually presented as month 13 in monthly data. Not all data series support this feature.

aspects

boolean. If set to TRUE, each item in the data list for each series returned may include an additional named element aspects, which will be a named list. Not all data series support this feature.

series_limit

Maximum number of series to request in one API call when span is set to TRUE.

...

additional arguments to pass to bls_request()

See Also

query_n_series

Other blsR-requests: bls_request(), get_all_surveys(), get_latest_observation(), get_n_series_table(), get_popular_series(), get_series_tables(), get_series_table(), get_series(), get_survey_info(), reduce_spanned_responses(), span_series_request()

Examples

if (FALSE) {
series_ids <- list(uer.men ='LNS14000001', uer.women = 'LNS14000002')
uer_series <- get_n_series(series_ids, 'your-api-key-here' )
}