There are several options for obtaining the data in Twelve Data. They can be divided into two categories: long-polling via API and server-push via WebSocket. In the second scenario, the server will automatically send the data to the client once it is available, so the client will always stay with the latest information.
This tutorial will cover establishing the connection and start receiving the data in a few easy steps.
Open a connection.
Send subscribe event.
Manipulate the data.
Close the connection.
You can use any programming language or plugin of your choice. Here for the sake of simplicity, we will be using the WebSocket playground.
Step 1. Establish a connection
Your API key is used to connect to the Twelve Data Distributed WebSocket System (TDDWS). This system will manage all your subscriptions to all available instruments across all exchanges. You can establish up to 3 connections (typically used in production, stage, and local environments) across the whole lifespan of the application, the previous connections will be closed if you overuse the limit.
Use the default URL to connect to a WebSocket server:
wss://ws.twelvedata.com/v1/quotes/price?apikey=your_api_key
The connection is handled automatically in the WS playground, and there is no need to specify your API key. Simple click Open connection.
Step 2. Subscribe to data
To begin streaming prices, the subscribe events have to be sent. They follow a straightforward format, and the symbol tickers could be used in the same way as they are used in the API. Simultaneously you may subscribe to different markets, exchanges, or asset types.
{
"action": "subscribe",
"params": {
"symbols": "AAPL,INFY,TRP,QQQ,IXIC,EUR/USD,USD/JPY,BTC/USD,ETH/BTC"
}
}
WS playground already includes sample events that could be viewed by clicking the appropriate button. You may also change the list of symbols. Once you're ready, click the Send button.
Apart from subscribe events, you can also send unsubscribe, reset, and hearbeat events. The last ones are advised to be sent every 10 seconds to make sure that your connection stays alive.
Step 3. Manipulate the data
The data stream is displayed on the right-hand side. Raw messages are displayed in the playground. However, in a working environment, you can do any kind of manipulations with the data: analyze, store, display, process, etc.
There are two general return event types: subscribe-status and price.
Status events return the information about the events themselves, which symbols were successfully subscribed/unsubscribed, etc.
Price events return the real-time tick prices for the subscribed symbols. The message will include the brief meta information, UNIX timestamp, and the price itself. The daily volume will be also returned where available.
Step 4. Close the connection
Once the work has been done and there is no need to keep the connection open - you may close it. The structure depends on the programming language. However, inside the WS playground, it is done by clicking the Close connection button. This will make sure not to have an idle connection that will be wasting your WS credits usage.