thetadata-api / thetadata-python

Real-time & historical data API for US stocks and options

This API is deprecated, use our REST API!

Please use our REST API as it has better performance, more features, and more thorough documentation. Our REST API can be used in any language including Python. Each REST API endpoint comes with Python sample code.

This API is deprecated, use our REST API!

Please use our REST API as it has better performance, more features, and more thorough documentation. Our REST API can be used in any language including Python. Each REST API endpoint comes with Python sample code.

This API is deprecated, use our REST API!

Please use our REST API as it has better performance, more features, and more thorough documentation. Our REST API can be used in any language including Python. Each REST API endpoint comes with Python sample code.

This API is deprecated, use our REST API!

Please use our REST API as it has better performance, more features, and more thorough documentation. Our REST API can be used in any language including Python. Each REST API endpoint comes with Python sample code.

Thetadata Python API

The Thetadata Python API provides low latency US equities & options data that may be used for market research or algorithmic trading applications.

Please see this repository's documentation and GitHub for more details.

Installation

Java 11 or higher is required. If you are on Windows, Java 19 will automatically be installed for you. Python 10 or higher is highly recommended.

pip install thetadata

Please see our official installation instructions to get started.

thetadata-python's Issues

Feature request: time since epoch

client.get_hist_option currently has MS_OF_DAY and DATE, which requires an extra step to transform into a time since epoch. Is it possible to have TIME_SINCE_EPOCH?

Priority: low

Why are the column names in client.get_hist_option not strings?

Generally in pandas dataframes the column types are strings, but in thetadata they seem to be enum 'DataType'

Is there a practical reason for this?

Example code from install instructions fails

Following the install instructions, I get an error (listed below), with no obvious solution. My configuration:

OS: MacOS Sonoma 14.0
Python: 3.11.6
Java: 14.0.1

As a side note, downloading and installing extra software (the java code) should be done only with permission. Doing so automatically is rude at best.

[ins] In [1]: import pandas as pd
         ...: from datetime import date
         ...: from thetadata import ThetaClient, DateRange, StockReqType
         ...:
         ...:
         ...: def end_of_day() -> pd.DataFrame:
         ...:     client = ThetaClient()  # No credentials required for free access
         ...:
         ...:     # Make any requests for data inside this block. Requests made outside this block won't run.
         ...:     with client.connect():
         ...:         out = client.get_hist_stock(
         ...:             req=StockReqType.EOD,  # End of day data
         ...:             root="AAPL",
         ...:             date_range=DateRange(date(2022, 11, 14), date(2022, 11, 18))
         ...:         )
         ...:     # We are out of the client.connect() block, so we can no longer make requests.
         ...:     return out
         ...:
         ...: data = end_of_day()
If you require API support, feel free to join our discord server! http://discord.thetadata.us
------------------------------------------------------------------------------------------------
You are using the free version of Theta Data. You are currently limited to 20 requests / minute.
A data subscription can be purchased at https://thetadata.net. If you already have a ThetaData
subscription, specify the username and passwd parameters.
------------------------------------------------------------------------------------------------
---------------------------------------------------------------------------
ConnectionResetError                      Traceback (most recent call last)
Cell In[1], line 19
     16     # We are out of the client.connect() block, so we can no longer make requests.
     17     return out
---> 19 print(end_of_day())

Cell In[1], line 11, in end_of_day()
      9 # Make any requests for data inside this block. Requests made outside this block won't run.
     10 with client.connect():
---> 11     out = client.get_hist_stock(
     12         req=StockReqType.EOD,  # End of day data
     13         root="AAPL",
     14         date_range=DateRange(date(2022, 11, 14), date(2022, 11, 18))
     15     )
     16 # We are out of the client.connect() block, so we can no longer make requests.
     17 return out

File ~/.pyenv/versions/3.11.4/envs/theta/lib/python3.11/site-packages/thetadata/client.py:942, in ThetaClient.get_hist_stock(self, req, root, date_range, interval_size, use_rth, progress_bar)
    939 self._server.sendall(hist_msg.encode("utf-8"))
    941 # parse response header
