README.md

In ClaytonJY/tidyquandl: A tidy interface to financial data via Quandl.com

tidyquandl

The goal of tidyquandl is to be an easy-to-use and tidy interface to the Quandl API for financial data.

Core features:

• focuses on the Tables API (the good one)
• returns tibbles (except for metadata)
• always fetches all results (paginate = TRUE in Quandl)
• automatically retries failed queries
• automatically splits large queries into manageable ones (batching)
• uses readr::read_csv() for speed and type inference
• well-formatted errors

This is not the only way to interact with Quandl from R; Quandl themselves maintain a Quandl R package which covers a wider set of uses than tidyquandl (like the Timeseries API), but supports none of the above features. An earlier version of this package wrapped the Quandl one, but as of v0.1.2 the underlying code has been rewritten from scratch.

Installation

You can install the release and development versions from GitHub wih the devtools package:

# install.packages("devtools")

# latest release
devtools::install_github("claytonjy/tidyquandl@*release")

# latest development version
devtools::install_github("claytonjy/tidyquandl")

I recommend using the release version in general, but be sure to install the development version when filing bugs and pull requests.

Usage

Before doing anything with the Quandl API, you'll need an account; you can register for free at Quandl, and all examples use free datasets available to all registered users.

Then you need to obtain your API key (a string) from your account settings. Storing this in an environment variable named QUANDL_API_KEY is easiest (e.g. via .Renviron), though isn't strictly necessary.

# ~/.Renviron
QUANDL_API_KEY=my-ap1k3y

Then we read that in via quandl_key_set().

library(tidyquandl)

quandl_key_set()  # can also pass key to this as argument

Now we can call quandl_datatable() to interact with the Tables API. Here we use the Wiki Prices database to get one day of prices on Apple and Microsoft:

quandl_datatable("WIKI/PRICES", ticker = c("AAPL", "MSFT"), date = "2018-01-02")
#> # A tibble: 2 x 14
#>   ticker date        open  high   low close   volume `ex-dividend`
#>   <chr>  <date>     <dbl> <dbl> <dbl> <dbl>    <dbl>         <dbl>
#> 1 AAPL   2018-01-02 170.  172.  169.  172.  25048048             0
#> 2 MSFT   2018-01-02  86.1  86.3  85.5  86.0 21993101             0
#> # ... with 6 more variables: split_ratio <dbl>, adj_open <dbl>,
#> #   adj_high <dbl>, adj_low <dbl>, adj_close <dbl>, adj_volume <dbl>

Unlike Quandl::Quandl.datatable, if an error is received (HTTP response 400+) the query will be retried automatically up to three times. It can also accept an unlimited number of tickers: behind the scenes, multiple queries will be made to avoid errors from passing Quandl too many parameters.

You can pass in any of the arguments you're used to passing into Quandl::Quandl.datatable via the ... args. Here we get only the closing prices for Apple over the span of two weeks.

quandl_datatable(
  "WIKI/PRICES",
  ticker = "AAPL",
  date.gte = "2018-01-01", date.lt = "2018-01-15",
  qopts.columns = c("ticker", "date", "close")
)
#> # A tibble: 9 x 3
#>   ticker date       close
#>   <chr>  <date>     <dbl>
#> 1 AAPL   2018-01-02  172.
#> 2 AAPL   2018-01-03  172.
#> 3 AAPL   2018-01-04  173.
#> 4 AAPL   2018-01-05  175 
#> 5 AAPL   2018-01-08  174.
#> 6 AAPL   2018-01-09  174.
#> 7 AAPL   2018-01-10  174.
#> 8 AAPL   2018-01-11  175.
#> 9 AAPL   2018-01-12  177.

You can also use tidyquandl to fetch metadata about a table.

quandl_datatable_meta("WIKI/PRICES")
#> $vendor_code
#> [1] "WIKI"
#> 
#> $datatable_code
#> [1] "PRICES"
#> 
#> $name
#> [1] "Quandl End of Day Stocks Info"
#> 
#> $description
#> NULL
#> 
#> $columns
#>           name              type
#> 1       ticker            String
#> 2         date              Date
#> 3         open BigDecimal(34,12)
#> 4         high BigDecimal(34,12)
#> 5          low BigDecimal(34,12)
#> 6        close BigDecimal(34,12)
#> 7       volume BigDecimal(37,15)
#> 8  ex-dividend BigDecimal(42,20)
#> 9  split_ratio            double
#> 10    adj_open BigDecimal(50,28)
#> 11    adj_high BigDecimal(50,28)
#> 12     adj_low BigDecimal(50,28)
#> 13   adj_close BigDecimal(50,28)
#> 14  adj_volume            double
#> 
#> $filters
#> [1] "ticker" "date"  
#> 
#> $primary_key
#> [1] "ticker" "date"  
#> 
#> $premium
#> NULL
#> 
#> $status
#> $status$refreshed_at
#> [1] "2018-03-27T23:54:20.000Z"
#> 
#> $status$status
#> [1] "ON TIME"
#> 
#> $status$expected_at
#> [1] "*"
#> 
#> $status$update_frequency
#> [1] "CONTINUOUS"

Unlike quandl_datatable() this returns a list rather than a tibble. This can also be used on any table, including premium tables you haven't paid for, which can be helpful to evaluate their usefullness beyond what you see in the documentation.

Roadmap

The next big changes will be to allow for more readr-like control of types (issues #22, #27) and to improve documentation by making a pkgdown site (#9) and a vignette comparing this to the Quandl package more directly (#28).

Contributing

Your contributions are welcome! Issues, typo fixes, new functions, anything. See .github/CONTRIBUTING.md for more information.

To test & check you'll need to store your key in the QUANDL_API_KEY variable. I recommend creating an .Renviron file in this directory.

Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.

ClaytonJY/tidyquandl documentation built on May 3, 2019, 4:02 p.m.