R/iexcloud.R

In kermit-t-frog/iexcloudr: Facilitates the IEX cloud api at https://iexcloud.io

#' Set IEX cloud api key
#'
#' @param api_key productive or sandbox publishable IEX cloud api key.
#' @param secret_key Optional: productive or sandbox IEX cloud secret key, only
#' required if you want to query credit usage
#' @param sandbox Set to TRUE for sandbox mode, i.e. when api key and/or secret
#' key are used for testing.
#'
#' @return sets the api key.
#' @export
#' @examples
#' \dontrun{
#' apikey("your_api_key_here")
#' }
apikey <- function(api_key,secret_key,sandbox){

  if (!missing(api_key)) {
    options(iex_api_key = api_key)
  }
  if (!missing(secret_key)){
    options(iex_secret_api_key = secret_key)
  }
  if (!missing(sandbox)){
    if (sandbox){
      message("iexcloudr sandbox mode")
      options(iex_api = "https://sandbox.iexapis.com/stable")
    } else {
      message("iexcloudr production mode")
      options(iex_api = "https://cloud.iexapis.com/stable")
    }
  }

  invisible(getOption("iex_api_key"))
}

#' Query current month credit usage
#'
#' @return This months credit usage for your account.
#' @export
#' @importFrom httr GET content
#' @importFrom jsonlite fromJSON
#' @importFrom magrittr %>% %$%
#' @examples
#' \dontrun{
#' apikey(secret_key="your_secret_key")
#' credit_usage()}
credit_usage <- function(){
  token <- paste0("?token=",getOption("iex_secret_api_key"))
  endpoint <- paste0(getOption("iex_api"),"/account/usage/credits",token)
  endpoint %>% httr::GET() %>%
    httr::content(as="text") %>%
    jsonlite::fromJSON(flatten=TRUE) %>% {.[["tokenUsage"]][[1]]} %>% as.integer()
}

#' Get symbol from instrument ISIN
#'
#' @param isin 12 digit alphanumeric international securities identification number
#'
#' @return A tibble consisting of all symbols, regions and exchanges for the instrument
#' @export
#' @importFrom httr GET content
#' @importFrom jsonlite fromJSON
#' @importFrom dplyr select
#' @importFrom tibble as_tibble
#' @importFrom magrittr %>%
#' @examples
#' \dontrun{
#' apikey("your_key")
#' symbols_by_isin("US67066G1040")
#' }
symbols_by_isin <- function(isin){
  token <- paste0("token=",apikey())
  endpoint <- paste0(getOption("iex_api"),"/ref-data/isin?isin=",isin,"&",token)
  jsonlite::fromJSON(httr::content(httr::GET(endpoint),as="text"),flatten=TRUE) %>% tibble::as_tibble() %>%
    dplyr::select(.data$symbol,.data$region,.data$exchange)
}

#' Available exchanges
#'
#' @return A tibble of all exchanges available at IEX cloud,
#'         with exchange code, region, description, mic and suffix.
#' @export
#' @importFrom httr GET content
#' @importFrom jsonlite fromJSON
#' @importFrom tibble as_tibble
#' @importFrom magrittr %>%
#' @examples
#' \dontrun{
#' api_key("your_key")
#' exchanges()
#' }
exchanges <- function(){
  token <- paste0("token=",apikey())
  endpoint <- paste0(getOption("iex_api"),"/ref-data/exchanges?",token)
  jsonlite::fromJSON(httr::content(httr::GET(endpoint),as="text"),flatten=TRUE) %>%
    tibble::as_tibble()
}

#' All available symbols at an exchange
#'
#' @param iex_exchange_code IEX exchange code
#' @param market_identifier_code MIC according to ISO 10383, supersedes `iex_exchange`
#'
#' @description  asdf
#'
#' @return A tibble of all available symbols at the specified exchange. Notable fields are `symbol` and `name`.
#' @references See https://iexcloud.io/docs/api/#international-symbols
#' @export
#' @importFrom httr GET content
#' @importFrom jsonlite fromJSON
#' @importFrom tibble as_tibble
#' @importFrom magrittr %>%
#'
#' @examples
#' \dontrun{
#' apikey("your_key")
#' symbols_by_exchange(market_identifier_code = "XETR")}
symbols_by_exchange <- function(iex_exchange_code,market_identifier_code){
  if (!missing(market_identifier_code)){
    iex_exchange_code <- exchanges() %>%
      dplyr::filter(.data$mic==market_identifier_code) %>% {.[["exchange"]]}
  }
  token <- paste0("token=",apikey())
  endpoint <- paste0(getOption("iex_api"),"/ref-data/exchange/",
                     iex_exchange_code,"/symbols?",token)
  jsonlite::fromJSON(httr::content(httr::GET(endpoint),as="text"),flatten=TRUE) %>%
    tibble::as_tibble()
}

