Help > API

Using the Quandl API

This document is a comprehensive guide to using the Quandl API. Every single dataset on Quandl is available via our API.

Synopsis

Fast learners can infer almost everything about the API from this example:

www.quandl.com/api/v1/datasets/WIKI/AAPL.csv?sort_order=asc&exclude_headers=true&rows=3&trim_start=2012-11-01&trim_end=2013-11-30&column=4&collapse=quarterly&transformation=rdiff

Tutorials and comprehensive documentation follows.

Usage Rules

API usage is free and unlimited for registered users. (Anonymous calls are welcome, but limited to 50 requests per day.) Note: there is a "speed limit" of 5000 calls per hour.

Auth Tokens

You will need an authentication token unless you are doing less than 50 calls per day. Logged in users can find their auth_token here.

Quandl Codes

To use the API to download a dataset, you will need to know the dataset's "Quandl code".

Each dataset on Quandl has a unique Quandl code, comprising a source code and a table code. For instance, the dataset named GDP of the United States has the Quandl code FRED/GDP, where FRED is the source code and GDP is the table code. All datasets from the same source will have the same source code.

Note that table codes are not guaranteed to be unique across sources. SHFE/CUG2014 is not the same as MCX/CUG2014. Thus you need both the source code and the table code to fully identify a dataset.

A Simple Example

To get all data points for the dataset FRED/GDP in CSV format, do this call:

www.quandl.com/api/v1/datasets/FRED/GDP.csv

Registered users should include their auth_token, like this:

www.quandl.com/api/v1/datasets/FRED/GDP.csv?auth_token=dsahFHUiewjjd

(Note that the auth_token in the example above is a fake, and will not work).

In the interest of concision and code clarity, we will not include auth_tokens in the remaining examples on this page.

Data Formats

You can get data from the Quandl API in CSV, JSON, XML and HTML formats, by appending the relevant format code to your call.

Format Suffix Example
CSV .csv www.quandl.com/api/v1/datasets/FRED/GDP.csv
JSON .json www.quandl.com/api/v1/datasets/FRED/GDP.json
XML .xml www.quandl.com/api/v1/datasets/FRED/GDP.xml

Data Manipulation

Quandl allows you to perform a number of manipulations on your data, prior to download. All you have to do is append the relevant parameters to your basic API call, to get the altered data. Here is a list of available manipulations:

Sort Order

You can select the sort order by passing the parameter sort_order=asc|desc. (Notice that the | in the parameter specification separates various mutually-exclusive options). The default sort order is descending. Here is an example call, showing the spot price of crude oil from DOE/RWTC in ascending order:

http://www.quandl.com/api/v1/datasets/DOE/RWTC.csv?sort_order=asc

Headers

On CSV calls, you can exclude column headers by passing the parameter exclude_headers=true. Here is an example:

http://www.quandl.com/api/v1/datasets/DOE/RWTC.csv?exclude_headers=true

Note that this parameter will be ignored on non-CSV calls.

Date Truncation

You can use rows=n to get only the first n rows of your dataset. Use rows=1 to get the latest observation for any dataset. Here is an example:

http://www.quandl.com/api/v1/datasets/DOE/RWTC.csv?rows=1

Specific Date Range

You can download data within a specific date range, by setting start and end dates for your query. Set the start date with:

trim_start=yyyy-mm-dd

Set the end date with:

trim_end=yyyy-mm-dd

To get the Prague Stock Index data points for November 2012:

http://www.quandl.com/api/v1/datasets/PRAGUESE/PX.csv?trim_start=2012-11-01&trim_end=2012-11-30

Specific Columns

Many datasets on Quandl have multiple data columns. (For example, stock prices typically have columns for Open, High, Low, Close and Volume). You can use the API to request a specific column by passing the column=n parameter. Here is an example that gets the closing price for Apple stock:

http://www.quandl.com/api/v1/datasets/WIKI/AAPL.csv?column=4

Column 0 is the date column and is always returned. Data begins at column 1.

If you want to get more than one but less than all of the columns from a particular dataset, you will need to use the "multisets" call (described below).

Frequency

Append any basic API call with parameters to indicate the desired frequency.

collapse=none|daily|weekly|monthly|quarterly|annual

When you change the frequency of a dataset, Quandl returns the last observation for the given period. So, if you collapse a daily dataset to monthly, you will get a sample of the original dataset where the observation for each month is the last data point available for that month. Thus this transformation does not work well for datasets that measure percentage changes, period averages or period extremes (highs and lows).

To get crude oil prices on a quarterly basis from the EIA's daily spot price, do this call:

http://www.quandl.com/api/v1/datasets/DOE/RWTC.csv?collapse=quarterly

Calculations

Quandl allows you to perform certain elementary calculations on your data prior to downloading. The transformations currently availabe are row-on-row change, percentage change, cumulative sum, and normalize (set starting value at 100).

If a datapoint for time t is denoted as y[t] and the transformed data as y'[t], the available transformations are defined as below:

