Historical Data - Market Replay Developer Guide
The historical query/response system allows a user to request intraday (both tick, including Trades and Quotes-Bid/Ask, and minute) data as well as end of day data. In order to accomplish this, three types of queries are provided (Tick, Minute, and EOD).
Last Updated: December 1, 2020 Download complete .rtf file
All query URLs are located under the historical server application directory: http://ds01.ddfplus.com/historical/.
Tick queries return all tick records for a specified symbol during a specified period between a start and an end date/time. A maximum number of records to be returned can also be specified, along with either the start or end date/time, or both. The request handler for tick queries is queryticks.ashx.
The result set returned from a tick query will always be confined to a single day. In other words, if ticks for different days are required, then more than one query will have to be executed in order to retrieve all the ticks.
If both a start and an end date/time are specified, then all ticks within the specified period will be returned, as long as the period is contained within a single day. If a maximum number of records is specified along with both date/times and the number of tick records between those dates exceeds the maximum number of records to be returned, then the excess records will be cut off from the beginning or the end of the result set depending on the sort order specified in the query (if ascending order is specified, excess records will be cut off from the chronological end of the result set, otherwise they will be cut off from the chronological beginning).
If no start date/time is specified and an end date/time is specified along with a maximum number of records to be returned, then a number of records up to the maximum number specified or back to the beginning of the specified end day will be returned, whichever is smaller. If no maximum number of records is specified, then all the tick records between the end date/time specified and the beginning of the specified end day will be returned.
If no end date/time is specified and a start date/time is specified along with a maximum number of records to be returned, then a number of records up to the maximum number specified or up to the end of the specified start day will be returned, whichever is smaller. If no maximum number of records is specified, then all the tick records between the start date/time specified and the end of the specified start day are returned.
If no date/times are specified, then the start date/time will default to the beginning of the current day and the end date/time will default to the beginning of the next day. If a maximum number of records is specified, the query will be treated as if both start and end date/times had been specified with their default values (refer to maximum number of records when both dates are specified in paragraph above).
Note: although query date/times can only be specified down to the second, tick timestamps are returned down to the millisecond, and several ticks can actually occur in the same millisecond, so when specifying a maximum number of ticks in a query, all ticks within a given second will be returned even if they exceed the maximum number of ticks specified.
The following parameters are either required or supported in tick queries (required parameters are marked with an asterisk):
Note: All times are in Eastern Time for equities and Central Time for everything else.
Results are returned by tick queries in comma delimited text format, one tick record per line, as follows:
YYYY-MM-DD HH:MM:SS.FFF,TRADING_DAY,SESSION_CODE,PRICE,SIZE
Example:
2009-02-03 13:30:00.000,10,G,823.5,1 2009-02-03 13:30:00.125,10,G,823.75,7
The session code (session code for futures and sale condition for equities) is a single character that is documented in the ddfplus broadcast feed specifications on the ddfplus developer website.
In order to query all the ticks for Apple between 9 am and 12 pm on February 3, 2009, execute:
https://historical-quotes.aws.barchart.com/historical/queryticks.ashx?username=username&password=password&symbol=AAPL&start=20090203090000&end=20090203120000
In order to query the last 1000 ticks for Apple for the current day in descending order, execute:
https://historical-quotes.aws.barchart.com/historical/queryticks.ashx?username=username&password=password&symbol=AAPL&maxrecords=1000&order=desc
In order to query the first 1000 ticks for Apple for the February 3, 2009, in ascending order, execute:
https://historical-quotes.aws.barchart.com/historical/queryticks.ashx?username=username&password=password&symbol=AAPL&start=20090203&maxrecords=1000&order=asc
In order to query all the ticks for Apple between 9 am and 12 pm on February 3, 2009, execute:
https://historical-quotes.aws.barchart.com/historical/queryticks.ashx?username=username&password=password&type=T&symbol=AAPL&order=desc&sessionfilter=!!&maxrecords=10&sale4Condition=true&participantID=true&exchId=true
Results are returned by tick queries in comma delimited text format, one tick record per line, as follows:
YYYY-MM-DD HH:MM:SS.FFF,TRADING_DAY,EXCHANGE ID(optional),SESSION_CODE,SALE 4BYTE CONDITION(optional),PRICE,SIZE,PARTICIPANT ID(optional)
Example:2020-12-01 11:56:33.122,1,Q,I,@ I,123.1432,3,D 2020-12-01 11:56:32.734,1,Q,I,@ I,123.145,4,D 2020-12-01 11:56:32.467,1,Q,@,@ ,123.145,100,Q 2020-12-01 11:56:32.453,1,Q,I,@ I,123.1493,5,D
Quote Condition is implied ‘Regular’ for the Best Bid and Best Offer. In order to query all the ticks for Apple between 9 am and 12 pm on February 3, 2009, execute:
https://historical-quotes.aws.barchart.com/historical/queryticks.ashx?username=username&password=password&type=Q&symbol=AAPL&order=desc&sessionfilter=!!&maxrecords=10&sale4Condition=true&participantID=true&exchId=true
Results are returned by tick queries in comma delimited text format, one tick record per line, as follows:
YYYY-MM-DD HH:MM:SS.FFF,TRADING_DAY,EXCHANGE ID(optional),Quote Condition,BID PRICE, BID SIZE,Bid Participant ID(optional),OFFER PRICE, OFFER SIZE,Offer Participant ID(optional)
Example:2020-12-01 12:53:55.791,1,Q,R,122.83,100,Q,122.84,1000,N 2020-12-01 12:53:55.730,1,Q,R,122.83,100,Q,122.84,900,N
Both example: (Type='B')
exchangeID=true (defaults false) - returns the listing exchange
Q – Nasdaq
A – NYSE Arca
N – NYSE
U – OTC BB
participantID=true (default false) - returns the Participant or Processor that initiated the trade.
Particpant ID for NYSE / NYSE Arca (cts pillar output page 64)
A – NYSE American, LLC (NYSE American)
B – NASDAQ OMX BX, Inc. (NASDAQ OMX BX)
C – NYSE National, Inc. (NYSE National)
D – FINRA Alternative Display Facility (ADF)
H – MIAX Pearl Exchange, LLC (MIAX)
I – International Securities Exchange, LLC (ISE)
J – Cboe EDGA Exchange, Inc. (Cboe EDGA)
K – Cboe EDGX Exchange, Inc. (Cboe EDGX)
L – Long-Term Stock Exchange, Inc. (LTSE)
M – NYSE Chicago, Inc. (NYSE Chicago)
N – New York Stock Exchange, LLC (NYSE)
P – NYSE Arca, Inc. (NYSE Arca)
S – Consolidated Tape System (CTS)
T – NASDAQ Stock Market, LLC (NASDAQ)
U – Members Exchange, LLC (MEMX)
V – Investors’ Exchange, LLC. (IEX)
W – CBOE Stock Exchange, Inc. (CBSX)
X – NASDAQ OMX PSX, Inc. (NASDAQ OMX PSX)
Y – Cboe BYX Exchange, Inc. (Cboe BYX)
Z – Cboe BZX Exchange, Inc. (Cboe BZX)
Particpant ID for Nasdaq (utp binnary 1.5 page 36)
A – NYSE American, LLC
B – Nasdaq BX, Inc.
C – NYSE National, Inc.
D – Financial Industry Regulatory Authority (FINRA)
E – Market Independent
H – MIAX Pearl, LLC (MIAX)
I – Nasdaq ISE, LLC*
J – Cboe EDGA Exchange, Inc.
K – Cboe EDGX Exchange, Inc.
L – Long-Term Stock Exchange (LTSE)
M – NYSE Chicago, Inc.
N – New York Stock Exchange LLC
P – NYSE Arca, Inc.
Q – Nasdaq, Inc.
U – MEMX LLC (MEMX)
V – Investors’ Exchange LLC (IEX)
W – Cboe Exchange, Inc.
X – Nasdaq PHLX LLC
Y – Cboe BYX Exchange, Inc.
Z – Cboe BZX Exchange, Inc.
sale4Condition=true (default false) - returns the extended 4 byte sale condition associated with the trade.
Sale Condition NYSE - Denotes the sale condition associated with a trade (cts pillar output page 64)
@ – Regular Sale
B – Average Price Trade
C – Cash Trade (Same Day Clearing)
E – Automatic Execution
F – Inter-market Sweep Order
H – Price Variation Trade
I – Odd Lot Trade
K – Rule 127 (NYSE Only) or Rule 155 (NYSE American only)
L – Sold Last (Late Reporting)
M – Market Center Official Close
N – Next Day Trade (Next Day Clearing)
O – Market Center Opening Trade
P – Prior Reference Price
Q – Market Center Official Open
R – Seller
T – Extended Hours Trade
U – Extended Hours Sold (Out Of Sequence)
V – Contingent Trade
X – Cross Trade
Z – Sold (Out Of Sequence)
4 – Derivatively Priced
5 – Market Center Reopening Trade
6 – Market Center Closing Trade
7 – Qualified Contingent Trade
8 – Reserved
9 – Corrected Consolidated Close Price as per Listing Market
Sale Condition Nasdaq - Denotes the sale condition associated with a trade (utp binnary 1.5 page 43)
@ – Regular Sale
A – Acquisition
B – Bunched Trade
C – Cash Sale
D – Distribution
E – Placeholder
F – Intermarket Sweep
G – Bunched Sold Trade
H – Price Variation Trade
I – Odd Lot Trade
K – Rule 155 Trade (AMEX)
L – Sold Last
M – Market Center Official Close
N – Next Day
O – Opening Prints
P – Prior Reference Price
Q – Market Center Official Open3
R – Seller
S – Split Trade
T – Form T
U – Extended trading hours (Sold Out of Sequence)
V – Contingent Trade
W – Average Price Trade
X – Cross Trade
Y – Yellow Flag Regular Trade
Z – Sold (out of sequence)
1 – Stopped Stock (Regular Trade)
4 – Derivatively priced
5 – Re-Opening Prints
6 – Closing Prints
7 – Qualified Contingent Trade
8 – Placeholder For 611 Exempt
9 – Corrected Consolidated Close (per listing market)
Minute queries return all minute records for a specified symbol during a specified period between a start and an end date/time. A maximum number of records to be returned can also be specified, along with either the start or end date/time, or both. The request handler for minute queries is queryminutes.ashx.
An optional interval can be specified in order to aggregate sets of contiguous minute records (the number of minute records in each set is equal to the specified interval) into one record. If the interval is omitted, then a 1 minute interval (no aggregation) will be the default.
If both a start and an end date/time are specified, then all minutes within the specified period will be returned. If a maximum number of records is specified along with both date/times and the number of minute records between those dates exceeds the maximum number of records to be returned, then the excess records will be cut off from the beginning or the end of the result set depending on the sort order specified in the query (if ascending order is specified, excess records will be cut off from the chronological end of the result set, otherwise, excess records will be cut off from the chronological beginning; otherwise).
If no start date/time is specified and an end date/time is specified along with a maximum number of records to be returned, then a number of records up to the maximum number specified or back to the beginning of the available minute data will be returned, whichever is smaller. If no maximum number of records is specified, then all the minute records between the end date/time specified and the beginning of the specified end day will be returned.
If no end date/time is specified and a start date/time is specified along with a maximum number of records to be returned, then a number of minute records up to the maximum number specified or up to the most current minute record available will be returned, whichever is smaller. If no maximum number of records is specified, then all the minute records between the start date/time specified and the end of the specified start day are returned.
If no date/times and no maximum number of records are specified, then the start date/time will default to the beginning of the current day and the end date/time will default to the beginning of the next day. If a maximum number of records is specified, the query will be treated as if the start date/time is specified to the beginning of available data and the end date/time is specified to the end of available data (refer to maximum number of records when both dates are specified in paragraph above).
Trading_Day for futures contracts signifies the actual trading day used to construct the daily o/h/l/c values. For the (ES) E-Mini S&P futures Trading _Day will start at 3:30pm the previous day, and finish at 3:15pm the next day.
Historical market data reflects all trades made during all sessions of the market, including electronic trades executed for futures markets during regular holidays.
The date/times for all futures and forex contracts are always in CST. Times are adjusted for daylight savings time.
The following parameters are either required or supported in minute queries (required parameters are marked with an asterisk):
Note: All times are in Eastern Time for equities and Central Time for everything else.
Results are returned by minute queries in comma delimited text format, one minute record per line, as follows:
YYYY-MM-DD HH:MM,TRADING_DAY,OPEN,HIGH,LOW,CLOSE,VOLUME
Example:
2009-02-03 14:44,10,821.75,823.25,820.75,823,10279 2009-02-03 14:43,10,823.25,823.75,821.75,821.75,11888
In order to query all the minute records for Apple between 9 am and 12 pm on February 3, 2009, execute:
https://historical-quotes.aws.barchart.com/historical/queryminutes.ashx?username=username&password=password&symbol=AAPL&start=200902030900&end=200902031200
In order to query the last 1000 minute records for Apple for the current day in descending order, execute:
https://historical-quotes.aws.barchart.com/historical/queryminutes.ashx?username=username&password=password&symbol=AAPL&maxrecords=1000&order=desc
In order to query the first 1000 minute records for Apple for the February 3, 2009, in ascending order, execute:
https://historical-quotes.aws.barchart.com/historical/queryminutes.ashx?username=username&password=password&symbol=AAPL&start=20090203&maxrecords=1000&order=asc
In order to query 5-minute interval records for Apple between 9 am and 12 pm on February 3, 2009, execute:
https://historical-quotes.aws.barchart.com/historical/queryminutes.ashx?username=username&password=password&symbol=AAPL&start=200902030900&end=200902031200&interval=5
Minute date range queries return the date range available in the minute database for a comma delimited list of symbols. Only three parameters are supported, and all three are required: username, password, and symbols.
The results consist of three-field records (i.e. SYMBOL,TIMESTAMP_OLDEST_RECORD, TIMESTAMP_MOSTRECENT_RECORD). Symbols that do not exist in the system are simply ignored and no corresponding record is returned. The request handler for minute date range queries is queryminutedaterange.ashx
The following parameters are either required or supported in minute date range queries (required parameters are marked with an asterisk):
Results are returned by minute date range queries in comma delimited text format, one symbol date range record per line, as follows (first timestamp is the oldest record available in the system, and second timestamp is the most recent record available in the system):
SYMBOL,YYYY-MM-DD HH:MM,YYYY-MM-DD HH:MM
Example:
AAPL,2008-05-05 09:30,2011-06-29 19:57 IBM,2008-05-05 09:30,2011-06-29 18:51
In order to query date ranges available in the system for both IBM and AAPL, executes:
https://historical-quotes.aws.barchart.com/historical/queryminutedaterange.ashx?username=username&password=password&symbols=IBM,AAPL
Nearby minute queries are basically identical in functionality and format to <minute queries>, with three important differences:
- They only apply to futures contracts.
- Only the root symbol is used by the query (even though a full contract symbol can be passed in that includes the month and year, both the month and year are ignored). The results of the query will include data for one or more active contracts during the period requested. A contract is considered to be active from (and including) the day of expiration of the previously active contract to (and including) the day prior to its expiration.
- Each record in the result set includes the name of the active contract to which the record belongs, since the different records returned may belong to different contracts.
Except for these three exceptions, everything else works the same way it does for "Minute Queries".
Results are returned by nearby minute queries in comma delimited text format, one minute record per line, as follows:
CONTRACT,YYYY-MM-DD HH:MM,TRADING_DAY,OPEN,HIGH,LOW,CLOSE,VOLUME
Example:
ESU09,2009-09-11 00:13,11,1040,1040,1039.75,1039.75,4
In order to query all the nearby minute records for ES between June 1 and (not including) July 1, 2009, execute:
https://historical-quotes.aws.barchart.com/historical/querynearbyminutes.ashx?username=username&password=password&symbol=ES&start=20090601&end=20090701
In order to query 1-hour interval records for ES between June 1 and (not including) July 1, 2009, execute:
https://historical-quotes.aws.barchart.com/historical/querynearbyminutes.ashx?username=username&password=password&symbol=ES&start=20090601&end=20090701&interval=60
Form T minute queries are basically identical in functionality and format to "Minute Queries", with two important differences:
- They only apply to stocks.
- They include minutes (or aggregated minute intervals) created using Form T trades (pre-/post-market trades). Form T trades are described in Appendix A of the ddf Broadcast Feed documentation, titled ddfplus Processing of Special Sale Conditions.
Except for these two exceptions, everything else works the same way it does for "Minute Queries".
Results are returned by Form T minute queries in comma delimited text format, one minute record per line, as follows:
YYYY-MM-DD HH:MM,TRADING_DAY,OPEN,HIGH,LOW,CLOSE,VOLUME
Example:
2009-09-11 00:13,11,1040,1040,1039.75,1039.75,4
In order to query all the minute records (including Form T trades) for IBM between September 1 and (not including) September 10, 2009, execute:
https://historical-quotes.aws.barchart.com/historical/queryformtminutes.ashx?username=username&password=password&symbol=IBM&start=20090901&end=20090910
In order to query 1-hour interval records (including Form T trades) for IBM between September 1 and (not including) September 10, 2009, execute:
https://historical-quotes.aws.barchart.com/historical/queryformtminutes.ashx?username=username&password=password&symbol=IBM&start=20090901&end=20090910&interval=60
EOD queries return all records (daily, weekly or monthly) for a specified symbol during a specified period between a start and an end date. A maximum number of records to be returned can also be specified along with an end date (the maximum number of records is ignored if a start date is specified). The request handler for EOD queries is queryeod.ashx.
An optional data parameter specifies whether the records returned are daily, weekly or monthly, and whether plain, nearby, or continuation records are returned. If not specified, daily records are returned.
A "nearby record" is the nearest futures contract to expiration at any given date in time. Example: Corn Dec 2008, Corn Sep 2008, Corn July 2008 ...
A "continuation record" is the same contract month over different contract years. Example: Corn Dec 2008, Corn Dec 2007, Corn Dec 2006 ...
Nearby and continuation futures records include price data for the front month contract up to the prior day before expiration.
If both a start and an end date are specified, then all records within the specified period will be returned. If a start date is specified, the maximum number of records is ignored.
If no start date is specified and an end date is specified along with a maximum number of records to be returned, then a number of records up to the maximum number specified or back to the beginning of the available data will be returned, whichever is smaller. If no maximum number of records is specified, then all the records between the end date specified and the beginning of the available data will be returned.
If no end date is specified and a start date is specified all the records between the start date and the most current available data will be returned. The maximum number of records is ignored if a start date is specified.
If no dates and no maximum number of records are specified, then all the available records will be returned. If a maximum number of records is specified, the query will be treated as if the end date is specified to the most current available data (refer to maximum number of records when end date is specified in paragraph above).
To query end-of-day options data the symbol format must follow options symbology structure, which is comprised of the underlying futures symbol including the month and year code followed by a vertical bar "|" followed by the strike, followed by a Call or Put indicator ("C" or "P"). For example, the following symbol is valid for NGH12 600 Call options: NGH12|600C
The following parameters are either required or supported in minute queries (required parameters are marked with an asterisk):
This parameter can be set to one of fifteen values (daily, dailynearest, dailycontinue, weekly, weeklynearest, weeklycontinue, monthly, monthlynearest, monthlycontinue, quarterly, quarterlynearest, quarterlycontinue, yearly, yearlynearest, and yearlycontinue) in order to specify whether daily, weekly, monthly, quarterly or yearly records are to be returned, and whether they should be plain, nearest, or continuation records. Nearest and continuation are ignored for equities, and if specified the query will simply return plain records.
The 'nearest' queries return the total volume by default (&volume=total) but if you desire contract volume, this can be overridden by passing &volume=contract.
A "nearby record" is the nearest futures contract to expiration at any given date in time. Example: Corn Dec 2008, Corn Sep 2008, Corn July 2008 ...
A "continuation record" is the same contract month over different contract years. Example: Corn Dec 2008, Corn Dec 2007, Corn Dec 2006 ...
Note: All times are in Eastern Time for equities and Central Time for everything else.
Results are returned by EOD queries in comma delimited text format, one record per line, as follows:
SYMBOL,YYYY-MM-DD,OPEN,HIGH,LOW,CLOSE,VOLUME[,OPENINTEREST]
Example (fragment of weekly nearest for ESH09):
ESZ08,2008-12-08,872.25,919.25,829,886,3269325,3301807 ESZ08,2008-12-15,883.5,919.25,857.25,881.25,2670206,3198151 ESH09,2008-12-22,884.25,891.5,852.75,869,654227,2287817 ESH09,2008-12-29,869,932.75,853.25,925.5,853185,2344054
Example:
CSCO,2009-02-09,16.99,17.05,16.62,16.85,37633398 CSCO,2009-02-10,16.59,16.93,15.92,16.05,69148797 CSCO,2009-02-11,16.18,16.27,15.85,16.17,46280102 CSCO,2009-02-12,15.97,16.22,15.63,16.2,57651598
Note: open interest does not apply to equities, and is therefore omitted.
In order to query all the daily records for Apple between February 3, 2009, and February 23, 2009 execute:
http://ds01.ddfplus.com/historical/queryeod.ashx?username=username&password=password&symbol=AAPL&start=20090203&end=20090223&data=daily
In order to query the last 10 weekly records for Apple up to the current day execute:
http://ds01.ddfplus.com/historical/queryeod.ashx?username=username&password=password&symbol=AAPL&maxrecords=10&data=weekly
In order to query the last 100 daily nearest records for ESH09 execute:
http://ds01.ddfplus.com/historical/queryeod.ashx?username=username&password=password&symbol=ESH09&maxrecords=100&data=dailynearest
In order to query the 100 daily nearest records up to February 3, 2009 for ESH09 with total volume execute:
http://ds01.ddfplus.com/historical/queryeod.ashx?username=username&password=password&symbol=ESH09&end=20090203&maxrecords=100&data=dailynearest&volume=total
In order to query NGH12 600 Call options from 1/1/12 to 1/31/12 execute:
http://ds01.ddfplus.com/historical/queryeod.ashx?username=username&password=password&symbol=NGH12|600C&start=20120101&end=20120131&order=&data=daily&volume=contract
End of Day date range queries return the date range available in the end of day database for a comma delimited list of symbols. Only three parameters are supported, and all three are required: username, password, and symbols.
The results consist of three-field records (i.e. SYMBOL,DATE_OLDEST_RECORD, DATE_MOSTRECENT_RECORD). Symbols that do not exist in the system are simply ignored and no corresponding record is returned. The request handler for end of day date range queries is queryeoddaterange.ashx
The following parameters are either required or supported in end of day date range queries (required parameters are marked with an asterisk):
Results are returned by end of day date range queries in comma delimited text format, one symbol date range record per line, as follows (first date is the oldest record available in the system, and second date is the most recent record available in the system):
SYMBOL,YYYY-MM-DD,YYYY-MM-DD
Example:
AAPL,1987-10-06,2011-06-29 IBM,1987-10-01,2011-06-29
In order to query date ranges available in the system for both IBM and AAPL, execute:
http://ds01.ddfplus.com/historical/queryeoddaterange.ashx?username=username&password=password&symbols=IBM,AAPL
Event queries return the stock related events for a comma delimited list of symbols. Three parameters are always required: username, password, and symbols.
The results consist of four-field records (i.e. SYMBOL,DATE,EVENT_TYPE,VALUE). Symbols that do not exist in the system are simply ignored and no corresponding record is returned. Optionally, start and end dates can be specified to filter events by date (all records are returned by default if no dates are specified). Also, the type of events to return can be specified setting the parameters splits, dividends, and earnings to true. If no event types are specified, all event types are returned by default. The request handler for event queries is queryevents.ashx
The following parameters are either required or supported in event queries (required parameters are marked with an asterisk):
Note: The above three parameters (splits, dividends and earnings) can be set to true in any combination. If none of the three is specified, the default is to return all available events.
Results are returned by event queries in comma delimited text format, one symbol event record per line, as follows:
SYMBOL,YYYY-MM-DD,EVENT_TYPE,VALUE
Example:
IBM,1999-04-21,Earnings,1.55 IBM,1999-05-27,Split,2-1 IBM,2001-05-08,Dividend,0.14
In order to query all events available in the system for both IBM and AAPL, execute:
http://ds01.ddfplus.com/historical/queryevents.ashx?username=username&password=password&symbols=IBM,AAPL
In order to query all splits available in the system for both IBM and AAPL between 1995 and 2005, execute:
http://ds01.ddfplus.com/historical/queryevents.ashx?username=username&password=password&symbols=IBM,AAPL&splits=true&start=19950101&end=20051231