--> 942 header_data = self._server.recv(20)
    943 header: Header = Header.parse(hist_msg, header_data)
    945 # parse response body

ConnectionResetError: [Errno 54] Connection reset by peer

[11-26-2023 17:43:37] INFO: Starting Theta Terminal v0.9.12 Revision D...
[ins] In [2]: java.net.ConnectException: Connection refused
	at java.base/sun.nio.ch.Net.connect0(Native Method)
	at java.base/sun.nio.ch.Net.connect(Net.java:503)
	at java.base/sun.nio.ch.Net.connect(Net.java:492)
	at java.base/sun.nio.ch.NioSocketImpl.connect(NioSocketImpl.java:588)
	at java.base/java.net.SocksSocketImpl.connect(SocksSocketImpl.java:333)
	at java.base/java.net.Socket.connect(Socket.java:648)
	at java.base/java.net.Socket.connect(Socket.java:597)
	at java.base/java.net.Socket.<init>(Socket.java:520)
	at java.base/java.net.Socket.<init>(Socket.java:294)
	at net.thetadata.terminal.client.ClientServerV2.init(ClientServerV2.java:42)
	at net.thetadata.terminal.App.setupServers(App.java:138)
	at net.thetadata.terminal.App.main(App.java:83)
[11-26-2023 17:43:37] INFO: Working Dir: /Users/xxxx/ThetaData/ThetaTerminal
Existing terminal instance found. Attempting to terminate it -->  [11-26-2023 17:43:37] ERROR: An instance of the Theta Terminal is already running or the port 11000 is in use or this terminal was unable to terminate the old one. Please terminate any existing instances of the Theta Terminal or python scripts.
[ins] In [2]:

Feature request: error handling on disconnected client

Current behavior:

• is someone attempts to make a call without the client being connected (omitting the with client.connect()) the error is pretty cryptic:

-> 686 self._server.sendall(hist_msg.encode("utf-8"))
    688 # parse response header
    689 header_data = self._server.recv(20)

OSError: [Errno 9] Bad file descriptor

Suggested change:

• catch the error with something like a Connection Error

Why this matters:

• Some new users may get discouraged
• hard to interpret in larger code bases
• current behavior makes testing for connection quality difficult

When DataType.ASK_SIZE is 0 should DataType.ASK be 0 or empty?

In get_hist_option, when DataType.ASK_SIZE is 0 DataType.ASK is set to 0.
Would it not make sense for it to be empty? (null or np.nan)

Feature request: subset the desired outputs of client.get_hist_option

The output of client.get_hist_option is very data intense and in some cases will be immediately subset. In order to speed things up (and potentially lower data volumes on both client and server side) would it be possible to specify what part of data we want?

For instance something like

    data = client.get_hist_option(
        req=OptionReqType.QUOTE,
        subset=["ASK", "ASK_SIZE", "DATE", "MS_OF_DAY"]    # Pseudocode for this example 
        root=root,
        exp=expiration_date,
        strike=strikes.iloc[0],
        progress_bar=True, 
        interval_size=30000,
        right=OptionRight.CALL,
        date_range=DateRange(start_date, 
                             end_date),
    )

Or maybe there is a way to do this that I haven't figured out?

What is the aggregation when requesting quotes with interval size?

My apologies if this is a stupid question.

When I request quotes on other exchanges every X minutes usually there is a "High" and "Low" (as it is for a period) but with get_hist_option it seems to be a single number. What is the aggregation that's being done?

Failed requesting stock quote data

I got this error when call get_hist_stock API:
thetadata.exceptions.ResponseParseError: Failed to parse body for request: MSG_CODE=200&START_DATE=20211230&END_DATE=20211230&root=SPY&sec=STOCK&req=201&rth=False&IVL=0
. Please send this error to support.

Simmilar error happens for get_hist_option API as well. It seems that the performance of API is not stable. I am using a loop to request for data day by day, and it always error out some place. Error on different day every time. But when I try debug on the single day that caused the error, it can get data successfully.

A Problem on Option Data

Can I use this API to get specific trading data for SP500 options? It would be better to have historical data on transactions.