--- title: "IEX Stocks and Market Data via IEX API" author: "Myriam Ibrahim" date: "`r Sys.Date()`" output: rmarkdown::html_vignette vignette: > %\VignetteIndexEntry{IEX Stocks and Market Data via IEX API} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8} --- ```{r setup, include = FALSE} knitr::opts_chunk$set( collapse = TRUE, comment = "#>" ) ``` The main goal of `Riex` is to efficiently retrieve financial and market data using `IEX Cloud API`. In addition, provide robust tool to: - Enable data analysis and visualization - Monitor account usage and alerts Please make sure to review and acknowledge [IEX Terms of Use](https://iexcloud.io/terms/) before using `Riex`. Effective June 1st, 2019, subscription will be required to access third party data. For subscriptions details, visit [IEX - Flexible, scalable pricing](https://iexcloud.io/pricing/). - Multiple tiers are available to users depending on their requirements with capability to upgrade - Usage is measured based on message counts which depends on API Call and associated weight - Example [Company - API Call](https://iexcloud.io/docs/api/#company) has a weight of 1 for each Symbol Additional details about usage calculations available in [Data Weight - section](https://iexcloud.io/docs/api/#how-credits-work) as well as best practice about storing and sharing [Private & Public Secret Key](https://iexcloud.io/docs/api/#authentication) ## Installation You can `install` the released version of Riex from [CRAN](https://CRAN.R-project.org) with: ``` r install.packages("Riex") ``` ## Examples Following are basic examples that will demonstrate how to use `Riex` to retrieve Stock and Market information via `IEX Cloud API`. List of parameters and their valid values: - iex_sk : `IEX Cloud API` **Secret Token**. *Secret Token* is available to use via Account Console and assigned the variable **sk** in the documentation. e.g. sk <- "sk_xxxxxx". Please note that term "*Secret Token*" and "*Secret Key*" are used interchangeably in `Riex` documentation Keep your **Secret Token** safe. Your **Secret Token** can make any API call on behalf of your account, including changes that may impact billing such as enabling pay-as-you-go charges. - x : A valid IEX Stock Symbol - p : "annual" or "quarter" - r : Takes only of of the values accepted in API request. {"5y", "2y", "1y", "ytd", "6m", "3m", "1m", "1d"} ## Load `Riex` ```{r load, echo=TRUE} library(Riex) ``` - Assign Secret key to Variable **sk** ```r sk <- "[SECRET KEY]" ``` - Assign valid stock symbol to **x** ```{r symbol, echo=TRUE} x <- "TSLA" ``` - Assign valid period to variable **r** ```{r period, echo=TRUE} r <- "6m" ``` ## Chart ```r TSLA <- iex.chart(x, r, sk) ``` Load `quantmod` package ```r library(quantmod) ``` Generate Barchart ```r barChart(TSLA) ``` ```{r, echo=FALSE, message=FALSE, fig.cap='TSLA 6 Months Chart', fig.align='center'} knitr::include_graphics("./TSLA_6M_Chart.png") ``` To check available themes to customize visualization ```r names(quantmod:::.chart.theme) ``` To apply a different Theme ```r barChart(TSLA, theme="white") ``` If you receive an error run: ```r par("mar") ``` In case response is similar to the following: [1] 5.1 4.1 4.1 2.1, then run: ```r par(mar=c(1,1,1,1)) barChart(TSLA) ``` ```r chartSeries(TSLA) ``` When possible, results from functions matches OHLC standards for `quantomd` package to leverage its capabilities. Future enhancements to `Riex` will be geared toward enabling comprehensive financial analysis & modeling. Refer to `quantomd` documentation for additional details about customizing visualization. ## Most Active ```r Most_Active <- iex.most.active(sk) Most_Active['companyName'] ``` ## Book ```r iex.book("GM", sk) ``` ## Earnings ```r iex.earnings("GM", sk) ``` ## Financials The following default functions retrieve income statement, balance sheet, and cash flow data from the most recent reported quarter. Upon further testing of `IEX Cloud API`, additional parameter *"p"* will be added to allow user to specify annual or quarterly financials. - iex.balance.sheet (x, sk) - iex.cash.flow (x, sk) - iex.income (x, sk) Results are rendered in data frame format to allow further manipulation in case of multiple stocks ```r GM_BS <- iex.balance.sheet("GM", sk) str(GM_BS) ``` Similarly, you can generate the previous quarter Income Statement and Cash Flow statement: ```r GM_IS <- iex.income("GM", sk) GM_CF <- iex.cash.flow("GM", sk) ``` ## Key Stats Function returns a data frame that includes 20 observations - e.g. PE ratio, number of employees and 52 Weeks high and low, ..etc. ```r iex.stats("TSLA", sk) ``` ## Crypto ```r Bitcoin <- crypto("BTCUSDT", sk) Bitcoin ``` list of available crypto currency symbols in `IEX` as of April 26th, 2019 is included as dataset with `Riex` package and can be viewed using **crypto_symbols**. ```r crypto_symbols ``` for most current list, Visit [IEX-Reference Data](https://iexcloud.io/docs/api/#reference-data) ## Company Information ```r TSLA_Co <- iex.company(x, sk) ``` ## Company Logo ```r TSLA_Logo <- logo (x, sk) ``` To store image in current directory, use: ```r download.file(TSLA_Logo,"TSLA.png",mode="wb") ``` To check current directory path: ```r getwd() ``` ```{r, echo=FALSE, message=FALSE, fig.cap='TSLA Logo', fig.align='center'} knitr::include_graphics("./TSLA.png") ``` ## Account Visit [IEX Cloud API - Account Section](https://iexcloud.io/docs/api/#account) for more details. The following functions provide Account and usage details based on **Secret Token** provided. Please make sure to monitor usage regularly as it impacts billing depending on your Account setup. ## Account Metadata Output includes **Total Message Limit** and **Total Message Used** in addition to useful info. - e.g. Tier Name ```r iex.account(sk) ``` ## Usage Output includes **Monthly Usage**, **Monthly Pay As You Go** and **Token Usage**. ```r iex.usage(sk) ``` ## Key Usage Key Usage includes the detailed usage by API Call type. ```r iex.key.usage (sk) ``` For example: - STOCK_QUOTE - HISTORICAL_PRICES - COMPANY - REF_DATA - CRYPTO_QUOTE - COMPANY_LOGO - EARNINGS - KEY_STATS - ACCOUNT_USAGE - CASH_FLOW - BALANCE_SHEET - INCOME Type with "0" usage are included as well. For example, ACCOUNT_USAGE. ## Daily Usage Output includes Total usage per day. Date format is xyyyymmdd - e.g. X20190423 ```r iex.daily.usage(sk) ``` ## Monthly Usage Output includes Total usage per month. ```r iex.monthly.usage(sk) ``` ## Quote of the Day and Everyday ! > "He who gives up [code] safety for [code] speed deserves neither." - [Hadley Wickham](https://twitter.com/hadleywickham/status/504368538874703872) ```{r, echo=FALSE, message=FALSE, fig.cap='Hadley Wickham Quote', fig.align='center'} knitr::include_graphics("./HadleyWickham_Quote.png") ```