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.
Fast learners can infer almost everything about the API from this example:
Tutorials and comprehensive documentation follow below.
API usage is free for registered users.
Dataset calls are rate-limited to 2,000 calls per 10 minutes. Search calls are limited to 60 per minute.
Abusive behavior will be throttled. If you need to download large amounts of data and these limits are proving restrictive, please contact us.
You will need an authentication token unless you are doing fewer than 50 calls per day. Logged-in users can find their authentication token here.
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 database 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 database code and GDP is the table code. All datasets from the same database will have the same database code.
Note that table codes are not guaranteed to be unique across database. SHFE/CUG2014 is not the same as MCX/CUG2014. Thus you need both the database 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:
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.
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.)
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:
You can paginate through search results using
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:
You can also paginate through the list using
Premium databases have an additional API route which enables you to download the entire database in a single call. Read each premium database's respective documentation page to learn more about this route. See our list of premium databases here.
Cross-origin Resource Sharing (CORS)
The Quandl API supports CORS.
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:
- Stocks: API for stock data
- Economics: API for economic data
- Earnings: API for earnings data
- Futures: API for futures data
- Currencies: API for currency data
- Commodities: API for commodity data
- Cross-Country Statistics: API for country data
- Housing: API for housing data
- Bitcoin: API for bitcoin data
Quandl contributors have created a number of libraries that allow you to use the API from within your own application. Libraries currently available include R, Python, Matlab, Excel, Stata, Maple, C#, EViews, Java, C/C++, .NET, Clojure and Julia.