Transformation Parameter Effect
Row-on-row change diff y'[t] = y[t] - y[t-1]
Row-on-row % change rdiff y'[t] = (y[t] - y[t-1])/y[t-1]
Cumulative sum cumul y'[t] = y[t] +y[t-1] + ... + y[0]
Start at 100 normalize y'[t] = (y[t]/y[0]) * 100

Note that y[0] in the above table refers to the starting date for the API call, i.e., the date specified by trim_start= or rows=, NOT the starting date of the entire dataset.

Append any basic API call with parameters to indicate the desired transformation:

transformation=none|diff|rdiff|cumul|normalize

Thus to get the Canadian GDP annual percentage change, you would do the following call:

http://www.quandl.com/api/v1/datasets/FRED/CANRGDPR.csv?transformation=rdiff

A Complex Example

You can combine any of the above parameters in a single call, concatenating them using the & character. For example, here is the annual percentage return for AAPL stock over the previous decade, in ascending date order:

http://www.quandl.com/api/v1/datasets/WIKI/AAPL.csv?column=4&collapse=annual&trim_start=2000-01-01&trim_end=2010-01-01&sort_order=asc&transformation=rdiff

Note that you may need to enclose a complex API call in quotes, depending on what method you're using to make the call and whether that method has a special use for the & character. (curl is a good example of such a method.)

Multiple Datasets

You can pull data from multiple datasets (or from multiple columns in a single dataset) using our "multisets" API call.

Here is an example of a multisets call. This call combines the closing price of AAPL stock from WIKI/AAPL, and the spot price of crude oil from DOE/RWTC, in CSV format:

http://quandl.com/api/v1/multisets.csv?columns=WIKI.AAPL.4,DOE.RWTC.1

Here are some things to note about the syntax:

  • You have to replace the / in each Quandl code with a ..
  • Different Quandl codes are separated by a ',' and you can add as many codes as you like.
  • Include a number at the end of each Quandl code to specify which data columns you want from each dataset. (Omit this to get all columns.)
  • As with the basic API call, you can get multiset data in multiple formats, by using their respective format codes: .csv, .json, and .xml.

All the parameters and manipulations available for regular API calls are also available for multiset calls: auth_token, sort_order, exclude_headers, rows, trim_start, trim_end, collapse and transformation.

Please note that that this time you will be limited to 500,000 data points (rows x columns) per multiset call. Therefore it is better to do multiple medium-sized calls than try to get everything you need in a single huge call. Remember that you can always request a higher number of calls for free by contacting us.

(Regular Quandl users will recognize that multisets are functionally equivalent to non-persistent supersets created on the fly).

A Multiset Example

In this complex multiset example, we combine US GDP from FRED/GDP, crude oil spot prices from DOE/RWTC, and Apple stock 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. Here is the call:

http://quandl.com/api/v1/multisets.csv?columns=FRED.GDP.1,DOE.RWTC.1,WIKI.AAPL.4&collapse=annual&transformation=rdiff&rows=10

You can access the Quandl search engine directly from the API. For example, this call returns the top 20 results for the query "crude oil", in JSON format:

www.quandl.com/api/v1/datasets.json?query=crude+oil

If you prefer the results in XML format, the call is:

www.quandl.com/api/v1/datasets.xml?query=crude+oil

You can paginate through search results using page= and per_page=

www.quandl.com/api/v1/datasets.xml?query=crude+oil&per_page=50&page=2

Note that multiple search terms should be separated by a + character. We are currently working on enhancing API search; if you have suggestions, please email us.

Getting Metadata

You can access the metadata for any dataset using the following calls, for JSON and XML formats respectively:

http://www.quandl.com/api/v1/datasets/NSE/OIL.json?exclude_data=true 
http://www.quandl.com/api/v1/datasets/NSE/OIL.xml?exclude_data=true 

Metadata fields currently available include: source-code, table-code, numeric-id, name, description, last-update-time, update-frequency, from-date, to-date, column-names and privacy-setting.

Getting Favourites

You can get a list of a user's favourite datasets via the API in XML or JSON, by passing the users auth_token as a parameter:

 http://www.quandl.com/api/v1/current_user/collections/datasets/favourites.xml?auth_token=<auth_token>
 http://www.quandl.com/api/v1/current_user/collections/datasets/favourites.json?auth_token=<auth_token>

Cross-origin Resource Sharing (CORS)

The Quandl API supports CORS.

Further Resources

Many useful lists -- stock codes, futures codes, country codes, macro-economic indicator codes and more -- are available on our ticker lists page.

In addition, we have created pages detailing how to use the Quandl API within specific subject areas:

Quandl contributors have created a number of packages that "wrap around" the API. These packages allow you to access Quandl data directly from within the tool of your choice. Quandl packages currently available include R, Python, Matlab, Excel, Stata, Maple, C#, EViews, Java, C/C++, .NET, Clojure and Julia.

Keep in mind that this API is a work in progress. Tell us about bugs or additional needed features. Thank you for using Quandl!