quandl-api-0.2.1.0: Quandl.com API library

Copyright(c) 2014 Peter van den Brand
LicenseBSD3
MaintainerPeter van den Brand <peter@vdbrand.nl>
Stabilityexperimental
Portabilityportable
Safe HaskellNone
LanguageHaskell98

Data.Quandl

Contents

Description

This library provides an easy way to download data from Quandl.com. See http://www.quandl.com/help/api for detailed information on the Quandl API.

For basic usage, see the getTable function. This function is all you need to download tables.

For more advanced usage, see the getTableWith function. This function allows you to use query a subset of the data, query multiple tables (multisets), apply frequency conversions, and apply transformations supported by Quandl.

Synopsis

Download a whole table at once

getTable Source

Arguments

:: String

Quandl code for the source

-> String

Quandl code for the table

-> Maybe String

Auth code

-> IO (Maybe Dataset)

Dataset returned by Quandl, or Nothing if parsing failed

Download all rows and columns from a single table. To get all data points for the dataset FRED/GDP:

getTable "FRED" "GDP" Nothing

Registered users should include their auth_token, like this:

getTable "FRED" "GDP" (Just "dsahFHUiewjjd")

Download using API parameters

defaultOptions :: Options Source

Default options to use for Quandl API calls. The default options do not use an auth token and will return all rows in descending order.

getTableWith Source

Arguments

:: Options

API parameters

-> [(String, String, Maybe Int)]

List of (source, table, column) items to retrieve. Nothing retrieves all columns.

-> IO (Maybe Dataset)

Dataset returned by Quandl, or Nothing if parsing failed

Download data from Quandl using the full API. This function supports all data manipulation options, plus downloading from multiple datasets (multisets).

For example, here is the annual percentage return for AAPL stock over the previous decade, in ascending date order:

import Data.Quandl
import Data.Time (fromGregorian)
getTableWith (defaultOptions {opSortAscending  = True, 
                              opStartDate      = Just (fromGregorian 2000 1 1), 
                              opEndDate        = Just (fromGregorian 2010 1 1), 
                              opFrequency      = Just Annual, 
                              opTransformation = Just RDiff})
             [("WIKI", "AAPL", Just 4)]  -- Just 4 means we only want the 4'th column (Close price)

You can pull data from multiple datasets (or from multiple columns in a single dataset) using this function as well. In the example below, we combine US GDP from FRED/GDP, crude oil spot prices from DOE/RWTC, and Apple closing prices from WIKI/AAPL. We are going to convert all of them to annual percentage changes, and look only at data for the last 10 years.

import Data.Quandl
getTableWith (defaultOptions {opNumRows        = Just 10,
                              opFrequency      = Just Annual,
                              opTransformation = Just RDiff})
             [("FRED", "GDP", Just 1), ("DOE", "RWTC", Just 1), ("WIKI", "AAPL", Just 4)]

Please note that Quandl does not return the table metadata when pulling data from multiple datasets. In that case the daTable field of the returned Dataset will be Nothing.

Search for a table

search Source

Arguments

:: [String]

List of search terms

-> Maybe String

Auth Token

-> Maybe Int

Number to display per page or Nothing

-> Maybe Int

Page number to display or Nothing

-> IO (Maybe SearchPage)

Search results from Quandl, or Nothing if parsing failed.

Search for terms, returning given page

Datatypes

data Options Source

API parameters supported by Quandl, for use with the getTableWith function. See http://www.quandl.com/help/api for detailed information.

Constructors

Options 

Fields

opAuthToken :: Maybe String

The Quandl Auth Token (Nothing means no token supplied, limited to 50 requests per day)

opSortAscending :: Bool

Sort results ascending or descending

opNumRows :: Maybe Int

Limits the number of returned rows (Nothing means no limit)

opStartDate :: Maybe Day

Start date of returned results (inclusive, Nothing means no restriction on start date)

opEndDate :: Maybe Day

End date of returned results (inclusive, Nothing means no restriction on end date)

opFrequency :: Maybe Frequency

Desired frequency of returned results (Nothing means frequency of original dataset)

opTransformation :: Maybe Transformation

Desired transformation of returned results (Nothing means no transformation)

opMetadataOnly :: Bool

Only return metadata, do not return any data (only works for single table queries)

data Frequency Source

Desired frequency of returned results. See http://www.quandl.com/help/api for detailed information.

Constructors

Daily 
Weekly 
Monthly 
Quarterly 
Annual 

data Transformation Source

Desired transformation of returned results. See http://www.quandl.com/help/api for detailed information.

Constructors

Diff 
RDiff 
Cumul 
Normalize 

data Dataset Source

Results from a Quandl API call.

Constructors

Dataset 

Fields

daTable :: Maybe Metadata

Metadata of the table (Nothing if fields from multiple tables are downloaded)

daColumnNames :: [Text]

The column names of the table

daData :: [[Text]]

The contents of the table

daFromDate :: Day

The starting date of the returned data (inclusive)

daToDate :: Day

The ending date of the returned data (inclusive)

daFrequency :: Text

The frequency of the returned data (daily, monthly, etc)

data Metadata Source

Metadata of a table. Only returned by Quandl when downloading from a single table.

Constructors

Metadata 

Fields

meId :: Int

Table ID

meSourceCode :: String

Source code (can be used as parameter to getTable and getTableWith)

meTableCode :: String

Table code (can be used as parameter to getTable and getTableWith)

meSourceName :: Text

Human-readable name of the source

meTableName :: Text

Human-readable name of the table

meUrlName :: Text

Urlized name of the table as used on Quandl.com

meDescription :: Text

Description of the table

meSourceUrl :: Text

URL of the original data source

meUpdatedAt :: UTCTime

Timestamp of latest update

mePrivate :: Bool

Private or public table

data SearchSource Source

Results from Search calls.

Constructors

SearchSource 

Fields

ssName :: Text

Name of the source

ssId :: Int

Source ID

ssDescription :: Text

Description of source

ssHost :: Text

Source Host site

ssDatasetsCount :: Int

count of datasets on host

ssCode :: Text

Code to use in API.

data SearchDoc Source

Constructors

SearchDoc 

Fields

sdSourceCode :: Text

Source code to use in API.

sdDisplayUrl :: Maybe Text

URL to fetch original data from.

sdPrivate :: Bool

Whether or not data is private

sdUrlizeName :: Text

Url encoded doc name.

sdName :: Text

Doc name.

sdFromDate :: Day

First date in source.

sdDescription :: Text

Description of data.

sdColumnNames :: [Text]

Names of columns in data.

sdFrequency :: Text

Frequency of updates.

sdSourceName :: Text

Name of source database.

sdUpdatedAt :: UTCTime

Time of most recent updated.

sdToDate :: Day

Last day data is available.

sdCode :: Text

Doc code to use in API.

data SearchPage Source

Constructors

SearchPage 

Fields

spTotalCount :: Int

Number of results available

spCurrentPage :: Int

Current page of results

spPerPage :: Int

Results per page

spSources :: [SearchSource]

Metadata for sources.

spDocs :: [SearchDoc]

Actual documents found.

Low-level functions

downloadJSON :: Options -> [(String, String, Maybe Int)] -> IO ByteString Source

Returns unparsed JSON from a Quandl API call.

createUrl :: Options -> [(String, String, Maybe Int)] -> String Source

Construct a URL given the various API parameter options.