---
title: "usage-alphvantagepf"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{usage-alphvantagepf}
  %\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.


```{r setup}
library(alphavantagepf)
```

There is one main function to call to access all of the API functionality provided by Alphavantage.

# Start with API keys


```{r}
av_api_key("YOUR_API_KEY")
print(av_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.


## Examples

### Time series data

```{r, eval=F}
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

```{r, eval=F}
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
```


## Helpers: `av_extract_df`

Extracting the nested data.frames can be a tedious task, so the helper function `av_extract_df()` can be used to filter for the correct variable and extract the data.frame

```{r, eval=F}
av_get_pf("","TOP_GAINERS_LOSERS")  |> av_extract_df("top_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
```