time_series: Time Series Data Accessor for ‘twelvedata’

Description

Retrieve Time Series Data from ‘twelvedata’

Usage

time_series(
  sym,
  interval = c("1min", "5min", "15min", "30min", "45min", "1h", "2h", "4h", "1day",
    "1week", "1month"),
  as = c("data.frame", "xts", "raw"),
  exchange = "",
  country = "",
  type = c(NA_character_, "Stock", "Index", "ETF", "REIT"),
  outputsize = NA_character_,
  dp = 5,
  order = c("ASC", "DESC"),
  timezone = NA_character_,
  start_date = NA_character_,
  end_date = NA_character_,
  previous_close = FALSE,
  apikey
)

Arguments

sym

(character) A (single or vector) symbol understood by the backend as a stock symbol, foreign exchange pair, or more. See the ‘twelvedata’ documentation for details on what is covered. In the case of a vector of arguments a list is returned.

interval

(character) A valid interval designator ranging form “1min” to “1month”. Currently supported are 1, 5, 15, 30 and 45 minutes, 1, 2, 4 hours (using suffix ‘h’, as well as “1day”, “1week” and “1month”.

(optional, character) A selector for the desired output format: one of “data.frame” (the default), “xts” (requiring the package to be installed), or “raw”.

exchange

(optional, character) A selection of the exchange for which data for “sym” is requested, default value is unset.

country

(optional, character) A selection of the country exchange for which data for “sym” is requested, default value is unset.

type

(optional, character) A valid security type selection, if set it must be one of “Stock” (the default), “Index”, “ETF” or “REIT”. Default is unset via the NA character value. This field may require the premium subscription.

outputsize

(optional, numeric) The requested number of data points with an internal default value of 30 if unset, and a valid range of 1 to 5000; we use NA as a default argument to signify leaving it unset.

(optional, numeric) The number of decimal places returned on floating point numbers. The value can be between 0 and 11, with a default value of 5.

order

(optional, character) The sort order for the returned time series, must be one of “ASC” (the default) or “DESC”.

timezone

(optional, character) The timezone of the returned time stamp. This parameter is optional. Possible values are “Exchange” (the default) to return the exchange-supplied value, “UTC” to use UTC, or a value IANA timezone name such as “America/New_York” (see link{OlsonNames} to see the values R knows). Note that the IANA timezone values are case-sensitive. Note that intra-day data is converted to an R datetime object (the standard POSIXct type) using the exchange timestamp in the returned metadata, if present.

start_date

(optional, character or date(time) type) The beginning of the time window for which data is requested, can be used with or without end_date. The format must be a standard ISO 8601 format such as “2020-12-31” or “2020-12-31 08:30:00”, or a Date or POSIXt object.

end_date

(optional, character or date(time) type) The end of the time window for which data is requested, can be used with or without start_date. The format must be a standard ISO 8601 format such as “2020-12-31” or “2020-12-31 08:30:00”, or a Date or POSIXt object.

previous_close

(optional, boolean) A logical switch to select inclusion of the previous close value, defaults to FALSE.

apikey

(optional character) An API key override, if missing a value cached from package startup is used. The startup looks for either a file in the per-package config directory provided by tools::R_user_dir (for R 4.0.0 or later), or the TWELVEDATA_API_KEY variable.

Value

The requested data is returned in the requested format containing columns for data(time), open, high, low, close, and volume. If the request was unsuccessful, an error message is returned. The date or datetime column is returned parsed as either a Date or Datetime where the latter is parsed under the exchange timezone if present. Additional meta data returned from the query is also provided as attributes. If the call contained a vector of symbols, a (named) list of elements is returned.

Details

This function access time series data from ‘twelvedata’. It requires an API key to be registered and to be supplied either in user-config file (TODO: add simple writer) or an environment variable.

All suitable optional parameters of the API are now supported. We excluded return as csv as this downloader encompasses that functionality by returning a parsed object.

Examples

Run this code

# NOT RUN {
  # requires API key
Sys.setenv(`_R_S3_METHOD_REGISTRATION_NOTE_OVERWRITES_`="false") # suppress load noise
data <- time_series("SPY", "5min", outputsize=500, as="xts")
if (requireNamespace("quantmod", quietly=TRUE))
   suppressMessages(library(quantmod))   # suppress some noise
   chartSeries(data, name=attr(data, "symbol"), theme="white")  # convenient plot for OHLCV
   str(data) # compact view of data and meta data

   cadusd <- time_series(sym="CAD/USD", interval="1week", outputsize=52.25*20, as="xts")
   chart_Series(cadusd, name=attr(data, "symbol"))

   gme <- time_series("GME", "1min", start_date="2021-01-25T09:30:00",
                       end_date="2021-02-04T16:00:00", as="xts")
   chart_Series(gme, name=paste0(attr(gme, "symbol"), "/", attr(gme, "exchange")))

   res <- time_series(c("SPY", "QQQ", "IWM", "EEM"), outputsize=300, as="xts")
   op <- par(mfrow=c(2,2))
   sapply(res, function(x) quantmod::chart_Series(x, name=attr(x, "symbol")))
   par(op)
# }