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, irrespective of where or how the data was originally published.
API usage is free and unlimited. Anonymous calls are welcome, but limited to 50 requests per (UTC) day.
Signed-in Quandl users can make up to 500 API calls per day. Registering for a free Quandl account takes only a few seconds.
Users can request higher usage thresholds for free, by contacting us. No request is ever refused!
All users are subject to a speed limit of 5000 calls per hour.
Once you've registered, you will need an authentication token in order to make use of higher thresholds. You can find your auth_token under the API tab on your account page.
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.
A Simple Example
To get all data points for the dataset FRED/GDP in CSV format, do this call:
Registered users should include their auth_token, like this:
(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.
You can get data from the Quandl API in CSV, JSON, XML and HTML formats, by appending the relevant format code to your call.
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:
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:
On CSV calls, you can exclude column headers by passing the parameter
exclude_headers=true. Here is an example:
Note that this parameter will be ignored on non-CSV calls.
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:
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:
Set the end date with:
To get the Prague Stock Index data points for November 2012:
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:
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).
Append any basic API call with parameters to indicate the desired frequency.
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:
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:
|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|
|Start at 100||normalize||y'[t] = (y[t]/y) * 100|
Note that y 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:
Thus to get the Canadian GDP annual percentage change, you would do the following call:
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:
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.)
You can pull data from multiple datasets (or from multiple columns in a single dataset) using our "multisets" API call.
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, .xml and .plain.
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:
Doing a Search
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:
If you prefer the results in XML format, the call is:
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.
You can access the metadata for any dataset using the following calls, for JSON and XML formats respectively:
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.
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:
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:
- Futures: API for futures data
- Currencies: API for currency data
- Commodities: API for commodity data
- Stocks: API for stock data
- Bitcoin: API for bitcoin data
- Housing: API for housing data
- Macroeconomics: API for macroeconomic data
- Country Statistics: API for country data
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!