Using the Quandl API
This document is a quick guide to using the Quandl API.
Complete API documentation can be found here.
(Note: The guide to v1 of the Quandl API is available here. We encourage users to adopt the current version, v1 is on the path to deprecation.)
Fast learners can infer almost everything about the API from this example:
API usage is free for registered users.
Registered users have a limit of 2,000 calls per 10 minutes, and a limit of 50,000 calls per day.
Premium data subscribers have a limit of 5,000 calls per 10 minutes, and a limit of 720,000 calls per day.
Dataset calls are rate-limited to 2,000 calls per 10 minutes.
Abusive behavior will be throttled.
You will need an API Key unless you are doing fewer than 50 calls per day. Logged-in users can find their API Key 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 dataset_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 dataset_code. All datasets from the same database will have the same database 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 API Key, like this:
(Note: The api_key in the example above is a fake, and will not work.)
In the interest of concision and code clarity, we will not include api_key in the remaining examples on this page.
You can get data from the Quandl API in CSV, JSON, and XML 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 some available manipulations:
You can select the sort order by passing the parameter
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:
Excluded Column Names
On CSV calls, you can exclude column headers by passing the parameter
exclude_column_names=true. Here is an example:
(Note: 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_index=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 available 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 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.
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.