--- title: "API_interface_usage" output: rmarkdown::html_vignette vignette: > %\VignetteIndexEntry{API_interface_usage} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8} --- ```{r, include = FALSE} knitr::opts_chunk$set( collapse = TRUE, comment = "#>" ) ``` **Alphavantagepf** interfaces the Alphavantage API to R in a way most compatible with normalized data stores. It returns data in `data.table()` format, which is really the best choice for financial time series analysis. This package uses just one call to access multiple functions available from the service. As with all APIs, we start by providing a user key: ```{r} require(alphavantagepf) avpf_api_key("YOUR_API_KEY","delayed") print(avpf_api_key()) ``` # Finding Functions and their defaults To find parameters and defaults provided by the `alphavantagepf` package, use `av_funhelp()` ```{r} av_funhelp("SERIES_INTRADAY") ``` Required parameters are listed with "R" and optional parameters (and any default provided by this package) are listed with "O" # Getting Data from Alpha Vantage Once the API key has been set, use the function `av_get_pf()` which requires at minimum two arguments, a `symbol` (put first to facilitate usage in pipes) and an Alphavantage "function" `av_fun`. The resulting output will be a `data.table` that depends on the type of data requested. (Note that data is returned in a `data.table`, which can be cast as tibbles as necessary.) The output will always include the `symbol` requested or the name of the `av_fun` used if a symbol isn't relevent. If that variable isn't wanted (e.g. when called within a grouping function `group_by(symbol) |> do({})` then set `symbolvarnm=""`. * If the data is a time series, the columns will all have the same type, and will be passed along unchanged. * Most other data will be a long-form (melted) datatable with at least the following columns: 1. `symbol` will either be the symbol requested or the value of `av_fun` if a symbol isn't relevant. 2. `variable` which is the name of the data item 3. `value_str`, `value_num` and/or `value_df` which will contain strings (converted to numeric if possible) or (in the case of `value_df`) a nested data.frame. 4. `ltype` is the inferred data-type, helpful for selecting the correct columns. ## Using defaults and overrides The `alphavantagepf` package includes a few default overrides to the defaults chosen in [Alphavantage API documentation](https://www.alphavantage.co/documentation/). Those defaults can be seen using the [av_funhelp()](https://derekholmes0.github.io/alphavantagepf/reference/av_funhelp.html) function, or can be seen by calling [av_get_pf()](https://derekholmes0.github.io/alphavantagepf/reference/av_get_pf.html) with `verbose=TRUE`. Any overrides to those parameters can be specified as additional arguments to [av_get_pf()](https://derekholmes0.github.io/alphavantagepf/reference/av_get_pf.html). For example, to get SMA using multiple horizon lengths can be seen below: ```{r, eval=F} > av_get_pf("IBM","SMA",verbose=T,time_period=30) https://www.alphavantage.co/query?function SMA symbol IBM interval daily time_period 30 # << Normally 60 series_type close datatype csv > response: 200 type: application/x-download... url copied to clipboard symbol time SMA 1: IBM 2026-01-06 304.1 2: IBM 2026-01-05 303.7 ``` # More complex data and helpful data extractors ## Extracting embedded data.frames Some API calls return more complex data, i.e. data with strings, numbers, and nested data.frames collected together. The [av_get_pf()](https://derekholmes0.github.io/alphavantagepf/reference/av_get_pf.html) returns data in as natural a format as possible. For example, time series are not melted, but single name quotes are. The parameter to control this is `melted` with a default value of "melted". `melted` can be set to TRUE (for example) to force or suppress melting into longer data.tables. As an example where the melted form makes more sense is the `TOP_GAINERS_LOSERS` function, which returns separate data.frames for each category. The natural output is ```{r, eval=F} av_get_pf("","TOP_GAINERS_LOSERS") Key: symbol variable ltype value_df value_str value_num 1: TOP_GAINERS_LOSERS last_updated numeric [NULL] 2026-01-05 16:15:59 US/Eastern 2026 2: TOP_GAINERS_LOSERS metadata character [NULL] Top gainers, losers, and most actively t NA 3: TOP_GAINERS_LOSERS most_actively_traded list NULL NA 4: TOP_GAINERS_LOSERS top_gainers list NULL NA 5: TOP_GAINERS_LOSERS top_losers list NULL NA ``` * Note that symbol for `TOP_GAINERS_LOSERS` isn't used, but still needs to be specified. * Note that the data returned is in long form, and always has at least three columns, `symbol` (which cna be changed in [av_get_pf()](https://derekholmes0.github.io/alphavantagepf/reference/av_get_pf.html) optional parameters). `variable` which is the name of the data item returned, and (e.g.) `value_str` or `value_df` with appropriate data components. The data is separated out by type so further delisting doesn't have to be done after the call. If you want to just get, e.g. the top losers, the returned data can be piped into the [av_extract_df()](https://derekholmes0.github.io/alphavantagepf/reference/av_extract_df.html) function `av_extract_df()` function: ```{r, eval=F} av_get_pf("","TOP_GAINERS_LOSERS") |> av_extract_df("top_losers") 1: OCG 0.0378 -0.0654 -63.3721% 216078762 TOP_GAINERS_LOSERS 2: ZBIO 16.6100 -17.8900 -51.8551% 8034469 TOP_GAINERS_LOSERS 3: SGN 0.4627 -0.4873 -51.2947% 2115079 TOP_GAINERS_LOSERS 4: HYT^# 0.0186 -0.0164 -46.8571% 126059 TOP_GAINERS_LOSERS 5: LVROW 0.0122 -0.0079 -39.3035% 10967 TOP_GAINERS_LOSERS ``` ## Foreign exchange The returned data from the `CURRENCY_EXCHANGE_RATE` is a bit complex, and can be simplified with ```{r, eval=F} # REAL-TIME QUOTE av_get_pf("USD/BRL","CURRENCY_EXCHANGE_RATE") |> av_extract_fx() Key: symbol Ask Bid QuoteTimestamp Mid 1: USD/BRL 5.37 5.37 2026-01-06 15:47:46 5.37 ``` ## Options The `HISTORICAL_OPTIONS` function returns a large set of options for any given ticker, many of which are long dated or have no opent interest. The `av_grep_opts()` helper can be used to narrow those down using a comma-separated string specifying 1. How far out maturities should be returned, e.g. Front Month (F) or Back month (B) or all (A) 2. What expiration schedules should be used, e.g. (Q) for Quarterly or (M) for monthlies. 3. "Call", "Put" or "all" So, for example, to get the closest monthly puts with at least 2 days to maturity, use the string "F,M,put". The default is "F,M,call" and (partial) results are shown below: ```{r, eval=F} av_get_pf("IBM","HISTORICAL_OPTIONS") |> av_grep_opts("F,M,put",mindays=2) symbol contractID expiration strike type last mark bid bid_size ask ask_size volume open_interest ... ... 1: IBM IBM260116P00277500 2026-01-16 278 put 0.00 0.80 0.67 158 0.94 254 0 ... 2: IBM IBM260116P00280000 2026-01-16 280 put 0.98 0.96 0.90 180 1.02 10 111 ... 3: IBM IBM260116P00282500 2026-01-16 282 put 1.32 1.29 1.17 213 1.41 158 14 ... ``` ## Analytics requests Analytics requests using the Alphavantage function `ANALYTICS_FIXED_WINDOW` are complicated enough that they are returned in *raw form*, which includes meta-data. These can be untangled using the extracting function `av_extract_analytics`. ```{r, eval=F} av_get_pf(c("ORCL","IBM"),"ANALYTICS_FIXED_WINDOW") |> av_extract_analytics(separate_vars=TRUE) av_get_pf: Reurning raw output; send to appropriate helper ---------------------------- variable_1 variable_2 variable_3 value 1: symbols ORCL,IBM 2: min_dt 2025-12-09 3: max_dt 2026-01-06 4: ohlc Close 5: interval DAILY 6: RETURNS_CALCULATIONS CUMULATIVE_RETURN ORCL -0.12540062294046 7: RETURNS_CALCULATIONS CUMULATIVE_RETURN IBM -0.0257987632053596 8: RETURNS_CALCULATIONS STDDEV(ANNUALIZED=TRUE) ORCL 0.575380551599422 9: RETURNS_CALCULATIONS STDDEV(ANNUALIZED=TRUE) IBM 0.171846694713282 ``` # Important Notes: av_get_pf() 1. Three parameters `apikey`, `datatype` and `outputsize` are filled into the API call from the package. `outputsize` defaults to the full dataset, and can be overridden as a named parameter to the `av_get_pf()` call. An additional parameter `entitlement` is added to the url if specified in the `avpf_api_key()` call and relevant. 2. `av_get_pf()` has an optional `delay` parameter, which may be needed if several short API calls are called sequentially (e.g. within another function). 3. `symbol` is always returned in the output dataset, and defaults to the name of the `av_fun` call if no symbol is relevant. 4. There is no need to specify the `datatype` parameter as an argument to [av_get_pf()](https://derekholmes0.github.io/alphavantagepf/reference/av_get_pf.html). The function will return a data.table. 5. Some output above has been truncated to adhere to licensing rules. # Examples ## Time series data ```{r, eval=F} av_get_pf("IBM","TIME_SERIES_INTRADAY") |> head() symbol timestamp open high low close volume 1: IBM 1999-11-01 98.5 98.8 96.4 96.8 9551800 2: IBM 1999-11-02 96.8 96.8 93.7 94.8 11105400 ``` ## Mixed use data ```{r, eval=F} av_get_pf("","TOP_GAINERS_LOSERS") Key: symbol variable ltype value_df value_str value_num 1: TOP_GAINERS_LOSERS last_updated numeric [NULL] 2026-01-05 16:15:59 US/Eastern 2026 2: TOP_GAINERS_LOSERS metadata character [NULL] Top gainers, losers, and most actively t NA 3: TOP_GAINERS_LOSERS most_actively_traded list NULL NA 4: TOP_GAINERS_LOSERS top_gainers list NULL NA 5: TOP_GAINERS_LOSERS top_losers list NULL NA ```