Tutorial
Logo

First introduction: getting an advantage in a few minutes

Twelve Data API is a service which provides financial data from all over the world (stock exchanges, forex markets, and crypto exchanges). Here you can get both historical and real-time financial data. All stock quotes can be accessed in a large number of intervals, starting from one minute up to monthly. Reliability and an innovative approach guarantee traders and developers access to the most precise and extensive financial data API.
This tutorial will walk you through to show you how to get started in a few minutes and explore the potential of Twelve Data API.

Getting your API Key

1. First things first, go to https://twelvedata.com/apikey
2. Provide your real email address which is used to confirm your account; it is used to protect from bots; we never send any kind of spam messages.
3. Next, enter text from the captcha image.
Once you submit the form an API Key will be issued and provided immediately.
API Key page
API Key page with entered details
API Key page with issued API Key
Enter your details with valid email address and captcha from the image.
Once you entered the data, click the “Get Free API Key” button to generate personal unique API Key.
Your API Key will be issued immediately and confirmation message will look like this.

Confirm email

After email confirmation your requests’ limits will be extended to up to 500 requests per minute for free.
Go to your email inbox and click the green confirmation button.
Email confirmation
Successful confirmation
Email body will contain your personal API Key and some sample requests to begin with.
Successful confirmation will redirect you to the home page.

How requests work

Explantion of request
Any Twelve Data API request consists of 3 parts
  1. A Prefix is a compulsory, non-changeable part
  2. The Endpoint is compulsory and might be
    • /time_series - for stocks, crypto and forex quotes
    • /bbands, /macd, /rsi, … - or any other indicator; a full list might be found in Technical Indicators section
  3. Parameters allow you to perfectly adjust the request to your needs. Three parameters are required:
    • symbol - stock ticker (e.g. AAPL, MSFT), physical currency pair (e.g. EUR/USD, CNY/JPY) or digital currency pair (BTC/USD, XRP/ETH)
    • interval - time frame (e.g. 1min, 5min, … , 1month)
    • apikey - your personal API Key obtained from the previous step
    Other parameters are optional and may be combined in arbitrary order. Most common are:
    • format - output format accepts json or csv (json by default)
    • outputsize - number of recent data points to retrieve (e.g. 12 will show the most recent twelve quotes)
    • start_date - start date and time of sampling period, accepts yyyy-MM-dd or yyyy-MM-dd hh:mm:ss format
    • end_date - end date and time of sampling period, accepts yyyy-MM-dd or yyyy-MM-dd hh:mm:ss format
    • exchange - if symbol is traded in multiple exchanges specify the desired one, valid for both stocks and cryptocurrencies

All parameters should be ampersand(&) separated. For a full list of available parameters refer to API Documentation

Mastering request understanding

To further understand how to build perfect requests and how they work you can refer to our brand-new API Query Generator tool.
API Query Generator
API Query Generator filled and confirmed
The API Query Generator has a clear and simple interface.
After parameters are entered you will be able to see your request and further use it. Also you can directly navigate to according section in API Documentation.

API request examples

Now we will show you some real-world API call examples with a short description. All requests are available in CSV format, which is very convenient for using in spreadsheets such as Excel, Google Docs or OpenOffice Calc. Remember that outputsize by default equals 30.
https://api.twelvedata.com/time_series?symbol=CNY/JPY&interval=1day&apikey=your_apikey
This call returns the last 30 trading days’ quotes for Chinese yuan against Japanese yen in JSON format.
https://api.twelvedata.com/time_series?symbol=MSFT&interval=5min&format=csv&start_date=2019-12-04&apikey=your_apikey
This stock API call will return all quotes for the Microsoft Corporation starting from December 4th 2019 up to the latest data point with five-minute intervals in CSV format.
https://api.twelvedata.com/time_series?symbol=BTC/ETH&exchange=Huobi&interval=1h&start_date=2019-12-01&end_date=2019-12-05&apikey=your_apikey
This call will return quotes for Ethereum against Bitcoin from the Huobi cryptocurrency exchange in date range from 2019-12-01 to 2019-12-05 with one-hour intervals.
https://api.twelvedata.com/bbands?symbol=AAPL&interval=1min&apikey=your_apikey
This stock API call returns 30 recent calculations of the Bollinger Band indicator in one-minute intervals for Apple stock.
https://api.twelvedata.com/macd?symbol=BTC/USD&interval=30min&outputsize=100&dp=8&apikey=your_apikey
This request will return MACD indicator 100 recent data points (MACD, MACD Signal and MACD Histogram) with eight decimal places accuracy where applicable for Bitcoin against the US Dollar.

Explore advantage

Now you are ready to explore the full potential of Twelve Data API!
As we have shown above, API parameters can be combined in arbitrary order in order to build and obtain necessary data.
For full reference, see the Documentation page.
If you have any questions, email us at api@twelvedata.com and our team will be glad to help you.