#' Batch download (un-)adjusted OHLC prices and volume data in large chunks.
#'
#' @description Using the IEX cloud `batch` endpoint, this function pulls data
#' based on the `chart` endpoint's `range`argument which offers ranges in
#' 5d, 1m, 3m, 6m, 1y, 2y, 5y, max. This is fast, but can be expensive. Use
#' \code{\link{prices}} for a more granular (and slower) download.
#' @seealso prices
#'
#' @param symbols Vector of IEX symbols. Length must be < 1000
#' @param start_date Optional start date. Defaults to the last trading month.
#' @param exact If set to `TRUE`, only the `start_date` is queried.
#' @references See \href{https://iexcloud.io/docs/api/}{IEX api documentation}
#'
#' @return A tibble with daily adjusted OHLC and unadjusted close data as well
#'         as volume.
#' @export
#' @importFrom purrr map_dfr
#' @importFrom httr GET content
#' @importFrom jsonlite fromJSON
#' @importFrom dplyr select mutate filter
#' @importFrom tibble as_tibble tibble
#' @importFrom magrittr %>%
#' @examples
#' \dontrun{
#' apikey("your_api_key")
#' prices_batch(c("AAPL","AMZN"),start_date = Sys.Date() - 10)
#' }
prices_batch <- function(symbols, start_date,exact=FALSE){
  if (length(symbols)>100){stop("IEX cloud API supports only 100 parallel symbols.")}
  token <- paste0("token=",apikey())
  symbols <- paste0(symbols,collapse = ",")
  range <- ""
  edate <- ""
  if (exact){
    edate <- paste0("&exactDate=",format(as.Date(start_date),"%Y%m%d"),"&chartByDay=true")
  }

  if (missing(start_date)){
    start_date <- as.Date("2000-01-01")
    range <- "1m"
  } else {
    ranges <- list(max  = "-30 year",`5y` = "-5 year",`2y` = "-2 year",
                   `1y` = "-1 year",`6m` = "-6 month",`3m` = "-3 month",
                   `1m` = "-1 month", `5d` = "-5 day")
    range_bounds <- as.Date(sapply(ranges,function(x){
      seq.Date(Sys.Date(),by=x,length.out=2)[2]}),origin="1970-01-01")
    range <- paste0(names(ranges)[max(which(range_bounds<=start_date))])
  }

  endpoint <- paste0(getOption("iex_api"),"/stock/market/batch?symbols=",symbols,
                       "&types=chart&range=",range,edate,"&",token)

  result <- jsonlite::fromJSON(httr::content(httr::GET(endpoint),as="text"),flatten=TRUE)
  eRow <- tibble::tibble(symbol=as.character(NULL),
                         date=as.Date(NA),
                         open=numeric(),
                         high=numeric(),
                         low=numeric(),
                         close=numeric(),
                         aClose=numeric(),
                         fClose=numeric(),
                         volume=numeric())
  purrr::map_dfr(names(result),function(symbol){
    if (length(result[[symbol]][["chart"]])>0){
      result[[symbol]][["chart"]] %>%
        tibble::as_tibble() %>%
        dplyr::mutate(symbol=symbol,
                      date = as.Date(.data$date),
                      volume=as.integer(.data$volume)) %>%
        dplyr::select(.data$symbol,
                      .data$date,
                      open   = .data$uOpen,
                      high   = .data$uHigh,
                      low    = .data$uLow,
                      close  = .data$uClose,
                      aClose = .data$close,
                      fClose = .data$fClose,
                      .data$volume) %>%
        dplyr::filter(.data$date >= start_date)
    } else {eRow}
  })
}

