Data Feed

Premium

The feed parameter allows the user to modify the data feed used for the API's response, forcing it to use cached data.

Our API offers three types of data feeds: live, cached, and delayed. These options are designed to meet diverse user needs, balancing between the immediacy of data and cost efficiency. Below is a detailed overview of each feed type, including examples and use-cases to help you choose the best option for your requirements.

Premium Parameter

This parameter can only be used with paid plans. Free plans and trial plans do not have the ability to control their data feed. Free plans will always receive delayed data.

Live Feed

The live feed provides real-time data, delivering the most current market information available. This option is ideal for scenarios requiring the latest data for immediate decision-making.

Pricing for Live Feed

• Quotes: 1 credit per symbol included in the response that has quote data (bid/ask/mid/last price).
• Candles: 1 credit per 1,000 candles included in the response.
• Bulk Candles: 1 credit per symbol* included in the response.
• Other Endpoints: 1 credit per response.

Requesting Live Data

To request real-time data, append feed=live to your API call or do nothing at all. If you omit the feed query parameter the live feed is used by default. Here's an example:

GET https://api.marketdata.app/v1/options/chain/SPY/?feed=live
GET https://api.marketdata.app/v1/options/chain/SPY/

Both of these requests are equally valid and return the latest data for the specified symbol, ensuring you have up-to-the-second information.

Cached Feed

The cached feed provides data that could be a few seconds to a few minutes old, offering a cost-effective solution for accessing large volumes of quote data. When you use cached data, there is no guarantee of how fresh the data will be. Tickers that are popular with Market Data customers are refreshed more often.

Pricing for Cached Feed

• Quotes: 1 credit per request, regardless of the number of symbols. This makes it an economical choice for bulk data retrieval using endpoints like Option Chain and Bulk Stock Quotes.
• Historical Quotes: Unavailable
• Candles: Unavailable
• Bulk Candles: Unavailable
• Other Endpoints: Unavailable

Use-Case for Cached Feed

The cached feed is perfect for users who need to access recent quote data across multiple symbols without the need for immediate pricing. It allows for significant cost savings, particularly when retrieving data for multiple symbols in a single request.

Requesting Cached Data

To access the cached data, include feed=cached in your API request. For example:

GET https://api.marketdata.app/v1/options/chain/SPY/?feed=cached

This query retrieves data from our cache, offering an affordable way to gather extensive data with a single credit.

Using maxAge with Cached Feed

The maxAge parameter can be used together with feed=cached to set a limit on how old the response data can be. This helps you avoid spending credits on data that may be too stale for your needs.

How maxAge Works

• Purpose: Sets a maximum age limit for cached data
• Behavior: If no recent data is available within the specified age limit, you'll receive a 204 empty response with 0 credit charge
• Format: Accepts either absolute datetimes in any format, or relative time expressions like 1h or 5min

Example Scenarios

Let's assume the last cached data for AAPL options chain is from 3 minutes ago:

Scenario 1: Data within maxAge limit

GET https://api.marketdata.app/v1/options/chain/AAPL/?feed=cached&maxAge=5min

• Result: 203 response with data (1 credit charged)
• Reason: 3-minute-old data is within the 5-minute limit

Scenario 2: Data exceeds maxAge limit

GET https://api.marketdata.app/v1/options/chain/AAPL/?feed=cached&maxAge=1min

• Result: 204 empty response (0 credits charged)
• Reason: 3-minute-old data exceeds the 1-minute limit

Strategic Usage

Using the maxAge parameter allows you to create intelligent fallback logic:

1. First attempt to get cached data with an appropriate maxAge limit
2. If you receive a 204 response, fall back to requesting live data for those specific tickers
3. This approach maximizes cost savings while ensuring data freshness

Cached Feed Response Codes

When the feed=cached parameter is added, the API's response codes are modified slightly. You will no longer get 200 OK responses, but instead 203 and 204 responses:

• 203 NON-AUTHORITATIVE INFORMATION - This response indicates the response was successful and served from our cache server. You can treat this the same as a 200 response.
• 204 NO CONTENT - This response indicates that the request was correct and would ordinarily return a success response, but our caching server does not have any cache data for the symbol requested. Make a live request to fetch real-time data for this symbol.

Delayed Feed

The delayed feed provides data that is delayed by at least 15 minutes. All free and trial accounts receive delayed data by default. Paid accounts can also request delayed data if they wish.

Pricing for Delayed Feed

• Pricing is the same as the live feed.

Requesting Delayed Data

To access delayed data, include feed=delayed in your API request. For example:

GET https://api.marketdata.app/v1/options/chain/SPY/?feed=delayed

This query retrieves data that is at least 15 minutes old.

Feed Comparison

Feature	Live Feed	Cached Feed	Delayed Feed
Data Timeliness	Real-time, up-to-the-second data	Seconds to minutes old	Delayed by 15 minutes
Pricing	1 credit per symbol with quote data	1 credit per request, regardless of symbol count	Same as live feed
Ideal Use-Case	Time-sensitive decisions requiring the latest data	Large volumes of data at lower cost	Non-time-sensitive applications
Default Option	Yes for Paid accounts (if feed parameter is omitted)	No (must specify feed=cached)	Yes for Free and Trial accounts (cannot change feed)
Paid Accounts Access	✅	✅	✅
Free/Trial Accounts Access	❌	❌	✅

• Opt for the live feed when you require the most current data for each symbol, and the immediate freshness of the data justifies the additional credits.
• Select the cached feed for bulk data retrieval or when working with a larger set of symbols, to capitalize on the cost efficiency of retrieving extensive data at a lower price.
• Choose the delayed feed for scenarios where data timeliness is less critical.