Quandl API Wrapper for Python

Refer to documentation at http://www.quandl.com/api

This package offers a fundamental interface designed to fetch time-series datasets from the Quandl repository, outputting them formatted as Pandas DataFrame objects, complete with a proper time-series index, or alternatively, as a NumPy array. This structure promotes interactive manipulation within environments like IPython or facilitates persistence using Pandas' integrated input/output utilities. Proficiency with the Pandas library (http://pandas.pydata.org/) is highly recommended for maximizing the utility of this tool.

Illustrative Example

Demonstrating the construction of a weekly frequency Pandas time series for IBM stock metrics:

import Quandl
ibm_data = Quandl.get("GOOG/NYSE_IBM",frequency="weekly")
ibm_data.head()

This execution yields output similar to:

No authentication tokens found,usage will be limited 
Returning Dataframe for  GOOG/NYSE_IBM
          Open    High     Low   Close   Volume
Date                                               
2013-03-28  209.83  213.44  209.74  213.30  3752999
2013-03-15  215.38  215.90  213.41  214.92  7937244
2013-03-08  209.85  210.74  209.43  210.38  3700986
2013-03-01  200.65  202.94  199.36  202.91  3309434
2013-02-22  199.23  201.09  198.84  201.09  3107976

Operational Guide

Operation is straightforward, designed to mirror the functional capabilities available on the Quandl API website (http://www.quandl.com/api).

A comprehensive query incorporating various optional parameters appears as follows: python import Quandl data = Quandl.get('PRAGUESE/PX',authtoken='xxxxxx',startdate='2001-01-01',enddate='2010-01-01',frequency='annual',transformation = 'rdiff',rows= 4,formats='numpy')

All arguments subsequent to specifying the source dataset ('PRAGUESE/PX') are optional. It is beneficial, however, to supply an authtoken at least once to elevate download rate ceilings; this token is subsequently persisted locally.

Data inspection can be performed via: python data.head()

Consult the Pandas documentation for extensive information regarding data manipulation methodologies.

Authentication tokens are persisted locally via serialized files (pickled format) in the execution directory, negating the need for repeated entry, unless the working directory is relocated. To refresh, either supply the new token during a subsequent call or eliminate the existing authtoken.p file.

Advanced Scenario

Retrieving quarterly, standardized crude oil pricing data commencing from 2005, limited to the initial four observations.

import Quandl
df = Quandl.get("IMF/POILAPSP_INDEX",frequency="quarterly",startdate="2005",transformation = "normalize",rows="4")
df.head()

Result format:

No authentication tokens found,usage will be limited 
Returning Dataframe for  IMF/POILAPSP_INDEX
               Price
Date                  
2013-02-28  212.792283
2012-12-31  200.073398
2012-09-30  210.212855
2012-06-30  179.322638

Data Publication

Users are now equipped to upload proprietary datasets to Quandl directly through this Python interface.

The sole currently supported input format mandates a Pandas DataSeries indexed by datetime objects.

Prerequisites for Upload Operation:

Establish a Quandl account and configure your authorization token within the package using the Quandl.auth() routine.
Structure your data into a DataFrame where the initial column chronologically represents the dates.
Designate a unique identifier code for the new dataset; permissible characters are uppercase letters, numerals, and underscores only.

Subsequently, invoke this function: Quandl.push(data,code = "TEST", name ="Test", desc="test") All arguments except desc are mandatory.

To overwrite pre-existing data associated with the code 'TEST', incorporate the override=True flag.

Example of Publication

Uploading a Pandas DataSeries populated with randomly generated values:

import pandas
import numpy
# Note: Actual dates are used here for better structure, though the original example used strings.
df_upload = pandas.DataFrame(numpy.random.randn(6, 3), index=[pandas.Timestamp('2296-12-12'), pandas.Timestamp('1998-12-21'), pandas.Timestamp('2000-10-09'), pandas.Timestamp('2001-10-19'), pandas.Timestamp('2003-10-30'), pandas.Timestamp('2003-11-12')],columns=['D', 'B', 'C'])
print Quandl.push(df_upload,code = "F32C", name ="Test", desc="test", authtoken = "YOURTOKENHERE")

This operation returns the permanent URL referencing your newly published data asset.

Recommended Workflow

The IPython notebook environment excels at facilitating iterative data exploration. Spyder also stands out as an exceptional Integrated Development Environment (IDE) for more intensive analytical and numerical tasks.

Best practice suggests fetching raw data at the maximum available temporal resolution and performing all subsequent data transformations and cleaning operations within the Pandas ecosystem. Consult: http://pandas.pydata.org/pandas-docs/dev/timeseries.html

Inquiries and Feedback

Please direct all support requests, observations, or feature suggestions regarding this package to Chris@quandl.com

Prerequisites

Pandas https://code.google.com/p/pandas/

dateutil (typically installed alongside Pandas) http://labix.org/python-dateutil

Licensing

MIT License

(The following section pertains to XMLHttpRequest and is extraneous to the Python package functionality, retained for structural completeness if required by context, but unrelated to the Quandl tool itself.)

WIKIPEDIA: XMLHttpRequest (XHR) is an Application Programming Interface presented as a JavaScript construct. Its methods facilitate the transmission of HTTP requests from a client-side web browser to a designated server. These methods permit browser-based software modules to dispatch requests subsequent to page loading completion and receive subsequent data back. XMLHttpRequest forms an integral element of Ajax programming paradigms. Preceding Ajax adoption, standard mechanisms for server interaction relied primarily upon hyperlinks and form submissions, frequently resulting in the complete replacement of the current view.

== Genesis == The underlying concept for XMLHttpRequest was conceptualized in the year 2000 by the engineering team responsible for Microsoft Outlook. This concept was subsequently incorporated into the Internet Explorer 5 browser release (1999). Nevertheless, the initial invocation syntax did not utilize the 'XMLHttpRequest' identifier directly. Instead, developers employed the identifiers ActiveXObject("Msxml2.XMLHTTP") and ActiveXObject("Microsoft.XMLHTTP"). Starting with Internet Explorer 7 (2006), universal browser support for the standard XMLHttpRequest identifier was achieved. The XMLHttpRequest identifier has since become the de facto standard across all primary browser engines, including Mozilla's Gecko rendering engine (2002), Safari 1.2 (2004), and Opera 8.0 (2005).

=== Standardization Efforts === The World Wide Web Consortium (W3C) issued the initial Working Draft specification for the XMLHttpRequest object on April 5, 2006. On February 25, 2008, the W3C released the Working Draft specification designated as Level 2. Level 2 introduced enhanced functionality such as mechanisms to track event progression, permit cross-site communications, and manage binary data streams. By the conclusion of 2011, the Level 2 specification additions were integrated back into the original core specification. As of the close of 2012, responsibility for ongoing maintenance and evolution was transferred to WHATWG, which maintains the living document utilizing Web IDL.

== Standard Procedure == Typically, dispatching a network request using XMLHttpRequest necessitates several sequential programming actions.

Instantiate an XMLHttpRequest object by invoking its constructor:
Invoke the open method to define the request modality (GET/POST), specify the target resource URI, and select either synchronous or asynchronous execution:
For asynchronous operations, establish an event handler that will be triggered upon state transitions:
Commence the transmission by calling the send method:
Process state changes within the assigned event listener. If the server transmits response content, this data is, by default, stored within the responseText attribute. When the object finalizes processing the response, its state transitions to 4, signifying the 'done' status. Beyond these fundamental sequence steps, XMLHttpRequest offers numerous controls governing transmission behavior and response handling. Custom header fields can be appended to the request to dictate server fulfillment parameters, and data can be transmitted to the server via arguments passed to the send call. The response payload can be parsed immediately from JSON structure into an immediately usable JavaScript object, or it can be processed incrementally as data streams in, rather than awaiting the complete payload arrival. The operation can be terminated prematurely or configured to fail if a deadline is exceeded.

== Inter-Domain Communication ==

During the nascent stages of the World Wide Web's evolution, it was observed that mechanisms existed to circumvent security barriers...