#' Batch download (un-)adjusted OHLC prices and volume data in daily chunks.
#'
#' @description Using the IEX cloud `batch` endpoint, this function pulls data
#' based on the `chart` endpoint's `chartByDay`argument which offers a granular,
#' day-based download. This is slow, but can be less expensive than the `range`
#' mode in \code{\link{prices_batch}}.
#' @seealso prices_batch
#'
#' @param symbols Vector of IEX symbols. Length must be < 1000
#' @param start_date Optional start date. Defaults to the last trading month.
#' @param end_date Optional end date. Defaults to today.
#'
#' @references See \href{https://iexcloud.io/docs/api/}{IEX api documentation}
#'
#' @return A tibble with daily adjusted OHLC and unadjusted close data as well
#'         as volume.
#' @export
#' @importFrom purrr map_dfr
#' @importFrom httr GET content
#' @importFrom jsonlite fromJSON
#' @importFrom dplyr select mutate filter
#' @importFrom tibble as_tibble tibble
#' @importFrom magrittr %>%
#' @examples
#' \dontrun{
#' apikey("your_api_key")
#' prices(c("AAPL","AMZN"),start_date = "2021-01-01",end_date="2021-01-06")
#' }
prices <- function(symbols, start_date,end_date){
  if (length(symbols)>100){stop("IEX cloud API supports only 100 parallel symbols.")}
  if (missing(start_date)){start_date <- seq.Date( Sys.Date(), length.out = 2, by='-1 months' )[2]}
  if (missing(end_date)){end_date <- Sys.Date()}
  symbols <- paste0(symbols,collapse = ",")
  dates <- seq.Date(as.Date(start_date),as.Date(end_date),by="1 day") %>% format("%Y%m%d")
  token <- paste0("token=",apikey())

  res <- purrr::map_dfr(dates,function(dt){
    endpoint <- paste0(getOption("iex_api"),"/stock/market/batch?symbols=",symbols,
                       "&types=chart&range=1d","&exactDate=",dt,"&chartByDay=true","&",token)
    result <- jsonlite::fromJSON(httr::content(httr::GET(endpoint),as="text"),flatten=TRUE)
    purrr::map_dfr(names(result),function(symbol){
      if (length(result[[symbol]][["chart"]])>0){
        result[[symbol]][["chart"]] %>%
          tibble::as_tibble() %>%
          dplyr::mutate(symbol=symbol,
                        date = as.Date(.data$date),
                        volume=as.integer(.data$volume)) %>%
          dplyr::select(.data$symbol,
                        .data$date,
                        open   = .data$uOpen,
                        high   = .data$uHigh,
                        low    = .data$uLow,
                        close  = .data$uClose,
                        aClose = .data$close,
                        fClose = .data$fClose,
                        .data$volume)
      }})})
  if (nrow(res)==0){tibble::tibble(
    symbol=as.character(),date=as.Date(NA),open=numeric(),high=numeric(),low=numeric(),close=numeric(),aClose=numeric(),fClose=numeric(),volume=numeric())
  } else {res%>% dplyr::arrange(symbol,date)}
}




#' Batch download daily historical exchange rates.
#'
#' @description Using the IEX cloud `batch` endpoint, this function pulls data
#' based on the `chart` endpoint's `chartByDay`argument which offers a granular,
#' day-based download. This is slow, but can be less expensive than the `range`
#' mode in \code{\link{prices_batch}}.
#' @seealso prices_batch
#'
#' @param symbol The company's symbol. Preferably from the company's leading exchange.
#'
#' @return A list with company information
#' @export
#' @importFrom magrittr %>%
#' @importFrom httr GET content
#' @importFrom jsonlite fromJSON
#' @examples \dontrun{
#' company_info('AAPL')}
company_info <- function(symbol){
  token <- paste0("?token=",getOption("iex_api_key"))
  endpoint <- paste0(getOption("iex_api"),"/stock/",symbol,"/company",token)
  endpoint %>% httr::GET() %>%
    httr::content(as="text") %>%
    jsonlite::fromJSON(flatten=TRUE)
}

#' Batch download exchange rates
#'
#' @param symbols list of ISO 4217 currency exchange rate pairs, e.g. EURUSD. First
#' symbol is base currency, second is quote currency.

#' @param start_date Optional start date, defaults to yesterday.
#' @param end_date Optional end date, defaults to yesterday..
#'
#' @return Returns a tibble with date, symbol, rate.
#' @export
#'
#' @importFrom purrr map_dfr
#' @importFrom httr GET content
#' @importFrom jsonlite fromJSON
#' @importFrom dplyr select mutate filter group_by slice_max ungroup
#' @importFrom tidyr drop_na
#' @importFrom tibble as_tibble
#' @importFrom magrittr %>% %<>%
#' @importFrom purrr reduce
#'
#' @examples
exchange_rates <- function(symbols, start_date,end_date){
  token <- paste0("&token=",getOption("iex_api_key"))
  if (missing(start_date)){start_date <- Sys.Date() - 1}
  if (missing(end_date)){end_date <- Sys.Date()-1}
  symbols %<>% paste0(collapse = ",")
  start_date <- format(as.Date(start_date), format("%Y-%m-%d"))
  end_date <- format(as.Date(end_date), format("%Y-%m-%d"))
  endpoint <- paste0(getOption("iex_api"),"/fx/historical?symbols=",symbols,
                     "&from=",start_date,"&to=",end_date,token)
  endpoint %>% httr::GET() %>%
    httr::content(as="text") %>%
    jsonlite::fromJSON(flatten=TRUE) %>%
    purrr::reduce(dplyr::bind_rows) %>%
    tibble::as_tibble() %>%
    dplyr::group_by(.data$date,.data$symbol) %>%
      dplyr::slice_max(.data$timestamp,n=1) %>%
    dplyr::ungroup() %>%
    dplyr::select(.data$date,.data$symbol, .data$rate) %>%
    tidyr::drop_na()
}