Quandl4J : A Quandl library for Java

NEWS: 2.1.1 security update

Bumped the version of Jersey to address security vulnerability in the Jersey library. More information can be found here. Also corrected minor documentation typos.

NEWS: 2.1.0 dependency updates

This is a fairly minor release that bumps the version of various dependencies, adds support for GitHub Actions builds, and fixes changes to TravisCI that brokes builds due to Oracle license changes.

NEWS: 2.0.0 released

The 2.0.0 release represents a substantial rewrite to allow the use of alternative types to hold tabular and meta-data. The initial implementations are classic and tablesaw. Classic refers to the previous 1.x API's use of json.org's JSONObject type for metadata and the home-grown TabularResult type for tabular data. Tablesaw is new project build around an in-memory table implementation in the same vein as TabularResult, but taken much, much further, by allowing fast querying and filtering of the in-memory column store, fast import/export, charting and so on. Many thanks to Ben McCann for his suggestions and pull-requests, which kicked off development of 2.0.0.

More details can be found in the release notes.

Introduction

Quandl is a source of millions of free data sets covering financial, economic, sociological and country data via an open REST API. Quandl4j is a Java 7+ client-side wrapper for this API provided under the commercially friendly Apache V2 license. It provides a type safe and fluent API in a modern style that takes care of constructing URLs and processing JSON and CSV responses but nonetheless allows access to all the functionality of the underlying REST API.

Quandl4J uses GitHub Actions to perform continuous builds. The current status is

Quick start
Design Principles
Release Notes
Classic Tutorial
TableSaw Tutorial
2.0.0 Migration Guide
Documentation
Roadmap
Contributions
Community
Versioning
Creator
Copyright and license
Gradle

Quick Start

The minimum pre-requisites are:

OpenJDK 7, Oracle JDK 7 & 8 are tested. The 2.0.0 release is the last major release that will support Java 7.
Maven 3.

Four options are available:

Download the latest release
Clone the repository: git clone https://github.com/jimmoores/quandl4j.git
- Run mvn install to build the libray, test, javadoc and source jars and install to your local Maven repository.
- Run mvn javadoc:javadoc to build the documentation.
Add the following fragment to your Maven POM file

<dependency>
  <groupId>com.jimmoores</groupId>
  <artifactId>quandl-core</artifactId>
  <version>2.1.1</version>
</dependency>

and if you want to use the new tablesaw support:

<dependency>
  <groupId>com.jimmoores</groupId>
  <artifactId>quandl-tablesaw</artifactId>
  <version>2.1.1</version>
</dependency>

or in gradle

dependencies {
    compile 'com.jimmoores:quandl-core:2.1.1'
}

and add

compile 'com.jimmoores:quandl-tablesaw:2.1.1'

to your dependencies section if you want tablesaw support.

Design Principles

The core design principles are:

Allow full access to the functionality of the underlying API.
Allow efficient network requests by using the more compact CSV encoding where possible.
Use modern Java design principles like immutable objects, builders and factories and JSR-310 style date/times (using the ThreeTen backport so Java 7 is supported)
Thorough unit and integration test support, including a framework that can be reused by user applications without hitting the Quandl backend.
Publish maven artifacts on Maven Central.
Provide concrete examples.
Provide comprehensive documentation and JavaDocs.

Release Notes

Version 2.1.1

Patch for security vulnerability in dependent library.

Version 2.1.0

This is a fairly minor release that bumps the version of various dependencies, adds support for GitHub Actions builds, and fixes changes to TravisCI that brokes builds due to Oracle license changes.

Version 2.0.0

A fairly comprehensive overhaul. The primary aim was to allow the use of alternative types to hold tabular and metadata. A common user question has been around the choice of JSON or Table representation, and these are now abstracted in a way that allows you to choose types that best suit your application, and even add your own very easily. This version is fully source compatible with previous versions, although most existing session classes and interfaces have been deprecated. Updating existing code is very simple, see the 2.0.0 migration guide for more information.

Version 1.5.0

Calls upgraded to use V3 of the REST API for both data and metadata. No API changes. Logback is removed as a normal dependency to allow users to choose their own implementation of SLF4J (which is the whole point of SLF4J!). If you have any build issues try adding logback to your own pom.xml. Examples are moved to test packages and commons-cli dependency is now only a dependency for test scope. Docs and contributors list updated.

Version 1.4.2

This is a little tweak release, user William Farrugia suggested updating the version of Jackson used so it can be used with AWS.

Version 1.4.1

This is a bug fix release, @Olivier-92 reported a resource leak that affects those using RESTEasy as a JAX-RS provider. The request objects are now closed as required.

Version 1.4.0

POM references to external OpenGamma Maven repository have been removed and the JSON library referred to has been switched for Jackson using the json.org datatype module. This should require no code changes in users outside of perhaps a POM change if you've referred to the OpenGamma POM in your POM.

Version 1.3.0

SearchRequest now supports the v3 API databasecode argument and makes the query parameter (previous of()) optional. This means the of() static factory method is now deprecated in favor of a no-arg constructor.

SearchRequest.Builder.of(<query>).build();

becomes

new SearchRequest.Builder().withQuery(<query>).build();

Version 1.2.0

Changed HTTPS URL because RESTEasy and Apache CXF can't handle redirect to https://www.quandl.com which is the address in the TLS certificate. Disabled integration test from main build because test framework misbehaving.

Version 1.1.0

Switch to HTTPS, regenerate test data.

Version 1.0.0

Handle deprecation of all multi-request APIs. This release emulates the old behaviour of the multiset APIs by issuing multiple single requests and aggregating results into the same structure as returned before. This should allow existing applications to adjust seamlessly, abeit probably at reduced performance. Please note though, that these APIs are now deprecated and you should plan for their eventual removal.
High loads on the Quandl servers have lead to an increase in the number of requests that return errors asking the client to throttle requests apart from when user maximum request counts are exceeded. The QuandlSession will now retry requests that are likely to be transient (503 Service Unavailable and 429 Too Many Requests) according to a RetryPolicy that can be set in the SessionOptions. The default is to back off for 1, 5, 20 and then 60 seconds and then give up. Custom policies can be put in place by subclassing RetryPolicy. Some examples are available via factory methods on
RetryPolicy.
Emulated multiset queries (both Tabular and Metadata) now return Quandl codes of the form PROVIDER/CODE rather than PROVIDER.CODE. This was only noticed after release. If this causes big problems for you, please open a ticket and I will provide the facility to revert to the old behaviour in a new release.
The new retry behaviour means that there are times that would previously have thrown a generic QuandlRuntimeException will now return QuandlFailedRequestException (which is thrown after receiving multiple
QuandlTooManyRequestsException or QuandlServiceUnavailableException). Note that previously a bug prevented the correct throwing of QuandlTooManyRequestsException.
To revert as closely as possible to the old behaviour (turn off retries), use RetryPolicy.createNoRetryPolicy() and set in the SessionOptions.
getMetaData(final MultiMetaDataRequest request) does it's best to emulate the JSON response from Quandl, but may be have fields like Frequency set to null rather than values that Quandl returned.
A missing dependency for Java 7 users has been added that allows the examples to run cleanly.
Test files were regenerated.

Version 0.9.0

Skipped because it was used internally by the author in a private Maven repository for an intermediate version and never curated for Maven Central.

Version 0.8.1

Fixed some POM issues.

Version 0.8.0

Initial public release.

Tutorial

Since 2.0.0, you can choose the types used to return data from a session by using the appropriate sess

Quandl4j

Install / Use

README