Welcome to this lesson on requesting market data in the Trader Workstation API. In this video, we will be highlighting the requirements for requesting market data, how to request delayed data, how to request live market data, and how to request historical bars. Please note that these are the most popular methods of requesting market data; however, Interactive Brokers also offers tick data, histogram data, and market depth.<\/p>\n\n\n\n
Let\u2019s begin by discussing market data subscriptions. In order for clients to subscribe to market data, users must have a funded IBKR account for at least $500 USD in most instances. There are some instances where this is not the case; however, for the average individual at Interactive Brokers, $500 is the minimum. This threshold must be maintained in addition to the cost of any subscriptions held by the account.<\/p>\n\n\n\n
For those with a long-time IBKR PRO account, you may have observed that some instruments return market data to your Trader Workstation for free by default. That is because some market data can be provided to users for free while \u201con-platform\u201d. On-platform simply means that users are observing data directly display through one of Interactive Brokers platforms. Exchanges consider API functionality to be considered off-platform, and as a result, typically have a cost affiliated with them. Some of the most popular market data subscriptions for API use are listed in the API Documentation for Market Data on IBKR Campus. Users can subscribe to market data through the Client Portal. <\/p>\n\n\n\n
It is also worth clarifying that Market Data is affiliated on a per-user basis. Many clients will run a single Trader Workstation instance for monitoring trades; however, it is common to have a separate machine running your trading algorithm on IB Gateway hosted on a virtual machine elsewhere. In order for both of these platforms to retrieve market data, each user consuming market data would need to subscribe to data separately.<\/p>\n\n\n\n
With the subscription discussion out of the way, we can start to dive into the actual API requests. Please note that we will be using the same framework from our Essential Components video, so if there are any questions on the initial structure in this video, please be sure to review that lesson first.<\/p>\n\n\n\n
The most popular way of requesting and viewing data in the API would be with EClient.reqMktData method, which requests the same data available in the TWS Watchlists.<\/p>\n\n\n\n
Clients that do not have a market data subscription for instruments can often request 15 minute delayed data. This is only a single extra step compared to standard market data subscriptions, so I will include it before moving forward.<\/p>\n\n\n\n
To clarify if your requests will be Live or delayed, users simply need to call the app.reqMarketDataType function. The only argument this takes is the type of data to retrieve, which can be 1,2,3,4 or Live, Frozen, Delayed, or Delayed Frozen respectively. Frozen data will refer to market data from the most recent close, while delayed frozen data will return yesterday\u2019s closing values. And then as we\u2019ve mentioned, standard delayed data will return 15-minute delayed data.<\/p>\n\n\n\n
If I am subscribed to market data on a given instrument, but request delayed market data, live data will still be returned. Interactive Brokers will always try to provide the most up-to-date market data where possible.<\/p>\n\n\n\n
Now, let\u2019s start building out our request for streaming data. We will be focused on requesting price and size data; however, the reqMktData request can also return string, news, generic and even Greek values depending on the tick types provided.<\/p>\n\n\n\n
From within our TestApp class, let\u2019s start defining one of our tick functions, tickPrice. This will handle all returning values related to price values. tickPrice takes self, reqId, tickType, price, and attrib as arguments. While we\u2019re already familiar with the first two, and the last two are rather self-explanatory, the tickType argument is used to indicate what kind of data is coming in.<\/p>\n\n\n\n
Each tickType is an integer value that correlates to a specific value, be it bid price, last size, closing price, or otherwise. For a full list of all of these tick values, we can look at ticktype.py inside the ibapi source files and see exactly what everything is relating to. Users are welcome to reference the returned integer values directly; however, the enumerator contains a toStr method that converts our tick type integers into the values we see before us. In our file, we can add an import for from ibapi.ticktype import TickTypeEnum<\/em>. This will allow us to reference the TicKTypeEnum.toStr() method and print out our value directly in a moment.<\/p>\n\n\n\n I will print out all of these values in an \u00adf-string<\/em>, including our reference of TickTypeEnum.toStr(). As we discussed before, this would be perfectly fine to print out our price values; however, I also want to see the quantities of our trades effected by this. To do this, we will also add the EWrapper.tickSize function to our TestApp class as well. This function only takes the arguments: self, reqId, tickType, and size. The sizes returned here will relate to the prices returned in our tickPrice function and allow us to create a clearer picture of the trades taking place.<\/p>\n\n\n\n Now that we have everything in place to receive the data, let\u2019s build out a contract object and a request for market data. Leaping off of our prior video, I\u2019ll make a request for AAPL market data using the symbol, security type, currency, and exchange values.<\/p>\n\n\n\n With a contract now set, I can call app.reqMktData to start requesting my streaming data. For arguments, we\u2019ll need to pass the reqId, which we\u2019ll use our app.nextId() function for. I can pass mycontract for the contract object. For our next argument, the generic tick list, I will pass \u201c232\u201d as a string so I can retrieve the mark price from my request. For users looking to request multiple generic ticks, you would simply comma-separate the values within the string. So maybe you would pass \u201c232, 233, 234\u201d as an example.<\/p>\n\n\n\n The next argument defines if we are requesting a Snapshot value.<\/p>\n\n\n\n This is a single return instance aggregating the last 11 seconds of trading. If no trading has taken place, this will not return any values. And if we do see trades in the last 11 seconds, we will see those values returned in aggregate. Similarly, the next argument determines if we are requesting a regulatory snapshot. This is a snapshot used to determine the price of an instrument before executing a trade.<\/p>\n\n\n\n Regulatory snapshots will cost approximately $0.01 per request, until we reach the cost of the affiliated subscription. If I request market data for AAPL repeatedly, Interactive Brokers will eventually add the subscription to your account, as the cost of the regulatory snapshots equate to the value of the subscription anyway. The final argument takes market data options, which is an argument used only for internal purposes.<\/p>\n\n\n\n If we run this script, we\u2019ll find an initial flood of data depicting the most recent values for several tick types, then over time we will receive all the live data prices and sizes as they come through.<\/p>\n\n\n\n Requesting Historical Data follows a similar pattern to the live market data requests. The one caveat to this is that market data cannot be retrieved if you do not have a valid market data subscription. Before we begin to dig into historical data, I\u2019d like to first find how far back we can request market data. I\u2019ll start finding this value using a new python file.<\/p>\n\n\n\n In our new file, I will create a new function in the TestApp class to define the headTimeStamp function. This takes three arguments, self, a request ID, and the headTimeStamp string. Within my new function, I will print out my headTimeStamp value. I will also make a request for self.cancelHeadTimeStamp to terminate the request now that I\u2019m done with it, and we can just pass the requestId we received as an argument. With the EWrapper piece out of the way, I will move out of the TestApp class to create my headTimeStamp request. I will copy over my same AAPL contract I used from the Live Data script, because I want to validate how far back I can find AAPL market data.<\/p>\n\n\n\n Next, I will make a call to the app.reqHeadTimeStamp function. This takes an argument for a request ID, which can use our nextId function; and a contract reference, which will take my mycontract<\/em> object. After these two, I\u2019m now encountering something known as the \u201cwhatToShow\u201d value. This same value is used to denote what data is displayed in your TWS bar charts. In my case, I will use the value for Trades, though the full list of whatToShow values are available in our documentation.<\/p>\n\n\n\n The next argument relates to using regular trading hours. A 1 will indicate that we want the earliest date within trading hours, while a 0 will request the earliest date outside of trading hours. Finally, we have the formatDate parameter. This will indicate whether we want 1, a UTC timestamp in a string format, or 2, an Epoch timestamp. The latter is an integer representation of the same timestamp. You can consider the former better for human consumption, while the latter is best utilized in a programmatic request structure. I will show these off in just a moment by making two requests.<\/p>\n\n\n\n If we run this script using \u20181\u2019 as the date format, we\u2019ll see 19801212-14:30:00. Meaning AAPL\u2019s \u201cTrades\u201d market data can go as far back as December 12, 1980 at 9:30 AM Eastern. Before we move on, I\u2019ll quickly add another print statement to my headTimeStamp method for the datetime.datetime.fromtimestamp function, taking in the integer version of our headTimeStamp. If I change my original request to use 2 as my date format, I\u2019ll print out the original epoch value as well as the python translated datetime, which is automatically converted to my pc\u2019s local time in US\/Central time.<\/p>\n\n\n\n Now that we know our historical data range, we can start making a request for historical data. You are welcome to use the same file, but for my demonstration, I\u2019ll be starting from a fresh example of our standard layout but add in our AAPL contract again. As always, we\u2019ll define the EWrapper function inside TestApp using def historicalData. This function takes an argument for self, reqId, and bar. We will finish the function by printing the reqId and bar values.<\/p>\n\n\n\n I will note that we are printing out the full bar object; however, the bar object can be split out, so you may print bar.open for the opening price, bar.close for the closing price, and so on. But just for our presentation here, I\u2019ll print the whole thing.<\/p>\n\n\n\n Each bar size is returned separately, so for us to know we\u2019re done we should reference the EWrapper function for historicalDataEnd. This function takes an argument for self and reqID and is just meant to indicate that all available data has been returned to the user.<\/p>\n\n\n\n With the wrapper functions set, we\u2019ll start our EClient request. To make the request, we\u2019ll call the app.reqHistoricalData function. This takes 10 total arguments, starting with reqid, contract.<\/p>\n\n\n\n The next argument is endDateTime, which takes the value we\u2019d like to end our historical data at. If we leave this as an empty string, the system will assume the current time. Otherwise, we would make a format for year, month, day followed by the 24 hour timestamp, and a timezone. You must pass the timezone for the exchange, available through a Contract Details request, the exact timezone used for your TWS, which is set prior to the homescreen, or using UTC. I will send my request for \u201c20240523 16:00:00 US\/Eastern\u201d.<\/p>\n\n\n\n Then, we\u2019ll pass in a duration value, which corresponds to the full interval over which data will be returned. So, if I specify \u201c1 D\u201d, I will receive however many bars in a single day. On the topic of bars, the next argument will take the bar size. In my case, I can pass \u201c1 hour\u201d to receive an hour.<\/p>\n\n\n\n This means I will receive 7 bars for my day, a bit more on that later.<\/p>\n\n\n\n Moving forward in our arguments, we\u2019ll find more familiar values, like the whatToShow value we used before, which I\u2019ll use \u201cTRADES\u201d for once again, then useRth and formatDate, again using 1 in both cases. Now we have the option for \u201ckeepUpToDate\u201d, which allows us to build bars as data is available and return these new bars to the historicalDataUpdate function. I\u2019m not interested in this data at the moment, so I\u2019ll go ahead and leave this as False for now. Finally, we end with market data options, which I\u2019ll again leave as an empty list.<\/p>\n\n\n\n Now if we run this script, I will see my request ID, and all of my bar\u2019s values. While most of this is self-explanatory, there are a few points I\u2019d like to mention from the programmatic standpoint. You might notice that we sent the request using US\/Eastern, but my data shows America\/Chicago. That\u2019s because I\u2019m choosing to print out my \u201cOperator Timezone\u201d even though I made the request with the \u201cInstrument Timezone\u201d. You can modify the time zone returned in TWS by opening the Global Configuration page and opening the API Settings. You\u2019ll notice a section for \u201cSend instrument-specific attributes for dual-mode API Client in\u201d. Specifying Operator Timezone returns your TWS time zone, Instrument time zone returns the time zone for the contract, and UTC is obviously the UTC time zone.<\/p>\n\n\n\n The other piece I\u2019d like to mention is the 7 bars I had referenced earlier. The Date value in the bar references the starting time for the bar. In my case, we can see my bar started at 08:30:00 America\/Chicago, which is when NASDAQ opens for trading AAPL. But then we\u2019ll see 09:00 as our next bar, meaning our first bar is only 30 minutes long, before turning into a series of 1-hour bars. This is the same behavior as Trader Workstation, though it may not be as commonly understood when pulling data programmatically. Therefore, it\u2019s best practice to use the next bar as an indicator of approximate bar size.<\/p>\n\n\n\n This concludes our lesson on market data in the TWS API. Thank you for watching. If you have any questions, please be sure to review our documentation or leave a comment below this video. We look forward to having you in the next lesson of our TWS API series.<\/p>\n\n\n\n This lesson will explore how to request market and historical data using the TWS Python API. Code examples will be presented which show the minimum Python code necessary to request streaming and historical data and display market data in the console. Finally, we will discuss limitations on requesting data, and the types of data which are included in IBKR\u2019s real time feed as compared to the historical database.<\/p>\n","protected":false},"author":940,"featured_media":208808,"parent":0,"comment_status":"open","ping_status":"closed","template":"","meta":{"_acf_changed":false,"footnotes":""},"contributors-categories":[13576],"traders-academy":[13126,13128,13132],"class_list":{"0":"post-175506","1":"trading-lessons","2":"type-trading-lessons","3":"status-publish","4":"has-post-thumbnail","6":"contributors-categories-interactive-brokers","7":"traders-academy-intermediate-trading","8":"traders-academy-level","9":"traders-academy-trading-lesson"},"pp_statuses_selecting_workflow":false,"pp_workflow_action":"current","pp_status_selection":"publish","acf":[],"yoast_head":"\nRequesting Historical Data<\/strong><\/h4>\n\n\n\n
Requesting the headTimeStamp Value<\/strong><\/h4>\n\n\n\n
Requesting historical bars<\/strong><\/h4>\n\n\n\n
Code Snippet – headTimeStamp<\/h4>\n\n\n\n
from ibapi.client import *\nfrom ibapi.wrapper import *\nimport datetime\nimport time\nimport threading\n\nport = 7497\n\n\nclass TestApp(EClient, EWrapper):\n def __init__(self):\n EClient.__init__(self, self)\n\n def nextValidId(self, orderId: OrderId):\n self.orderId = orderId\n \n def nextId(self):\n self.orderId += 1\n return self.orderId\n \n def error(self, reqId, errorCode, errorString, advancedOrderReject=\"\"):\n print(f\"reqId: {reqId}, errorCode: {errorCode}, errorString: {errorString}, orderReject: {advancedOrderReject}\")\n \n def headTimestamp(self, reqId, headTimeStamp):\n print(headTimeStamp)\n print(datetime.datetime.fromtimestamp(int(headTimeStamp)))\n self.cancelHeadTimeStamp(reqId)\n\n\napp = TestApp()\napp.connect(\"127.0.0.1\", port, 0)\nthreading.Thread(target=app.run).start()\ntime.sleep(1)\n\nmycontract = Contract()\nmycontract.symbol = \"AAPL\"\nmycontract.secType = \"STK\"\nmycontract.exchange = \"SMART\"\nmycontract.currency = \"USD\"\n\napp.reqHeadTimeStamp(app.nextId(), mycontract, \"TRADES\", 1, 2)<\/pre>\n\n\n\nCode Snippet – historical_market_data.py<\/h4>\n\n\n\n
from ibapi.client import *\nfrom ibapi.wrapper import *\nimport datetime\nimport time\nimport threading\n\nport = 7497\n\n\nclass TestApp(EClient, EWrapper):\n def __init__(self):\n EClient.__init__(self, self)\n\n def nextValidId(self, orderId: OrderId):\n self.orderId = orderId\n \n def nextId(self):\n self.orderId += 1\n return self.orderId\n \n def error(self, reqId, errorCode, errorString, advancedOrderReject=\"\"):\n print(f\"reqId: {reqId}, errorCode: {errorCode}, errorString: {errorString}, orderReject: {advancedOrderReject}\")\n \n def historicalData(self, reqId, bar):\n print(reqId, bar)\n \n def historicalDataEnd(self, reqId, start, end):\n print(f\"Historical Data Ended for {reqId}. Started at {start}, ending at {end}\")\n self.cancelHistoricalData(reqId)\n\napp = TestApp()\napp.connect(\"127.0.0.1\", port, 0)\nthreading.Thread(target=app.run).start()\ntime.sleep(1)\n\nmycontract = Contract()\nmycontract.symbol = \"AAPL\"\nmycontract.secType = \"STK\"\nmycontract.exchange = \"SMART\"\nmycontract.currency = \"USD\"\n\napp.reqHistoricalData(app.nextId(), mycontract, \"20240523 16:00:00 US\/Eastern\", \"1 D\", \"1 hour\", \"TRADES\", 1, 1, False, [])<\/pre>\n\n\n\nCode Snippet – LiveData.py<\/h4>\n\n\n\n
from ibapi.client import *\nfrom ibapi.wrapper import *\nimport datetime\nimport time\nimport threading\nfrom ibapi.ticktype import TickTypeEnum\n\nport = 7497\n\n\nclass TestApp(EClient, EWrapper):\n def __init__(self):\n EClient.__init__(self, self)\n\n def nextValidId(self, orderId: OrderId):\n self.orderId = orderId\n \n def nextId(self):\n self.orderId += 1\n return self.orderId\n \n def error(self, reqId, errorCode, errorString, advancedOrderReject=\"\"):\n print(f\"reqId: {reqId}, errorCode: {errorCode}, errorString: {errorString}, orderReject: {advancedOrderReject}\")\n \n def tickPrice(self, reqId, tickType, price, attrib):\n print(f\"reqId: {reqId}, tickType: {TickTypeEnum.toStr(tickType)}, price: {price}, attrib: {attrib}\")\n \n def tickSize(self, reqId, tickType, size):\n print(f\"reqId: {reqId}, tickType: {TickTypeEnum.toStr(tickType)}, size: {size}\")\n\n\napp = TestApp()\napp.connect(\"127.0.0.1\", port, 0)\nthreading.Thread(target=app.run).start()\ntime.sleep(1)\n\nmycontract = Contract()\nmycontract.symbol = \"AAPL\"\nmycontract.secType = \"STK\"\nmycontract.exchange = \"SMART\"\nmycontract.currency = \"USD\"\n\napp.reqMarketDataType(3)\napp.reqMktData(app.nextId(), mycontract, \"232\", False, False, [])<\/pre>\n","protected":false},"excerpt":{"rendered":"