Skip to contents

API_interface_usage

Source: vignettes/API_interface_usage.Rmd
API_interface_usage.Rmd

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:

require(alphavantagepf)
#> Loading required package: alphavantagepf
avpf_api_key("YOUR_API_KEY","delayed")
print(avpf_api_key())
#> [1] "YOUR_API_KEY" "delayed"

Finding Functions and their defaults

To find parameters and defaults provided by the alphavantagepf package, use av_funhelp()

av_funhelp("SERIES_INTRADAY")
#> Function: TIME_SERIES_INTRADAY
#> Category: equity
#> 
#> Parameters:
#> R> symbol
#> R> interval (default: 15min)
#> O> adjusted
#> O> extended_hours
#> O> month
#> O> outputsize (default: compact)
#> O> entitlement (default: {entitlement})
#> [1] "Function: TIME_SERIES_INTRADAY\nCategory: equity\n\nParameters:\nR> symbol\nR> interval (default: 15min)\nO> adjusted\nO> extended_hours\nO> month\nO> outputsize (default: compact)\nO> entitlement (default: {entitlement})\n"

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. Those defaults can be seen using the av_funhelp() function, or can be seen by calling av_get_pf() with verbose=TRUE. Any overrides to those parameters can be specified as additional arguments to av_get_pf(). For example, to get SMA using multiple horizon lengths can be seen below:

> 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
      <char>     <IDat> <num>
   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() 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

av_get_pf("","TOP_GAINERS_LOSERS")

Key: <variable>
               symbol             variable     ltype           value_df                                value_str value_num
               <char>               <char>    <char>             <list>                                   <char>     <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 <data.frame[20x5]>                                     NULL        NA
4: TOP_GAINERS_LOSERS          top_gainers      list <data.frame[20x5]>                                     NULL        NA
5: TOP_GAINERS_LOSERS           top_losers      list <data.frame[20x5]>                                     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() 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() function

av_extract_df() function:

av_get_pf("","TOP_GAINERS_LOSERS") |> av_extract_df("top_losers")

    <char>   <num>         <num>            <char>     <num>             <char>
 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

# REAL-TIME QUOTE
av_get_pf("USD/BRL","CURRENCY_EXCHANGE_RATE") |> av_extract_fx()

Key: <symbol>
    symbol   Ask   Bid      QuoteTimestamp   Mid
    <char> <num> <num>              <POSc> <num>
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:

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 ...
   <char>             <char>     <IDat>  <num> <char> <num> <num> <num>    <int> <num>    <int>  <int>      ...
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.

 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
                 <char>                  <char>     <char>              <char>
1:              symbols                    <NA>       <NA>            ORCL,IBM
2:               min_dt                    <NA>       <NA>          2025-12-09
3:               max_dt                    <NA>       <NA>          2026-01-06
4:                 ohlc                    <NA>       <NA>               Close
5:             interval                    <NA>       <NA>               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(). The function will return a data.table.
  5. Some output above has been truncated to adhere to licensing rules.

Examples

Time series data 

av_get_pf("IBM","TIME_SERIES_INTRADAY") |> head()

   symbol  timestamp  open  high   low close   volume
   <char>     <IDat> <num> <num> <num> <num>    <int>
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 

av_get_pf("","TOP_GAINERS_LOSERS")

Key: <variable>
               symbol             variable     ltype           value_df                                value_str value_num
               <char>               <char>    <char>             <list>                                   <char>     <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 <data.frame[20x5]>                                     NULL        NA
4: TOP_GAINERS_LOSERS          top_gainers      list <data.frame[20x5]>                                     NULL        NA
5: TOP_GAINERS_LOSERS           top_losers      list <data.frame[20x5]>                                     NULL        NA