Package com.jimmoores.quandl

The core Quandl wrapper classes

See: Description

Class Summary

Class	Description
DataSetRequest	Class for a tabular data set request to Quandl.
DataSetRequest.Builder	Inner builder class.
HeaderDefinition	The definition of the names of columns in a Row.
MetaDataRequest	A class that packages the request for MetaData from Quandl.
MetaDataResult	Class to hold meta-data for a single Quandl code.
MultiDataSetRequest	Builder class for a tabular data set request to Quandl.
MultiDataSetRequest.Builder	Inner builder class.
MultiMetaDataRequest	A class that packages the request for MetaData from Quandl.
QuandlCodeRequest	Class for representing a request for either a single column for a given Quandl code, or a request for all columns for a given Quandl code.
QuandlSession	Quandl session class.
RetryPolicy	Class containing multiple retry policies.
Row	Class to represent a single Row of data.
SearchRequest	A class that packages the request for search query from Quandl.
SearchRequest.Builder	Builder for this class.
SearchResult	Class to hold meta-data for a single Quandl code.
SessionOptions	Class for specifying any non-trivial options to a QuandlSession.
SessionOptions.Builder	Internal Builder class.
TabularResult	Represents a result in tabular form.

Enum Summary

Enum	Description
Frequency	Enumerated type representing the frequency of data being requested.
SortOrder	An enumerated type representing the required result ordering from a Quandl REST API request.
Transform	Enumerated type to represent a server-side pre-processing transformation of the source data.

Package com.jimmoores.quandl Description

The core Quandl wrapper classes

The core class is QuandlSession. This can be initialized with or without SessionOptions that specify things like the Quandl API Token (optional, but strongly recommended - they are free). The general pattern is that there is a Request and Response class. The Request class often uses the Builder pattern to allow requests to be built in a fluent style.

   QuandlSession session = QuandlSession.create();
   TabularResult tabularResult = session.getDataSet(DataSetRequest.Builder.of("WIKI/AAPL"));
   System.out.println(tabularResult.toPrettyPrintedString());
 

The types of request are:

• DataSetRequest - request tabular data set for a single Quandl code, builder has a range of optional parameters.
• MultiDataSetRequest - request tabular data across multiple Quandl codes, builder has a range of optional parameters.
• MetaDataRequest - request meta data for a single Quandl code.
• MultiMetaDataRequest - request meta data for multiple Quandl codes.
• SearchRequest - perform text-based searches, large result sets are paged.

The core methods on the session are:

• getDataSet(DataSetRequest) - request tabular data for single Quandl code.
• getDataSets(MultiDataSetRequest) - request tabular data for multiple Quandl codes/columns.
• getMetaData(MetaDataRequest) - request meta data for a single Quandl code.
• getMetaData(MultiMetaDataRequest) - request meta data for multiple Quandl codes.
• getMultipleHeaderDefinition(MultiMetaDataRequest) - request column header definitions for multiple Quandl codes.
• search(SearchRequest) - free text search on available data.

The data types returned by these methods are:

• TabularResult - made up of a HeaderDefinition and a list of Rows.
• MetaDataResult - Wrapper around JSON object returned. Contains various typed accessor methods for convenience.
• SearchResult - Wrapper around JSON object, allows easy iteration through resulting matches.

With the MetaDataResult and SearchResult the underlying raw JSON message is also available for query. Note that the multiple data set/meta data set calls return data in the same format as single requests, just with more columns and/or meta data. The only current exception is getMultipleHeaderDefinition which separates out the header information for each requested Quandl code. Future versions are intended to provide methods to split out multiple requests automatically for tabular data and search results (although for the meantime, the SearchResult class contains functionality to separate out the search documents.

Unlike the underlying Quandl REST API, you can lookup columns in a Row object using the column name as well as the index of the column. In some corner cases, duplicate column names can be returned from Quandl. In these cases, the later duplicates are renamed to 'ColumnName.1', 'ColumnName.2', and so on. This allows the consistent use of column names for lookup.

Gotchas and points of note

• It's common with the builder pattern to forget to call build() and be stumped as to why your IDE won't let you pass your request.
• Using column indices of less than 1 leads to unpredictable behavior.
• Search result page size is currently limited to 100 by Quandl.
• Search results with a high current page can be slow.
• Some requests throw unusual exceptions (e.g. QuandlUnprocessableEntityException, QuandlTooManyRequestsException. It's suggested all session calls should handle QuandlRuntimeException and it's sub-classes.
• Most of the data objects have toPrettyPrintedString() which produce nice output. These call into the PrettyPrinter class, which can also handle Map<String, HeaderDefinition>.
• Comparing meta data objects may be slower than you might expect because the underlying JSON library doesn't implement equals() or hashCode(). The workaround is to call equals() and hashCode() on the toString() output.
• The getMetaData(MultiMetaDataRequest) method is not especially useful as the only metadata returned for each request are the column names. This is why it's almost always more convenient to use getMultipleHeaderDefinition(MultiMetaDataRequest).