Bad Request
Request Line is too large (XXXX > 4094) ``` This is returned by the web server **before** the request reaches the API, so it does not appear in your account's request log and does not consume credits. The cause is exceeding the **4094-byte HTTP request-line limit**. The most common trigger is packing too many tickers into a single multi-symbol call, for example: - `/v1/stocks/prices/?symbols=...` - `/v1/stocks/bulkcandles/D/?symbols=...` ### How many symbols per request There is no application-level cap on symbol count — the ceiling is set entirely by URL length. As a rule of thumb: - An average 4-character ticker plus a separator comma takes 5 bytes. - Path, `token`, `format`, `columns`, and other query parameters typically consume 150–250 bytes of overhead. - That leaves roughly 3,800 bytes for the symbols list — about **700–800 typical-length tickers** before requests begin to fail. To stay clear of the limit, **chunk multi-symbol requests into batches of 500 symbols or fewer.** That leaves headroom for longer tickers (BRK.B, 5-letter Nasdaq tickers) and any additional query parameters you may add later. ### How to fix 1. Reduce the number of symbols in the request. 2. Split your symbol list into multiple smaller calls. 3. If you must send a long list, drop any non-essential query parameters to free up URL space. ## 400 vs Other Status Codes - `400`: request input/format is invalid - `401`: authentication issue (token missing/invalid) - `402`: plan/entitlement limit reached - `403`: forbidden by policy (for example multiple IP addresses) - `404`: request format is valid, but requested resource was not found ## If You Still Get 400 1. Log full request URL and all query parameters 2. Compare request against endpoint docs field-by-field 3. Re-test with only required parameters 4. Add optional parameters back one at a time --- # 400: Invalid Option Symbol Source: https://www.marketdata.app/docs/api/troubleshooting/invalid-option-symbol/index.md Use this page when you receive a `400 BAD REQUEST` with: ```json { "s": "error", "errmsg": "Invalid option symbol. Use valid OCC symbology for the option symbol." } ``` If you need the broader `400` troubleshooting flow, start here: - [400: Bad Request](https://www.marketdata.app/docs/api/troubleshooting/bad-request) ## What This Error Means The endpoint and query string can be valid, but the `optionSymbol` itself is not valid OCC format. ## OCC Option Symbol Format Expected format: `UNDERLYING + YYMMDD + C/P + STRIKE` Example: - `AAPL271217C00250000` Field rules: 1. `UNDERLYING`: Root symbol (for example `AAPL`, `SPY`, `INTC`) 2. `YYMMDD`: Expiration date (2-digit year, month, day) 3. `C/P`: `C` for call or `P` for put 4. `STRIKE`: 8 digits, zero-padded, implied 3 decimal places ## Strike Encoding Reference The strike is represented as an integer with three implied decimal places. Examples: - `150` becomes `00150000` - `32.5` becomes `00032500` - `32.25` becomes `00032250` ## Common Construction Errors 1. Expiration is not in `YYMMDD` 2. Missing call/put flag (`C` or `P`) 3. Strike field is not 8 digits 4. Strike is not zero-padded 5. Decimal strike is encoded incorrectly 6. Legacy pre-2010 style symbol is used ## Validate Before Calling Quotes/History Use the lookup endpoint to build/validate a symbol first. ```http # Build/validate OCC symbol from human-readable contract GET https://api.marketdata.app/v1/options/lookup/AAPL%201/17/2025%20150%20Call # Then request data with the returned optionSymbol GET https://api.marketdata.app/v1/options/quotes/AAPL271217C00250000/ ``` ## 400 vs 404 for Options - `400`: the option symbol format is invalid - `404`: format is valid, but no matching contract/data was found ## Quick Debug Checklist 1. Log the exact `optionSymbol` your client sent 2. Check `YYMMDD`, `C/P`, and 8-digit strike encoding 3. Validate with `options/lookup` 4. Reuse the exact returned symbol in follow-up requests --- # Logging Source: https://www.marketdata.app/docs/api/troubleshooting/logging/index.md ## Why Logging is Important Logging our API's responses is crucial for monitoring the behavior of your application and troubleshooting problems, either with our API or your usage of the API. ### What Should Be Logged Market Data responds to successful requests with either a 200 or 203 status code. Therefore, we recommend you log any response that doesn't have a 2xx status code. Successful responses may be logged if you wish, but normally this is not necessary. When logging errors, the log should include the exact request made, Market Data's response, and the CF-Ray header. ## Logging Examples ### JavaScript ```js title="logger.js" import { MarketDataClient, DefaultLogger, LogLevel } from "@marketdata/sdk"; // Enable DEBUG-level logging to capture full request/response diagnostics // (including the CF-Ray header) for every API call. const client = new MarketDataClient({ logger: new DefaultLogger(LogLevel.DEBUG), }); try { const quotes = await client.stocks.quotes("AAPL"); console.log(quotes); } catch (error) { // The SDK logs the failing request and response automatically; // handle the error here as needed. console.error(error); } ``` ### TypeScript ```typescript title="logger.ts" import { MarketDataClient, DefaultLogger, LogLevel } from "@marketdata/sdk"; import type { StockQuote } from "@marketdata/sdk"; // Enable DEBUG-level logging to capture full request/response diagnostics // (including the CF-Ray header) for every API call. const client = new MarketDataClient({ logger: new DefaultLogger(LogLevel.DEBUG), }); try { const quotes: StockQuote[] = await client.stocks.quotes("AAPL"); console.log(quotes); } catch (error) { // The SDK logs the failing request and response automatically; // handle the error here as needed. console.error(error); } ``` ### Python ```python title="logger.py" from marketdata import MarketDataClient, MarketDataClientErrorResult import json # Make the API request using the SDK client = MarketDataClient() result = client.stocks.quotes("AAPL") # Check if the result is an error (SDK handles HTTP errors internally) if isinstance(result, MarketDataClientErrorResult): log_data = { "request": f"GET https://api.marketdata.app/v1/stocks/quotes/AAPL/", "response": str(result.error), "cf_ray_header": "Not available" # CF-Ray is handled internally by the SDK } # Save to a logfile with open("api_error_log.json", "a") as logfile: logfile.write(json.dumps(log_data) + "\n") ``` ### Java ```java title="Logger.java" import com.marketdata.sdk.MarketDataClient; import com.marketdata.sdk.exception.MarketDataException; import com.marketdata.sdk.stocks.StockQuotesRequest; // Enable DEBUG logging by setting MARKETDATA_LOGGING_LEVEL=DEBUG in your // environment. The SDK then logs full request/response diagnostics (including // the CF-Ray request id) on the "com.marketdata.sdk" java.util.logging logger. try (MarketDataClient client = new MarketDataClient()) { var quotes = client.stocks().quotes(StockQuotesRequest.of("AAPL")); System.out.println(quotes.values()); } catch (MarketDataException e) { // The SDK already logged the failing request/response. getSupportInfo() // bundles the status code, request URL and request id for a bug report. System.err.println(e.getSupportInfo()); } ``` ### Kotlin ```kotlin title="Logger.kt" import com.marketdata.sdk.MarketDataClient import com.marketdata.sdk.exception.MarketDataException import com.marketdata.sdk.stocks.StockQuotesRequest // Enable DEBUG logging via the MARKETDATA_LOGGING_LEVEL=DEBUG environment // variable; the SDK logs request/response diagnostics on "com.marketdata.sdk". MarketDataClient().use { client -> try { val quotes = client.stocks().quotes(StockQuotesRequest.of("AAPL")) println(quotes.values()) } catch (e: MarketDataException) { System.err.println(e.supportInfo) } } ``` ### C# ```csharp title="Logger.cs" using MarketDataApp; using MarketDataApp.Exceptions; using Microsoft.Extensions.Logging; // Enable DEBUG logging by setting MARKETDATA_LOGGING_LEVEL=DEBUG in your environment. // The SDK then emits full request/response diagnostics (including the CF-Ray request // id) as structured Microsoft.Extensions.Logging events through the logger you attach. using var loggerFactory = LoggerFactory.Create(builder => builder.AddMarketDataCanonicalConsole()); var options = MarketDataClientOptions.FromEnvironment() .WithLogger(loggerFactory.CreateLoggerhttps://api.marketdata.app/v1/stocks/quotes/SPY/?token=token1234&dateformat=timestamp- **Protocol**: `https://` - **Host**: `api.marketdata.app` - **Path (or Endpoint)**: `/v1/stocks/quotes/SPY/` - **Query String**: Begins with a `?` and includes `token=token1234&dateformat=timestamp` - `token` and `dateformat` are the names of the parameters. - `token1234` and `timestamp` are the values assigned to those parameters. - `&` is used to separate multiple parameters. ### What Goes In The Path - Required route values like symbols, ids, or endpoint-specific path parts. - Example: `/v1/stocks/quotes/SPY/` ### What Goes In The Query String - Optional controls like `token`, `dateformat`, `limit`, and similar parameters. - Query values always use `key=value` form. - Multiple parameters are separated by `&`. ## How to Build URL Parameters When building URL parameters, follow these guidelines to ensure they are structured correctly: 1. **Start with the Endpoint URL**: Identify the base URL of the API endpoint you are interacting with. 2. **Add a Question Mark**: Follow the base URL with a `?` to start the query string. 3. **Append Parameters**: Add parameters in the format `key=value`. Use `&` to separate multiple parameters. 4. **Encode Special Characters**: Use URL encoding to handle special characters in keys or values. ### Example Suppose you want to request stock quotes for `SPY` with a specific date format and token authentication: ``` https://api.marketdata.app/v1/stocks/quotes/SPY/?token=token1234&dateformat=timestamp ``` ### Common Mistakes - **Incorrect Character Usage**: Ensure you use `?` to start and `&` to separate parameters. - **Unencoded Characters**: Encode special characters like spaces (`%20`), plus (`%2B`), etc, using URL encoding. --- # Universal Parameters Source: https://www.marketdata.app/docs/api/universal-parameters/index.md The following parameters are universal and can be used with any endpoint unless otherwise indicated in that endpoint's documentation. --- # Columns Source: https://www.marketdata.app/docs/api/universal-parameters/columns/index.md The columns parameter is used to limit the results of any endpoint to only the columns you need. ## Parameter ## Use Example ``` https://api.marketdata.app/v1/stocks/quotes/AAPL/?columns=ask,bid ``` ## Response Example ```json { "ask": [152.14], "bid": [152.12] } ``` ## Values ### string Use a list of columns names separated by commas to limit the response to just the columns requested. > [!CAUTION] > > When using the columns parameter the `s` status output is suppressed from the response. --- # Date Format Source: https://www.marketdata.app/docs/api/universal-parameters/date-format/index.md The dateformat parameter allows you to specify the format you wish to receive date and time information in. Regardless of format, all timestamps for US markets use the **America/New_York** timezone. See [Response Timezone](https://www.marketdata.app/docs/docs/api/dates-and-times#response-timezone) for full details on timezone handling. ## Parameter dateformat=\
(
symbol: string,
params?: P,
): MarketDataPromise (
params: P & { symbol: string },
): MarketDataPromise (
params?: P,
): MarketDataPromise (
symbol: string,
params?: P,
): MarketDataPromise (
params: P & { symbol: string },
): MarketDataPromise (
symbol: string,
params?: P,
): MarketDataPromise (
params: P & { symbol: string },
): MarketDataPromise (
lookupStr: string,
params?: P,
): MarketDataPromise (
params: P & { lookup: string },
): MarketDataPromise (
symbols: string | string[],
params?: P,
): MarketDataPromise (
params: P & { symbols: string | string[] },
): MarketDataPromise (
symbol: string,
params?: P,
): MarketDataPromise (
params: P & { symbol: string },
): MarketDataPromise (
symbol: string,
params?: P,
): MarketDataPromise (
params: P & { symbol: string },
): MarketDataPromise (
symbol: string,
params?: P,
): MarketDataPromise (
params: P & { symbol: string },
): MarketDataPromise (
symbols: string | string[],
params?: P,
): MarketDataPromise (
params: P & { symbols: string | string[] },
): MarketDataPromise (
symbols: string | string[],
params?: P,
): MarketDataPromise (
params: P & { symbols: string | string[] },
): MarketDataPromise
](https://app.getpostman.com/run-collection/27146376-b1331cd2-4749-4708-96fe-2f1708b02854?action=collection%2Ffork&source=rip_markdown&collection-url=entityId%3D27146376-b1331cd2-4749-4708-96fe-2f1708b02854%26entityType%3Dcollection%26workspaceId%3Dbd65af1d-3c36-4e62-ae64-f71008c154b4)
## Getting Started
Follow these steps to get started:
1. **Open**: Open the collection in Postman using the link above.
2. **Fork the Collection**: Fork the collection so you can work with your own local copy.
3. **Watch Original Collection**: When you fork the collection, ensure that you are watching the original collection to receive updates.
4. **Add Your Token**: Add your Market Data token as a variable in the Authorization tab.
## Keeping Up To Date
Here's a step-by-step guide to help you keep your forked Postman collection up to date:
### Step 1: Monitor the Original Collection for Updates
1. **Stay Informed**: If you are subscribed to our newsletter, you will recieve our monthly changelog with updates and new endpoints. We send out monthly notifications to all newsletter subscribers. If you do not wish to subscribe, you can review our changelog on the web.
2. **Change Log**: Review the [Market Data Changelog](https://roadmap.marketdata.app/changelog) and release notes to identify when we've made updates or released new endpoints.
### Step 2: Pull Changes from the Original Collection
1. **Navigate to Your Forked Collection**: Open Postman and go to your workspace where the forked collection is located.
2. **Find the Pull Changes Option**: Click on the three dots (...) next to your forked collection to open the collection options. Look for an option to pull changes or merge updates from the original collection. This option is available if there have been updates to the original collection after you forked it.
3. **Review and Pull Changes**: Depending on your version of Postman, you may be allowed to review the changes before pulling them. You can then confirm to pull the changes, which will update your forked collection with the new requests or modifications from the original.
#### Screenshot
---
# Python SDK
Source: https://www.marketdata.app/docs/sdk/py/index.md
Welcome to the Market Data Python SDK documentation. This SDK allows you to easily integrate Market Data services into your Python applications.
## Open Source
The SDK is completely open source under the MIT license and is available on GitHub. Feel free to contribute to the project, report bugs, or request new features.
- [Python SDK GitHub](https://github.com/MarketDataApp/sdk-py/)
- [Python SDK PyPI](https://pypi.org/project/marketdata-sdk-py/)
## Documentation
The best source for documentation on the SDK is right here. This documentation is the most up-to-date and accurate source of information on the SDK.
## Using the SDK
This SDK is designed to help you get up and running with Market Data's APIs as quickly as possible, providing you with all the tools you need to access real-time stock and options prices, historical data, and much more.
### Getting Started
1. [Install the SDK](https://www.marketdata.app/docs/sdk/py/installation) with the appropriate dependencies for your needs.
2. Set up your [authentication token](https://www.marketdata.app/docs/sdk/py/authentication) to access the API.
3. Learn about the [client](https://www.marketdata.app/docs/sdk/py/client) and how to make your first API requests.
4. Configure [Settings](https://www.marketdata.app/docs/sdk/py/settings) to customize output format, date format, and other universal parameters.
5. Explore the available endpoints for [stocks](https://www.marketdata.app/docs/sdk/py/stocks), [options](https://www.marketdata.app/docs/sdk/py/options), [funds](https://www.marketdata.app/docs/sdk/py/funds), and [markets](https://www.marketdata.app/docs/sdk/py/markets).
### Support
- If you have any questions or need further assistance, please don't hesitate to open a ticket at our [helpdesk](https://www.marketdata.app/dashboard/).
- If you find a bug you may also [open an issue in our GitHub repository](https://github.com/MarketDataApp/sdk-py/issues). Please only open issues if you find a bug. Use our helpdesk for general questions or implementation assistance.
---
# Authentication (Python SDK)
Source: https://www.marketdata.app/docs/sdk/py/authentication/index.md
The Market Data API uses a **Bearer Token** for authentication. The token is required for each request you make to the API. Your token should have been e-mailed to you when you first signed up for an account. If you do not have a token or have lost your sign-up email, request a new token from the [Market Data Dashboard](https://www.marketdata.app/dashboard/).
There are two ways to set your token when using the Python SDK:
1. Set it from an environment variable _(recommended)_
2. Pass it directly when creating the [client](https://www.marketdata.app/docs/sdk/py/client)
On startup, the SDK will look for the environment variable. If found, it will use the token for all requests. If the environment variable is not found, you will need to pass the token when creating the [client](https://www.marketdata.app/docs/sdk/py/client).
> [!TIP]
> When your code is running in a production environment, we recommend using an environment variable to ensure your token is not stored with your code. This is the most secure way to set your token.
## How To Set-Up The Environment Variable
Set the token in the environment variable `MARKETDATA_TOKEN`. Alternatively, you can pass it directly when creating the client, but please be aware that this is not secure and could pose a risk if your code is shared.
### Set The Environment Variable In The Console
After setting the variable, run your code to make a test request. If you have set the variable correctly, you should see the output of the test request. If you see an error, double-check that you have set the variable correctly.
### Mac / Linux
This command should be run in the terminal. It sets the environment variable for the current session only. If you open a new terminal window or restart your computer, the environment variable will not persist.
```bash
export MARKETDATA_TOKEN="your_api_token"
```
#### Verify the Variable
To verify that the MARKETDATA_TOKEN environment variable has been set properly on Mac OS or Linux, follow these steps:
1. Open a terminal.
2. Type the following command and press Enter: `echo $MARKETDATA_TOKEN`
3. If the environment variable has been set correctly, this command will output the value of MARKETDATA_TOKEN to the terminal. If the variable has not been set or an error occurred, the output will be blank, indicating that the variable is not set.
#### Make The Variable Persistent
To make the environment variable persistent across sessions, you need to add the export command to your shell's profile script (e.g., `~/.bash_profile`, `~/.bashrc`, `~/.zshrc`, etc.) depending on the shell you are using.
> [!TIP]
>
> To find out what shell you are using, you can open your terminal and enter the following command: `echo $SHELL` This command will output the path to the current shell being used, such as `/bin/bash`, `/bin/zsh`, or another shell. The last part of the path indicates the shell type (e.g., bash, zsh).
After adding the command to the appropriate profile script, you will need to either restart your terminal or source the profile script with a command like `source ~/.bash_profile` (adjusting the file name as necessary for your shell) to apply the changes.
##### Verify Variable Persistence
If you have made the environment variable persistent by adding it to your shell's profile script (e.g., ~/.bash_profile, ~/.bashrc, ~/.zshrc), you can verify that the variable persists across sessions by:
1. Closing the current terminal.
2. Opening a new terminal.
3. Running the `echo $MARKETDATA_TOKEN` command again to check if the variable is still set.
If the variable is not present after restarting the terminal, ensure you have correctly added the export command to the appropriate profile script and that you have either restarted the terminal or sourced the profile script with a command like `source ~/.bash_profile` (adjusting the file name as necessary for your shell).
### Windows
This command should be run in the Command Prompt on Windows. Note that after using setx, the environment variable will be set permanently but will not be available in the current Command Prompt session. You will need to start a new session to see the change.
```bash
setx MARKETDATA_TOKEN "your_api_token" # Windows
```
#### Verify The Variable
To verify that the MARKETDATA_TOKEN environment variable has been set properly on Windows, the follow these steps:
1. Open a new Command Prompt session (since the setx command does not affect the current session where it was run).
2. Type the following command and press Enter: `echo %MARKETDATA_TOKEN%`
3. If the environment variable has been set correctly, this command will output the value of MARKETDATA_TOKEN to the console. If the variable has not been set or an error occurred, it will likely output `%MARKETDATA_TOKEN%` indicating that the variable substitution did not happen.
4. The next step is to ensure the SDK is correctly utilizing the token. To do this, the use the provided test code to make a request to the Market Data API. If the request is successful and returns the expected data, it confirms that the SDK is correctly reading and using the MARKETDATA_TOKEN environment variable.
### Using a .env File
You can also create a `.env` file in your project root:
```ini
MARKETDATA_TOKEN=your_api_token
```
The SDK will automatically load this file if you have `python-dotenv` installed.
### Make A Test Request
Use the following test code to verify that your authentication is working by making a test request to SPY or any other symbol that requires authentication. Do not use AAPL to test your authentication because AAPL is a free test symbol and will return data even if you are not authenticated properly.
```python
from marketdata import MarketDataClient, MarketDataClientErrorResult
# No need to set a token here, the SDK will read it
# from the environment variable automatically.
# Initialize the client (see client documentation for details)
client = MarketDataClient()
# Make a test request
quotes = client.stocks.quotes("SPY")
# Check if the result is an error
if isinstance(quotes, MarketDataClientErrorResult):
print(f"Error occurred: {quotes.error}")
else:
# Print the quotes
print(quotes)
```
If your token is set correctly, you should see the output of the test request. If you see an error, double-check that you have set the token correctly.
## How To Create a Client and Assign a Token Directly
If you decide to pass the token directly when creating the client, you can do so by passing it as a parameter. This is not recommended for production code.
### Example Code
```python
from marketdata import MarketDataClient, MarketDataClientErrorResult
# Replace with your token
token = "your_token_here"
# Create a new client and set the token
client = MarketDataClient(token=token)
# Make a test request to SPY
quotes = client.stocks.quotes("SPY")
# Check if the result is an error
if isinstance(quotes, MarketDataClientErrorResult):
print(f"Error occurred: {quotes.error}")
else:
# Print the quotes
print(quotes)
```
## Next Steps
After successful authentication, you will be able to begin making requests to the Market Data API. We recommend reading the brief overview of how the [client](https://www.marketdata.app/docs/sdk/py/client) works, so you can get familiar with interacting with the SDK. The SDK includes methods for each endpoint that allow you to retrieve data. Use any of the endpoints in the SDK to make requests to the API.
You may also want to configure [Settings](https://www.marketdata.app/docs/sdk/py/settings) to customize output format, date format, and other universal parameters.
---
# Client (Python SDK)
Source: https://www.marketdata.app/docs/sdk/py/client/index.md
The Market Data Python Client includes functionality for making API requests, handling responses, managing rate limits, and logging. The SDK supports various data types including stocks, options, funds, and market status information.
## Get Started Quickly with the MarketDataClient
1. Review the [documentation on authentication](https://www.marketdata.app/docs/sdk/py/authentication) to learn how to set your API token.
2. Create a [`MarketDataClient`](#marketdataclient) instance and use it to make requests to the Market Data API.
3. Make a test request and review the console output. The SDK includes logging capabilities to help you debug requests.
4. Check the [rate limit](#accessing-rate-limits) in the client to track credit usage and how many API credits remain.
5. Configure [Settings](https://www.marketdata.app/docs/sdk/py/settings) to customize output format, date format, and other universal parameters.
## MarketDataClient
```python
class MarketDataClient:
def __init__(self, token: str = None, logger: Logger = None):
...
```
[MarketDataClient](#marketdataclient) is the main client class for interacting with the Market Data API. It provides access to all resources (stocks, options, funds, markets) and handles authentication, rate limiting, and request management.
### Properties
- `token` (str): The authentication token for API requests. See [authentication documentation](https://www.marketdata.app/docs/sdk/py/authentication) for details.
- `rate_limits` ([UserRateLimits](#accessing-rate-limits)): Current rate limit information
- `base_url` (str): The base URL for API requests
- `api_version` (str): The API version to use
- `headers` (dict): HTTP headers including Authorization and User-Agent
- `default_params` ([UserUniversalAPIParams](https://www.marketdata.app/docs/sdk/py/settings)): Default universal parameters for API requests. See [Settings](https://www.marketdata.app/docs/sdk/py/settings) for details on configuring these parameters.
### Resources
- `stocks` ([StocksResource](https://www.marketdata.app/docs/sdk/py/stocks)): Access to stocks endpoints (prices, quotes, candles, earnings, news)
- `options` ([OptionsResource](https://www.marketdata.app/docs/sdk/py/options)): Access to options endpoints (chain, expirations, quotes, lookup)
- `funds` ([FundsResource](https://www.marketdata.app/docs/sdk/py/funds)): Access to funds endpoints (candles)
- `markets` ([MarketsResource](https://www.marketdata.app/docs/sdk/py/markets)): Access to markets endpoints (status)
### Methods
- `__init__(token=None, logger=None)`
Creates a new MarketDataClient instance.
### __init__
```python
def __init__(self, token: str = None, logger: Logger = None)
```
Creates and configures a new MarketDataClient instance with default settings. This method initializes the client with the provided token (or reads it from the `MARKETDATA_TOKEN` environment variable), sets up HTTP client configuration, and initializes rate limits by making a request to the `/user/` endpoint.
#### Parameters
- `token` (str, optional)
The authentication token for API requests. If not provided, the SDK will attempt to read it from the `MARKETDATA_TOKEN` environment variable.
- `logger` (`logging.Logger`, optional)
A custom logger instance from Python's `logging` module. If not provided, the SDK will use its default logger. You can create a custom logger using `marketdata.logger.get_logger()`.
#### Returns
- `MarketDataClient`
A new MarketDataClient instance ready to make API requests.
#### Notes
- The client automatically fetches rate limits during initialization by making a request to `/user/` endpoint.
- The client includes a User-Agent header with the format `marketdata-py-{version}` (e.g., `marketdata-py-0.0.1`).
- All requests include an `Authorization: Bearer {token}` header.
- The client uses `httpx.Client` for HTTP requests with automatic connection pooling.
#### Example
```python
from marketdata import MarketDataClient
# Token will be automatically obtained from MARKETDATA_TOKEN environment variable
client = MarketDataClient()
# Or provide the token explicitly
client = MarketDataClient(token="your_token_here")
# You can also provide a custom logger
from marketdata.logger import get_logger
custom_logger = get_logger()
client = MarketDataClient(token="your_token_here", logger=custom_logger)
```
## Accessing Rate Limits
The client automatically fetches and tracks rate limits from the API. Rate limits are initialized when the client is created by making a request to `/user/` endpoint, and are updated after each API request based on response headers.
You can access current rate limits:
```python
client = MarketDataClient()
# Access current rate limits
rate_limits = client.rate_limits
# Access individual fields
print(f"Limit: {rate_limits.requests_limit}")
print(f"Remaining: {rate_limits.requests_remaining}")
print(f"Consumed: {rate_limits.requests_consumed}")
print(f"Reset at: {rate_limits.requests_reset}")
# Or use the formatted string representation
print(rate_limits) # Shows: "Rate used X/Y, remaining: Z credits, next reset: ISO timestamp"
```
**Note:** Rate limits are tracked via the following response headers:
- `x-api-ratelimit-limit`: Total API credits allowed
- `x-api-ratelimit-remaining`: Number of API credits remaining
- `x-api-ratelimit-consumed`: Number of API credits consumed
- `x-api-ratelimit-reset`: Unix timestamp when the rate limit resets
The `requests_reset` field is automatically converted to a `datetime.datetime` object for easier use.
## Configuration
The SDK supports flexible configuration of universal parameters through multiple methods. You can configure settings like output format, date format, data mode, and more. See the [Settings](https://www.marketdata.app/docs/sdk/py/settings) documentation for complete details on all available configuration options and how to use them.
---
# Funds (Python SDK)
Source: https://www.marketdata.app/docs/sdk/py/funds/index.md
The Python SDK from Market Data provides methods designed to streamline your use of the following Funds endpoints. These intuitive methods provide a seamless interface for accessing funds data.
## Funds Endpoints
---
# Fund Candles (Python SDK)
Source: https://www.marketdata.app/docs/sdk/py/funds/candles/index.md
Retrieve historical price candles for any supported fund symbol.
## Making Requests
Use the `candles()` method on the `funds` resource to fetch fund candles. The method supports multiple output formats:
| Output Format | Return Type | Description |
|---------------|----------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------|
| **DATAFRAME** | `pandas.DataFrame` or `polars.DataFrame` | Returns a DataFrame with candles data (default). |
| **INTERNAL** | `list[FundsCandle]` or `list[FundsCandlesHumanReadable]` | Returns a list of FundsCandle objects. When `use_human_readable=True`, returns a list of FundsCandlesHumanReadable objects with capitalized field names. |
| **JSON** | `dict` | Returns the raw JSON response as a dictionary. |
| **CSV** | `str` | Writes CSV data to file and returns the filename string. |
## candles
```python
def candles(
symbol: str,
*,
resolution: str = "D",
from_date: str | datetime.datetime = None,
to_date: str | datetime.datetime = None,
date: str | datetime.datetime = None,
countback: int = None,
output_format: OutputFormat = OutputFormat.DATAFRAME,
date_format: DateFormat = None,
columns: list[str] = None,
add_headers: bool = None,
use_human_readable: bool = False,
mode: Mode = None,
filename: str | Path = None,
) -> list[FundsCandle] | list[FundsCandlesHumanReadable] | dict | str | MarketDataClientErrorResult
```
Fetches historical candles (OHLC) data for a fund symbol. The `symbol` parameter can be passed as the first positional argument or as a keyword argument. All other parameters must be keyword-only.
### Parameters
- `symbol` (str)
The fund symbol for which to fetch candles data.
- `resolution` (str, optional)
The granularity of the candle data (e.g., "1D", "1W", "1M"). Defaults to `"D"` (daily).
- `from_date` (str | datetime.datetime, optional)
Start date for the date range.
- `to_date` (str | datetime.datetime, optional)
End date for the date range.
- `date` (str | datetime.datetime, optional)
Specific date for the candles data.
- `countback` (int, optional)
Number of candles to return, counting backwards from the `to_date`.
- `output_format` ([OutputFormat](https://www.marketdata.app/docs/sdk/py/settings#output-format), optional)
The format of the returned data. Defaults to `OutputFormat.DATAFRAME`. See [Settings](https://www.marketdata.app/docs/sdk/py/settings) for details.
- `date_format` ([DateFormat](https://www.marketdata.app/docs/sdk/py/settings#date-format), optional)
The date format to use in the response. Defaults to `DateFormat.UNIX`. See [Settings](https://www.marketdata.app/docs/sdk/py/settings) for details.
- [`columns`](https://www.marketdata.app/docs/sdk/py/settings#columns) (optional)
Specify which columns to include in the response. See [Settings](https://www.marketdata.app/docs/sdk/py/settings) for details.
- [`add_headers`](https://www.marketdata.app/docs/sdk/py/settings#headers) (optional)
Whether to include headers in the response. See [Settings](https://www.marketdata.app/docs/sdk/py/settings) for details.
- [`use_human_readable`](https://www.marketdata.app/docs/sdk/py/settings#human-readable) (optional)
Whether to use human-readable format for values. Only applies when `output_format=OutputFormat.INTERNAL`. See [Settings](https://www.marketdata.app/docs/sdk/py/settings) for details.
- `mode` ([Mode](https://www.marketdata.app/docs/sdk/py/settings#data-mode), optional)
The data mode to use. See [Settings](https://www.marketdata.app/docs/sdk/py/settings) for details.
- `filename` (str | Path, optional)
File path for CSV output (only used with `output_format=OutputFormat.CSV`).
### Returns
- `list[FundsCandle]` | `list[FundsCandlesHumanReadable]` | `dict` | `str` | `MarketDataClientErrorResult`
The candles data in the requested format, or a `MarketDataClientErrorResult` if an error occurred.
### Example (DataFrame)
```python
from marketdata import MarketDataClient
client = MarketDataClient()
# Get fund candles as DataFrame (default)
# symbol can be passed positionally or as keyword
df = client.funds.candles("VFINX")
# or
df = client.funds.candles(symbol="VFINX")
# Get candles for a date range
df = client.funds.candles(
"VFINX",
resolution="1D",
from_date="2023-01-01",
to_date="2023-01-31"
)
print(df)
```
### Example (Internal)
```python
from marketdata import MarketDataClient, OutputFormat
client = MarketDataClient()
# Get fund candles as internal objects
candles = client.funds.candles(
"VFINX",
resolution="1D",
from_date="2023-01-01",
to_date="2023-01-31",
output_format=OutputFormat.INTERNAL
)
# Access individual candle properties
for candle in candles:
print(f"Time: {candle.t}")
print(f"Open: {candle.o}")
print(f"High: {candle.h}")
print(f"Low: {candle.l}")
print(f"Close: {candle.c}")
```
### Example (JSON)
```python
from marketdata import MarketDataClient, OutputFormat
client = MarketDataClient()
# Get fund candles as JSON
candles = client.funds.candles(
"VFINX",
resolution="1D",
from_date="2023-01-01",
to_date="2023-01-31",
output_format=OutputFormat.JSON
)
print(candles)
```
### Example (CSV)
```python
from marketdata import MarketDataClient, OutputFormat
from pathlib import Path
client = MarketDataClient()
# Get fund candles as CSV
csv_file = client.funds.candles(
"VFINX",
resolution="1D",
from_date="2023-01-01",
to_date="2023-01-31",
output_format=OutputFormat.CSV,
filename=Path("funds_candles.csv")
)
print(f"CSV file saved to: {csv_file}")
```
### Example (Human Readable)
```python
from marketdata import MarketDataClient, OutputFormat
client = MarketDataClient()
# Get fund candles in human-readable format
candles = client.funds.candles(
"VFINX",
resolution="1D",
from_date="2023-01-01",
to_date="2023-01-31",
output_format=OutputFormat.INTERNAL,
use_human_readable=True
)
# Access individual candle properties
for candle in candles:
print(f"Date: {candle.Date}")
print(f"Open: {candle.Open}")
print(f"High: {candle.High}")
print(f"Low: {candle.Low}")
print(f"Close: {candle.Close}")
```
## FundsCandle
```python
@dataclass
class FundsCandle:
t: datetime.datetime
o: float
h: float
l: float
c: float
```
FundsCandle represents a single fund candle (OHLC data), encapsulating price information for a specific time period.
### Properties
- `t` (datetime.datetime): The timestamp for the candle (automatically converted from Unix timestamp).
- `o` (float): The opening price.
- `h` (float): The highest price.
- `l` (float): The lowest price.
- `c` (float): The closing price.
### Notes
- The `t` field is automatically converted to a `datetime.datetime` object from a Unix timestamp.
## FundsCandlesHumanReadable
```python
@dataclass
class FundsCandlesHumanReadable:
Date: datetime.datetime
Open: float
High: float
Low: float
Close: float
```
FundsCandlesHumanReadable represents a fund candle in human-readable format with capitalized field names and formatted values.
### Properties
- `Date` (datetime.datetime): The timestamp for the candle (automatically converted from Unix timestamp).
- `Open` (float): The opening price.
- `High` (float): The highest price.
- `Low` (float): The lowest price.
- `Close` (float): The closing price.
### Notes
- The `Date` field is automatically converted to a `datetime.datetime` object from a Unix timestamp.
- Field names use capitalized format (e.g., `Open` instead of `o`, `Date` instead of `t`).
---
# Installation (Python SDK)
Source: https://www.marketdata.app/docs/sdk/py/installation/index.md
This guide will help you install the Market Data Python SDK and configure it for your needs.
## Prerequisites
- Python >= 3.10
## Basic Installation
Install the Market Data Python SDK from PyPI:
### pip
```bash
pip install marketdata-sdk-py
```
### uv
```bash
uv pip install marketdata-sdk-py
```
## Installation with DataFrame Support
The SDK supports multiple DataFrame libraries for `OutputFormat.DATAFRAME`. To use DataFrame output format, you need to install at least one DataFrame library.
### Install with pandas (recommended)
### pip
```bash
pip install "marketdata-sdk-py[pandas]"
```
### uv
```bash
uv pip install "marketdata-sdk-py[pandas]"
```
### Install with polars
### pip
```bash
pip install "marketdata-sdk-py[polars]"
```
### uv
```bash
uv pip install "marketdata-sdk-py[polars]"
```
### Install with both pandas and polars
### pip
```bash
pip install "marketdata-sdk-py[pandas,polars]"
```
### uv
```bash
uv pip install "marketdata-sdk-py[pandas,polars]"
```
## Optional Dependencies
The SDK supports multiple DataFrame libraries for `OutputFormat.DATAFRAME`. You must install at least one of the following:
- **pandas** (recommended): `pandas>=2.3.3`
- **polars**: `polars-lts-cpu>=1.33.1`
### DataFrame Handler Priority
When using `OutputFormat.DATAFRAME`, the SDK automatically selects an available DataFrame library in the following order:
1. **pandas** (if installed)
2. **polars** (if pandas is not installed)
If neither pandas nor polars is installed, a `ValueError` will be raised when attempting to use `OutputFormat.DATAFRAME`:
```python
ValueError: No dataframe output handler found
```
> [!NOTE]
> You can use other output formats (`OutputFormat.INTERNAL`, `OutputFormat.JSON`, `OutputFormat.CSV`) without installing pandas or polars.
## Local Development Installation
For local development, install from the project directory:
```bash
# Clone the repository
git clone https://github.com/MarketDataApp/sdk-py.git
cd sdk-py
# Install the package
pip install .
# Or install with optional dependencies
pip install ".[pandas]"
```
## Core Dependencies
The SDK includes the following core dependencies (installed automatically):
- `httpx>=0.28.1`: HTTP client library for making API requests
- `pydantic>=2.12.5`: Data validation and settings management
- `pydantic-settings>=2.12.0`: Configuration management from environment variables
- `tenacity>=9.1.2`: Retry logic library for handling transient errors
## Next Steps
After installation, you'll need to:
1. Set up your [authentication token](https://www.marketdata.app/docs/sdk/py/authentication)
2. Learn about the [client](https://www.marketdata.app/docs/sdk/py/client) and how to make your first API requests
3. Configure [settings](https://www.marketdata.app/docs/sdk/py/settings) to customize output format, date format, and other universal parameters
---
# Markets (Python SDK)
Source: https://www.marketdata.app/docs/sdk/py/markets/index.md
The Python SDK from Market Data provides methods designed to streamline your use of the following Markets endpoints. These intuitive methods provide a seamless interface for accessing market status information.
## Markets Endpoints
---
# Market Status (Python SDK)
Source: https://www.marketdata.app/docs/sdk/py/markets/status/index.md
Retrieve market status information (open/closed) for dates and countries.
## Making Requests
Use the `status()` method on the `markets` resource to fetch market status information. The method supports multiple output formats:
| Output Format | Return Type | Description |
|---------------|-----------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------|
| **DATAFRAME** | `pandas.DataFrame` or `polars.DataFrame` | Returns a DataFrame with market status data (default). |
| **INTERNAL** | `list[MarketStatus]` or `list[MarketStatusHumanReadable]` | Returns a list of MarketStatus objects. When `use_human_readable=True`, returns a list of MarketStatusHumanReadable objects with capitalized field names. |
| **JSON** | `dict` | Returns the raw JSON response as a dictionary. |
| **CSV** | `str` | Writes CSV data to file and returns the filename string. |
## status
```python
def status(
*,
date: str | datetime.datetime = None,
from_date: str | datetime.datetime = None,
to_date: str | datetime.datetime = None,
countback: int = None,
country: str = None,
output_format: OutputFormat = OutputFormat.DATAFRAME,
date_format: DateFormat = None,
columns: list[str] = None,
add_headers: bool = None,
use_human_readable: bool = False,
mode: Mode = None,
filename: str | Path = None,
) -> list[MarketStatus] | list[MarketStatusHumanReadable] | dict | str | MarketDataClientErrorResult
```
Fetches market status information for specified dates and countries. All parameters must be keyword-only.
### Parameters
- `date` (str | datetime.datetime, optional)
Specific date for the market status.
- `from_date` (str | datetime.datetime, optional)
Start date for the date range.
- `to_date` (str | datetime.datetime, optional)
End date for the date range.
- `countback` (int, optional)
Number of days to return, counting backwards from the `to_date`.
- `country` (str, optional)
Filter by country code (e.g., "US", "CA", "GB").
- `output_format` ([OutputFormat](https://www.marketdata.app/docs/sdk/py/settings#output-format), optional)
The format of the returned data. Defaults to `OutputFormat.DATAFRAME`. See [Settings](https://www.marketdata.app/docs/sdk/py/settings) for details.
- `date_format` ([DateFormat](https://www.marketdata.app/docs/sdk/py/settings#date-format), optional)
The date format to use in the response. Defaults to `DateFormat.UNIX`. See [Settings](https://www.marketdata.app/docs/sdk/py/settings) for details.
- [`columns`](https://www.marketdata.app/docs/sdk/py/settings#columns) (optional)
Specify which columns to include in the response. See [Settings](https://www.marketdata.app/docs/sdk/py/settings) for details.
- [`add_headers`](https://www.marketdata.app/docs/sdk/py/settings#headers) (optional)
Whether to include headers in the response. See [Settings](https://www.marketdata.app/docs/sdk/py/settings) for details.
- [`use_human_readable`](https://www.marketdata.app/docs/sdk/py/settings#human-readable) (optional)
Whether to use human-readable format for values. Only applies when `output_format=OutputFormat.INTERNAL`. See [Settings](https://www.marketdata.app/docs/sdk/py/settings) for details.
- `mode` ([Mode](https://www.marketdata.app/docs/sdk/py/settings#data-mode), optional)
The data mode to use. See [Settings](https://www.marketdata.app/docs/sdk/py/settings) for details.
- `filename` (str | Path, optional)
File path for CSV output (only used with `output_format=OutputFormat.CSV`).
### Returns
- `list[MarketStatus]` | `list[MarketStatusHumanReadable]` | `dict` | `str` | `MarketDataClientErrorResult`
The market status data in the requested format, or a `MarketDataClientErrorResult` if an error occurred.
### Notes
- All parameters must be keyword-only (no positional arguments).
- When using `countback`, it counts backwards from `to_date` or the current date if `to_date` is not provided.
### Example (DataFrame)
```python
from marketdata import MarketDataClient
client = MarketDataClient()
# Get market status as DataFrame (default)
# All parameters must be keyword-only
df = client.markets.status(countback=7)
# Get market status for a specific date
df = client.markets.status(date="2023-01-01")
# Get market status for a date range
df = client.markets.status(
from_date="2023-01-01",
to_date="2023-01-31",
country="US"
)
print(df)
```
### Example (Internal)
```python
from marketdata import MarketDataClient, OutputFormat
client = MarketDataClient()
# Get market status as internal objects
status_list = client.markets.status(
countback=7,
output_format=OutputFormat.INTERNAL
)
# Access individual status properties
for status in status_list:
print(f"Date: {status.date}")
print(f"Status: {status.status}")
```
### Example (JSON)
```python
from marketdata import MarketDataClient, OutputFormat
client = MarketDataClient()
# Get market status as JSON
status = client.markets.status(
countback=7,
output_format=OutputFormat.JSON
)
print(status)
```
### Example (CSV)
```python
from marketdata import MarketDataClient, OutputFormat
from pathlib import Path
client = MarketDataClient()
# Get market status as CSV
csv_file = client.markets.status(
countback=7,
output_format=OutputFormat.CSV,
filename=Path("market_status.csv")
)
print(f"CSV file saved to: {csv_file}")
```
### Example (Human Readable)
```python
from marketdata import MarketDataClient, OutputFormat
client = MarketDataClient()
# Get market status in human-readable format
status_list = client.markets.status(
countback=7,
output_format=OutputFormat.INTERNAL,
use_human_readable=True
)
# Access individual status properties
for status in status_list:
print(f"Status: {status.Status}")
print(f"Date: {status.Date}")
```
## MarketStatus
```python
@dataclass
class MarketStatus:
date: datetime.date
status: str
```
MarketStatus represents market status information for a specific date, indicating whether the market is open or closed.
### Properties
- `date` (datetime.date): The date for which the market status applies (automatically converted from timestamp).
- `status` (str): The market status (e.g., "open", "closed").
### Notes
- The `date` field is automatically converted to a `datetime.date` object from a Unix timestamp.
## MarketStatusHumanReadable
```python
@dataclass
class MarketStatusHumanReadable:
Status: str
Date: datetime.datetime
```
MarketStatusHumanReadable represents market status information in human-readable format with capitalized field names and formatted values.
### Properties
- `Status` (str): The market status (e.g., "open", "closed").
- `Date` (datetime.datetime): The date for which the market status applies (automatically converted from timestamp).
### Notes
- The `Date` field is automatically converted to a `datetime.datetime` object from a Unix timestamp.
- Field names use capitalized format (e.g., `Date` instead of `date`, `Status` instead of `status`).
---
# Options (Python SDK)
Source: https://www.marketdata.app/docs/sdk/py/options/index.md
The Python SDK from Market Data provides methods designed to streamline your use of the following Options endpoints. These intuitive methods provide a seamless interface for accessing options data including chains, expirations, quotes, and lookup functionality.
## Options Endpoints
---
# Option Chain (Python SDK)
Source: https://www.marketdata.app/docs/sdk/py/options/chain/index.md
Retrieve a complete or filtered options chain for a given underlying symbol. Both real-time and historical requests are possible.
## Making Requests
Use the `chain()` method on the `options` resource to fetch options chain data. The method supports multiple output formats:
| Output Format | Return Type | Description |
|---------------|-----------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **DATAFRAME** | `pandas.DataFrame` or `polars.DataFrame` | Returns a DataFrame with options chain data indexed by optionSymbol (default). |
| **INTERNAL** | `OptionsChain` or `OptionsChainHumanReadable` | Returns an OptionsChain object containing lists of option data. When `use_human_readable=True`, returns an OptionsChainHumanReadable object with capitalized field names. |
| **JSON** | `dict` | Returns the raw JSON response as a dictionary. |
| **CSV** | `str` | Writes CSV data to file and returns the filename string. |
## chain
```python
def chain(
symbol: str,
*,
expiration: str = None,
date: str | datetime.datetime = None,
from_date: str | datetime.datetime = None,
to_date: str | datetime.datetime = None,
strike: float = None,
side: str = None,
dte: int = None,
delta: float = None,
range: str = None,
strike_limit: int = None,
min_bid: float = None,
max_bid: float = None,
min_ask: float = None,
max_ask: float = None,
min_open_interest: int = None,
min_volume: int = None,
max_bid_ask_spread: float = None,
max_bid_ask_spread_pct: float = None,
monthly: bool = None,
weekly: bool = None,
quarterly: bool = None,
nonstandard: bool = None,
am: bool = None,
pm: bool = None,
month: int = None,
year: int = None,
output_format: OutputFormat = OutputFormat.DATAFRAME,
date_format: DateFormat = None,
columns: list[str] = None,
add_headers: bool = None,
use_human_readable: bool = False,
mode: Mode = None,
filename: str | Path = None,
) -> OptionsChain | OptionsChainHumanReadable | dict | str | MarketDataClientErrorResult
```
Fetches the options chain for a given symbol with extensive filtering options. The `symbol` parameter can be passed as the first positional argument or as a keyword argument. All other parameters must be keyword-only.
### Parameters
- `symbol` (str)
The underlying stock symbol for which to fetch the options chain.
- `expiration` (str, optional)
Filter by expiration date. Can be a date string or "all" to get all expirations.
- `date` (str | datetime.datetime, optional)
Historical date for the options chain data.
- `from_date` (str | datetime.datetime, optional)
Start date for the date range.
- `to_date` (str | datetime.datetime, optional)
End date for the date range.
- `strike` (float, optional)
Filter by strike price.
- `side` (str, optional)
Filter by option side: "call" or "put".
- `dte` (int, optional)
Days to expiration. Requests an expiration date based on the number of days from the present date.
- `delta` (float, optional)
Filter by Delta value.
- `range` (str, optional)
Filter by strike range: "itm" (In The Money), "otm" (Out of The Money), "atm" (At The Money).
- `strike_limit` (int, optional)
Maximum number of strike prices to include in the option chain.
- `min_open_interest` (int, optional)
Minimum open interest for options to be included.
- `min_bid` (float, optional)
Minimum bid price for options to be included. Uses API alias `minBid`.
- `max_bid` (float, optional)
Maximum bid price for options to be included. Uses API alias `maxBid`.
- `min_ask` (float, optional)
Minimum ask price for options to be included. Uses API alias `minAsk`.
- `max_ask` (float, optional)
Maximum ask price for options to be included. Uses API alias `maxAsk`.
- `min_volume` (int, optional)
Minimum volume for options to be included.
- `max_bid_ask_spread` (float, optional)
Maximum bid-ask spread for options to be included.
- `max_bid_ask_spread_pct` (float, optional)
Maximum bid-ask spread percentage for options to be included.
- `monthly` (bool, optional)
Include or exclude monthly option expirations.
- `weekly` (bool, optional)
Include or exclude weekly option expirations.
- `quarterly` (bool, optional)
Include or exclude quarterly option expirations.
- `nonstandard` (bool, optional)
Include or exclude non-standard option expirations.
- `am` (bool, optional)
Whether to include A.M. expirations.
- `pm` (bool, optional)
Whether to include P.M. expirations.
- `month` (int, optional)
Filter by specific month (1-12).
- `year` (int, optional)
Filter by specific year.
- `output_format` ([OutputFormat](https://www.marketdata.app/docs/sdk/py/settings#output-format), optional)
The format of the returned data. Defaults to `OutputFormat.DATAFRAME`. See [Settings](https://www.marketdata.app/docs/sdk/py/settings) for details.
- `date_format` ([DateFormat](https://www.marketdata.app/docs/sdk/py/settings#date-format), optional)
The date format to use in the response. Defaults to `DateFormat.UNIX`. See [Settings](https://www.marketdata.app/docs/sdk/py/settings) for details.
- [`columns`](https://www.marketdata.app/docs/sdk/py/settings#columns) (optional)
Specify which columns to include in the response. See [Settings](https://www.marketdata.app/docs/sdk/py/settings) for details.
- [`add_headers`](https://www.marketdata.app/docs/sdk/py/settings#headers) (optional)
Whether to include headers in the response. See [Settings](https://www.marketdata.app/docs/sdk/py/settings) for details.
- [`use_human_readable`](https://www.marketdata.app/docs/sdk/py/settings#human-readable) (optional)
Whether to use human-readable format for values. Only applies when `output_format=OutputFormat.INTERNAL`. See [Settings](https://www.marketdata.app/docs/sdk/py/settings) for details.
- `mode` ([Mode](https://www.marketdata.app/docs/sdk/py/settings#data-mode), optional)
The data mode to use. See [Settings](https://www.marketdata.app/docs/sdk/py/settings) for details.
- `filename` (str | Path, optional)
File path for CSV output (only used with `output_format=OutputFormat.CSV`).
### Returns
- `OptionsChain` | `OptionsChainHumanReadable` | `dict` | `str` | `MarketDataClientErrorResult`
The options chain data in the requested format, or a `MarketDataClientErrorResult` if an error occurred.
### Notes
- When using `OutputFormat.DATAFRAME`, the DataFrame is indexed by the `optionSymbol` column.
- When using `OutputFormat.INTERNAL`, timestamps are automatically converted to `datetime.datetime` objects.
- The OptionsChain object contains lists of equal length for each field, allowing you to iterate through options by index.
### Example (DataFrame)
```python
from marketdata import MarketDataClient
client = MarketDataClient()
# Get options chain as DataFrame (default)
# symbol can be passed positionally or as keyword
chain = client.options.chain("AAPL")
# or
chain = client.options.chain(symbol="AAPL")
# Filter by side and date
chain = client.options.chain(
"AAPL",
side="call",
date="2022-01-03",
dte=60,
strike_limit=2,
range="itm"
)
print(chain)
```
**Output**
```
underlying expiration side strike ... volume openInterest inTheMoney underlyingPrice
optionSymbol ...
AAPL271217C00250000 AAPL 2022-03-18 call 175.0 ... 1295 15232 True 182.01
AAPL271217C00255000 AAPL 2022-03-18 call 180.0 ... 4609 18299 True 182.01
```
### Example (Internal)
```python
from marketdata import MarketDataClient, OutputFormat
client = MarketDataClient()
# Get options chain as internal object
chain = client.options.chain(
"AAPL",
side="call",
date="2022-01-03",
dte=60,
strike_limit=2,
range="itm",
output_format=OutputFormat.INTERNAL
)
# Access option data by index
print(f"Number of options: {len(chain.optionSymbol)}")
print(f"First option symbol: {chain.optionSymbol[0]}")
print(f"First option strike: {chain.strike[0]}")
print(f"First option expiration: {chain.expiration[0]}")
print(f"First option bid: {chain.bid[0]}")
print(f"First option ask: {chain.ask[0]}")
print(f"First option mid: {chain.mid[0]}")
```
**Output**
```
Number of options: 2
First option symbol: AAPL271217C00250000
First option strike: 175.0
First option expiration: 2022-03-18 16:00:00-04:00
First option bid: 12.95
First option ask: 13.1
First option mid: 13.02
```
### Example (JSON)
```python
from marketdata import MarketDataClient, OutputFormat
client = MarketDataClient()
# Get options chain as JSON
chain = client.options.chain(
"AAPL",
side="call",
date="2022-01-03",
output_format=OutputFormat.JSON
)
print(chain)
```
**Output**
```json
{
"s": "ok",
"optionSymbol": ["AAPL271217C00250000", "AAPL271217C00255000"],
"underlying": ["AAPL", "AAPL"],
"expiration": [1642798800, 1642798800],
"side": ["call", "call"],
"strike": [175, 180],
"bid": [12.95, 10.0],
"ask": [13.1, 10.2],
"mid": [13.02, 10.1],
...
}
```
### Example (CSV)
```python
from marketdata import MarketDataClient, OutputFormat
from pathlib import Path
client = MarketDataClient()
# Get options chain as CSV
csv_file = client.options.chain(
"AAPL",
side="call",
date="2022-01-03",
output_format=OutputFormat.CSV,
filename=Path("chain.csv")
)
print(f"CSV file saved to: {csv_file}")
```
### Example (Human Readable)
```python
from marketdata import MarketDataClient, OutputFormat
client = MarketDataClient()
# Get options chain in human-readable format
chain = client.options.chain(
"AAPL",
side="call",
date="2022-01-03",
output_format=OutputFormat.INTERNAL,
use_human_readable=True
)
# Access option data by index
print(f"Number of options: {len(chain.Symbol)}")
print(f"First option symbol: {chain.Symbol[0]}")
print(f"First option strike: {chain.Strike[0]}")
print(f"First option expiration: {chain.Expiration_Date[0]}")
print(f"First option bid: {chain.Bid[0]}")
print(f"First option ask: {chain.Ask[0]}")
```
### Example (Filtered)
```python
from marketdata import MarketDataClient
client = MarketDataClient()
# Get filtered options chain
chain = client.options.chain(
"AAPL",
side="call",
month=2,
year=2022,
range="itm",
strike=150,
weekly=False,
monthly=True,
quarterly=False,
nonstandard=False
)
print(chain)
```
## OptionsChain
```python
@dataclass
class OptionsChain:
s: str
optionSymbol: list[str]
underlying: list[str]
expiration: list[datetime.datetime]
side: list[str]
strike: list[float]
firstTraded: list[datetime.datetime]
dte: list[int]
updated: list[datetime.datetime]
bid: list[float]
bidSize: list[int]
mid: list[float]
ask: list[float]
askSize: list[int]
last: list[float]
openInterest: list[int]
volume: list[int]
inTheMoney: list[bool]
intrinsicValue: list[float]
extrinsicValue: list[float]
underlyingPrice: list[float]
iv: list[float]
delta: list[float]
gamma: list[float]
theta: list[float]
vega: list[float]
```
OptionsChain represents the options chain data with lists of equal length for each field. All lists have the same length, allowing you to access option data by index.
### Properties
- `s` (str): Status indicator ("ok" for successful responses).
- `optionSymbol` (list[str]): List of option symbols.
- `underlying` (list[str]): List of underlying symbols.
- `expiration` (list[datetime.datetime]): List of expiration dates (automatically converted from timestamps).
- `side` (list[str]): List of option sides ("call" or "put").
- `strike` (list[float]): List of strike prices.
- `firstTraded` (list[datetime.datetime]): List of first traded dates (automatically converted from timestamps).
- `dte` (list[int]): List of days to expiration.
- `updated` (list[datetime.datetime]): List of last update timestamps (automatically converted from timestamps).
- `bid` (list[float]): List of bid prices.
- `bidSize` (list[int]): List of bid sizes.
- `mid` (list[float]): List of mid prices.
- `ask` (list[float]): List of ask prices.
- `askSize` (list[int]): List of ask sizes.
- `last` (list[float]): List of last traded prices.
- `openInterest` (list[int]): List of open interest values.
- `volume` (list[int]): List of trading volumes.
- `inTheMoney` (list[bool]): List indicating if options are in the money.
- `intrinsicValue` (list[float]): List of intrinsic values.
- `extrinsicValue` (list[float]): List of extrinsic values.
- `underlyingPrice` (list[float]): List of underlying prices.
- `iv` (list[float]): List of implied volatilities.
- `delta` (list[float]): List of Delta values.
- `gamma` (list[float]): List of Gamma values.
- `theta` (list[float]): List of Theta values.
- `vega` (list[float]): List of Vega values.
### Notes
- All lists have the same length, allowing you to access option data by index (e.g., `chain.optionSymbol[0]`, `chain.strike[0]`, etc.).
- Timestamp fields (`expiration`, `firstTraded`, `updated`) are automatically converted to `datetime.datetime` objects.
- The `OptionsChainHumanReadable` variant uses capitalized field names with underscores (e.g., `Expiration_Date` instead of `expiration`).
## OptionsChainHumanReadable
```python
@dataclass
class OptionsChainHumanReadable:
Symbol: list[str]
Underlying: list[str]
Expiration_Date: list[datetime.datetime]
Side: list[str]
Strike: list[float]
First_Traded: list[datetime.datetime]
Days_To_Expiration: list[int]
Date: list[datetime.datetime]
Bid: list[float]
Bid_Size: list[int]
Mid: list[float]
Ask: list[float]
Ask_Size: list[int]
Last: list[float]
Open_Interest: list[int]
Volume: list[int]
In_The_Money: list[bool]
Intrinsic_Value: list[float]
Extrinsic_Value: list[float]
Underlying_Price: list[float]
IV: list[float]
Delta: list[float]
Gamma: list[float]
Theta: list[float]
Vega: list[float]
```
OptionsChainHumanReadable represents the options chain data in human-readable format with capitalized field names and formatted values. All lists have the same length, allowing you to access option data by index.
### Properties
- `Symbol` (list[str]): List of option symbols.
- `Underlying` (list[str]): List of underlying symbols.
- `Expiration_Date` (list[datetime.datetime]): List of expiration dates (automatically converted from timestamps).
- `Option_Side` (list[str]): List of option sides ("call" or "put").
- `Strike` (list[float | int]): List of strike prices.
- `First_Traded` (list[datetime.datetime]): List of first traded dates (automatically converted from timestamps).
- `Days_To_Expiration` (list[int]): List of days to expiration.
- `Date` (list[datetime.datetime]): List of last update timestamps (automatically converted from timestamps).
- `Bid` (list[float]): List of bid prices.
- `Bid_Size` (list[int]): List of bid sizes.
- `Mid` (list[float]): List of mid prices.
- `Ask` (list[float]): List of ask prices.
- `Ask_Size` (list[int]): List of ask sizes.
- `Last` (list[float]): List of last traded prices.
- `Open_Interest` (list[int]): List of open interest values.
- `Volume` (list[int]): List of trading volumes.
- `In_The_Money` (list[bool]): List indicating if options are in the money.
- `Intrinsic_Value` (list[float]): List of intrinsic values.
- `Extrinsic_Value` (list[float]): List of extrinsic values.
- `Underlying_Price` (list[float]): List of underlying prices.
- `IV` (list[float]): List of implied volatilities.
- `Delta` (list[float]): List of Delta values.
- `Gamma` (list[float]): List of Gamma values.
- `Theta` (list[float]): List of Theta values.
- `Vega` (list[float]): List of Vega values.
### Notes
- All lists have the same length, allowing you to access option data by index (e.g., `chain.Symbol[0]`, `chain.Strike[0]`, etc.).
- Timestamp fields (`Expiration_Date`, `First_Traded`, `Date`) are automatically converted to `datetime.datetime` objects.
- Field names use capitalized format with underscores (e.g., `Expiration_Date` instead of `expiration`, `Option_Side` instead of `side`, `Bid_Size` instead of `bidSize`).
---
# Expirations (Python SDK)
Source: https://www.marketdata.app/docs/sdk/py/options/expirations/index.md
Get a list of current or historical option expiration dates for an underlying symbol.
## Making Requests
Use the `expirations()` method on the `options` resource to fetch expiration dates. The method supports multiple output formats:
| Output Format | Return Type | Description |
|---------------|-----------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------|
| **DATAFRAME** | `pandas.DataFrame` or `polars.DataFrame` | Returns a DataFrame with expiration dates indexed by expirations (default). |
| **INTERNAL** | `OptionsExpirations` or `OptionsExpirationsHumanReadable` | Returns an OptionsExpirations object. When `use_human_readable=True`, returns an OptionsExpirationsHumanReadable object with capitalized field names. |
| **JSON** | `dict` | Returns the raw JSON response as a dictionary. |
| **CSV** | `str` | Writes CSV data to file and returns the filename string. |
## expirations
```python
def expirations(
symbol: str,
*,
strike: float = None,
date: str | datetime.datetime = None,
output_format: OutputFormat = OutputFormat.DATAFRAME,
date_format: DateFormat = None,
columns: list[str] = None,
add_headers: bool = None,
use_human_readable: bool = False,
mode: Mode = None,
filename: str | Path = None,
) -> OptionsExpirations | OptionsExpirationsHumanReadable | dict | str | MarketDataClientErrorResult
```
Fetches available expiration dates for a given symbol. The `symbol` parameter can be passed as the first positional argument or as a keyword argument. All other parameters must be keyword-only.
### Parameters
- `symbol` (str)
The underlying stock symbol for which to fetch expiration dates.
- `strike` (float, optional)
Filter by strike price.
- `date` (str | datetime.datetime, optional)
Historical date for the expiration dates.
- `output_format` ([OutputFormat](https://www.marketdata.app/docs/sdk/py/settings#output-format), optional)
The format of the returned data. Defaults to `OutputFormat.DATAFRAME`. See [Settings](https://www.marketdata.app/docs/sdk/py/settings) for details.
- `date_format` ([DateFormat](https://www.marketdata.app/docs/sdk/py/settings#date-format), optional)
The date format to use in the response. Defaults to `DateFormat.UNIX`. See [Settings](https://www.marketdata.app/docs/sdk/py/settings) for details.
- [`columns`](https://www.marketdata.app/docs/sdk/py/settings#columns) (optional)
Specify which columns to include in the response. See [Settings](https://www.marketdata.app/docs/sdk/py/settings) for details.
- [`add_headers`](https://www.marketdata.app/docs/sdk/py/settings#headers) (optional)
Whether to include headers in the response. See [Settings](https://www.marketdata.app/docs/sdk/py/settings) for details.
- [`use_human_readable`](https://www.marketdata.app/docs/sdk/py/settings#human-readable) (optional)
Whether to use human-readable format for values. Only applies when `output_format=OutputFormat.INTERNAL`. See [Settings](https://www.marketdata.app/docs/sdk/py/settings) for details.
- `mode` ([Mode](https://www.marketdata.app/docs/sdk/py/settings#data-mode), optional)
The data mode to use. See [Settings](https://www.marketdata.app/docs/sdk/py/settings) for details.
- `filename` (str | Path, optional)
File path for CSV output (only used with `output_format=OutputFormat.CSV`).
### Returns
- `OptionsExpirations` | `OptionsExpirationsHumanReadable` | `dict` | `str` | `MarketDataClientErrorResult`
The expiration dates in the requested format, or a `MarketDataClientErrorResult` if an error occurred.
### Example (DataFrame)
```python
from marketdata import MarketDataClient
client = MarketDataClient()
# Get options expirations as DataFrame (default)
# symbol can be passed positionally or as keyword
df = client.options.expirations("AAPL")
# or
df = client.options.expirations(symbol="AAPL")
print(df)
```
### Example (Internal)
```python
from marketdata import MarketDataClient, OutputFormat
client = MarketDataClient()
# Get options expirations as internal object
expirations = client.options.expirations("AAPL", output_format=OutputFormat.INTERNAL)
# Access expiration dates
print(f"Expirations: {expirations.expirations}")
```
### Example (JSON)
```python
from marketdata import MarketDataClient, OutputFormat
client = MarketDataClient()
# Get options expirations as JSON
expirations = client.options.expirations("AAPL", output_format=OutputFormat.JSON)
print(expirations)
```
### Example (CSV)
```python
from marketdata import MarketDataClient, OutputFormat
from pathlib import Path
client = MarketDataClient()
# Get options expirations as CSV
csv_file = client.options.expirations(
"AAPL",
output_format=OutputFormat.CSV,
filename=Path("expirations.csv")
)
print(f"CSV file saved to: {csv_file}")
```
### Example (Human Readable)
```python
from marketdata import MarketDataClient, OutputFormat
client = MarketDataClient()
# Get options expirations in human-readable format
expirations = client.options.expirations(
"AAPL",
output_format=OutputFormat.INTERNAL,
use_human_readable=True
)
# Access expiration dates
print(f"Expirations: {expirations.Expirations}")
print(f"Date: {expirations.Date}")
```
## OptionsExpirations
```python
@dataclass
class OptionsExpirations:
s: str
expirations: list[datetime.datetime]
updated: datetime.datetime
```
OptionsExpirations represents expiration dates for options, encapsulating a list of expiration dates and an update timestamp.
### Properties
- `s` (str): Status indicator ("ok" for successful responses).
- `expirations` (list[datetime.datetime]): List of expiration dates (automatically converted from timestamps).
- `updated` (datetime.datetime): The time when the data was last updated (automatically converted from timestamp).
### Notes
- The `expirations` list contains `datetime.datetime` objects automatically converted from Unix timestamps.
- The `updated` field is automatically converted to a `datetime.datetime` object from a Unix timestamp.
## OptionsExpirationsHumanReadable
```python
@dataclass
class OptionsExpirationsHumanReadable:
Expirations: list[datetime.datetime]
Date: datetime.datetime
```
OptionsExpirationsHumanReadable represents expiration dates in human-readable format with capitalized field names and formatted values.
### Properties
- `Expirations` (list[datetime.datetime]): List of expiration dates (automatically converted from timestamps).
- `Date` (datetime.datetime): The time when the data was last updated (automatically converted from timestamp).
### Notes
- The `Expirations` list contains `datetime.datetime` objects automatically converted from Unix timestamps.
- The `Date` field is automatically converted to a `datetime.datetime` object from a Unix timestamp.
- Field names use capitalized format (e.g., `Expirations` instead of `expirations`, `Date` instead of `updated`).
---
# Lookup (Python SDK)
Source: https://www.marketdata.app/docs/sdk/py/options/lookup/index.md
Lookup an option symbol from a human-readable string format.
## Making Requests
Use the `lookup()` method on the `options` resource to lookup option symbols. The method supports multiple output formats:
| Output Format | Return Type | Description |
|---------------|-------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------|
| **DATAFRAME** | `pandas.DataFrame` or `polars.DataFrame` | Returns a DataFrame with option lookup data indexed by optionSymbol (default). |
| **INTERNAL** | `OptionsLookup` or `OptionsLookupHumanReadable` | Returns an OptionsLookup object. When `use_human_readable=True`, returns an OptionsLookupHumanReadable object with capitalized field names. |
| **JSON** | `dict` | Returns the raw JSON response as a dictionary. |
| **CSV** | `str` | Writes CSV data to file and returns the filename string. |
## lookup
```python
def lookup(
lookup: str,
*,
output_format: OutputFormat = OutputFormat.DATAFRAME,
date_format: DateFormat = None,
columns: list[str] = None,
add_headers: bool = None,
use_human_readable: bool = False,
mode: Mode = None,
filename: str | Path = None,
) -> OptionsLookup | OptionsLookupHumanReadable | dict | str | MarketDataClientErrorResult
```
Fetches option lookup data for a given lookup string. The lookup string should contain the underlying symbol, expiration date, strike price, and option side in the format: "SYMBOL DD-MM-YYYY STRIKE SIDE" (e.g., "AAPL 20-12-2024 150.0 call"). The `lookup` parameter can be passed as the first positional argument or as a keyword argument. All other parameters must be keyword-only.
### Parameters
- `lookup` (str)
The lookup string in the format "SYMBOL DD-MM-YYYY STRIKE SIDE" (e.g., "AAPL 20-12-2024 150.0 call").
- `output_format` ([OutputFormat](https://www.marketdata.app/docs/sdk/py/settings#output-format), optional)
The format of the returned data. Defaults to `OutputFormat.DATAFRAME`. See [Settings](https://www.marketdata.app/docs/sdk/py/settings) for details.
- `date_format` ([DateFormat](https://www.marketdata.app/docs/sdk/py/settings#date-format), optional)
The date format to use in the response. Defaults to `DateFormat.UNIX`. See [Settings](https://www.marketdata.app/docs/sdk/py/settings) for details.
- [`columns`](https://www.marketdata.app/docs/sdk/py/settings#columns) (optional)
Specify which columns to include in the response. See [Settings](https://www.marketdata.app/docs/sdk/py/settings) for details.
- [`add_headers`](https://www.marketdata.app/docs/sdk/py/settings#headers) (optional)
Whether to include headers in the response. See [Settings](https://www.marketdata.app/docs/sdk/py/settings) for details.
- [`use_human_readable`](https://www.marketdata.app/docs/sdk/py/settings#human-readable) (optional)
Whether to use human-readable format for values. Only applies when `output_format=OutputFormat.INTERNAL`. See [Settings](https://www.marketdata.app/docs/sdk/py/settings) for details.
- `mode` ([Mode](https://www.marketdata.app/docs/sdk/py/settings#data-mode), optional)
The data mode to use. See [Settings](https://www.marketdata.app/docs/sdk/py/settings) for details.
- `filename` (str | Path, optional)
File path for CSV output (only used with `output_format=OutputFormat.CSV`).
### Returns
- `OptionsLookup` | `OptionsLookupHumanReadable` | `dict` | `str` | `MarketDataClientErrorResult`
The option lookup data in the requested format, or a `MarketDataClientErrorResult` if an error occurred.
### Notes
- The lookup string format is: "SYMBOL DD-MM-YYYY STRIKE SIDE"
- Example: "AAPL 20-12-2024 150.0 call" or "AAPL 20-12-2024 150.0 put"
- When using `OutputFormat.DATAFRAME`, the DataFrame is indexed by the `optionSymbol` column.
### Example (DataFrame)
```python
from marketdata import MarketDataClient
client = MarketDataClient()
# Get option lookup as DataFrame (default)
# lookup can be passed positionally or as keyword
df = client.options.lookup("AAPL 20-12-2024 150.0 call")
# or
df = client.options.lookup(lookup="AAPL 20-12-2024 150.0 call")
print(df)
```
### Example (Internal)
```python
from marketdata import MarketDataClient, OutputFormat
client = MarketDataClient()
# Get option lookup as internal object
lookup_result = client.options.lookup(
"AAPL 20-12-2024 150.0 call",
output_format=OutputFormat.INTERNAL
)
# Access lookup properties
print(f"Option Symbol: {lookup_result.optionSymbol}")
```
### Example (JSON)
```python
from marketdata import MarketDataClient, OutputFormat
client = MarketDataClient()
# Get option lookup as JSON
lookup_result = client.options.lookup(
"AAPL 20-12-2024 150.0 call",
output_format=OutputFormat.JSON
)
print(lookup_result)
```
### Example (CSV)
```python
from marketdata import MarketDataClient, OutputFormat
from pathlib import Path
client = MarketDataClient()
# Get option lookup as CSV
csv_file = client.options.lookup(
"AAPL 20-12-2024 150.0 call",
output_format=OutputFormat.CSV,
filename=Path("lookup.csv")
)
print(f"CSV file saved to: {csv_file}")
```
### Example (Human Readable)
```python
from marketdata import MarketDataClient, OutputFormat
client = MarketDataClient()
# Get option lookup in human-readable format
lookup_result = client.options.lookup(
"AAPL 20-12-2024 150.0 call",
output_format=OutputFormat.INTERNAL,
use_human_readable=True
)
# Access lookup properties
print(f"Symbol: {lookup_result.Symbol}")
```
## OptionsLookup
```python
@dataclass
class OptionsLookup:
s: str
optionSymbol: str
```
OptionsLookup represents the result of an option symbol lookup, containing the resolved option symbol.
### Properties
- `s` (str): Status indicator ("ok" for successful responses).
- `optionSymbol` (str): The resolved option symbol.
## OptionsLookupHumanReadable
```python
@dataclass
class OptionsLookupHumanReadable:
Symbol: str
```
OptionsLookupHumanReadable represents an option symbol lookup result in human-readable format with capitalized field names.
### Properties
- `Symbol` (str): The resolved option symbol.
### Notes
- Field names use capitalized format (e.g., `Symbol` instead of `optionSymbol`).
---
# Option Quotes (Python SDK)
Source: https://www.marketdata.app/docs/sdk/py/options/quotes/index.md
Retrieve quotes for one or more option symbols.
## Making Requests
Use the `quotes()` method on the `options` resource to fetch option quotes. The method supports multiple output formats and automatically handles multiple symbols by fetching them concurrently:
| Output Format | Return Type | Description |
|---------------|-------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **DATAFRAME** | `pandas.DataFrame` or `polars.DataFrame` | Returns a DataFrame with option quotes indexed by optionSymbol (default). |
| **INTERNAL** | `OptionsQuotes` or `OptionsQuotesHumanReadable` | Returns an OptionsQuotes object containing lists of option quote data. When `use_human_readable=True`, returns an OptionsQuotesHumanReadable object with capitalized field names. |
| **JSON** | `dict` | Returns the raw JSON response as a dictionary. |
| **CSV** | `str` | Writes CSV data to file and returns the filename string. |
## quotes
```python
def quotes(
symbols: str | list[str],
*,
output_format: OutputFormat = OutputFormat.DATAFRAME,
date_format: DateFormat = None,
columns: list[str] = None,
add_headers: bool = None,
use_human_readable: bool = False,
mode: Mode = None,
filename: str | Path = None,
) -> OptionsQuotes | OptionsQuotesHumanReadable | dict | str | MarketDataClientErrorResult
```
Fetches option quotes for one or more option symbols. Note: `quotes()` takes option symbols (e.g., "AAPL271217C00250000"), not stock symbols. The `symbols` parameter can be passed as the first positional argument or as a keyword argument. All other parameters must be keyword-only.
### Parameters
- `symbols` (str | list[str])
A single option symbol string or a list of option symbol strings for which to fetch quotes.
- `output_format` ([OutputFormat](https://www.marketdata.app/docs/sdk/py/settings#output-format), optional)
The format of the returned data. Defaults to `OutputFormat.DATAFRAME`. See [Settings](https://www.marketdata.app/docs/sdk/py/settings) for details.
- `date_format` ([DateFormat](https://www.marketdata.app/docs/sdk/py/settings#date-format), optional)
The date format to use in the response. Defaults to `DateFormat.UNIX`. See [Settings](https://www.marketdata.app/docs/sdk/py/settings) for details.
- [`columns`](https://www.marketdata.app/docs/sdk/py/settings#columns) (optional)
Specify which columns to include in the response. See [Settings](https://www.marketdata.app/docs/sdk/py/settings) for details.
- [`add_headers`](https://www.marketdata.app/docs/sdk/py/settings#headers) (optional)
Whether to include headers in the response. See [Settings](https://www.marketdata.app/docs/sdk/py/settings) for details.
- [`use_human_readable`](https://www.marketdata.app/docs/sdk/py/settings#human-readable) (optional)
Whether to use human-readable format for values. Only applies when `output_format=OutputFormat.INTERNAL`. See [Settings](https://www.marketdata.app/docs/sdk/py/settings) for details.
- `mode` ([Mode](https://www.marketdata.app/docs/sdk/py/settings#data-mode), optional)
The data mode to use. See [Settings](https://www.marketdata.app/docs/sdk/py/settings) for details.
- `filename` (str | Path, optional)
File path for CSV output (only used with `output_format=OutputFormat.CSV`).
### Returns
- `OptionsQuotes` | `OptionsQuotesHumanReadable` | `dict` | `str` | `MarketDataClientErrorResult`
The option quotes in the requested format, or a `MarketDataClientErrorResult` if an error occurred.
### Notes
- Multiple option symbols are fetched concurrently (up to 50 concurrent requests by default).
- When using `OutputFormat.DATAFRAME`, the DataFrame is indexed by the `optionSymbol` column.
- The OptionsQuotes object contains lists of equal length for each field, allowing you to iterate through options by index.
### Example (DataFrame)
```python
from marketdata import MarketDataClient
client = MarketDataClient()
# Get option quotes as DataFrame (default)
# symbols can be passed positionally or as keyword
# Note: quotes() takes option symbols, not stock symbols
df = client.options.quotes("AAPL271217C00250000")
# or
df = client.options.quotes(symbols="AAPL271217C00250000")
# Get quotes for multiple option symbols
df = client.options.quotes(["AAPL271217C00250000", "AAPL271217P00250000"])
print(df)
```
### Example (Internal)
```python
from marketdata import MarketDataClient, OutputFormat
client = MarketDataClient()
# Get option quotes as internal object
quotes = client.options.quotes(
["AAPL271217C00250000", "AAPL271217P00250000"],
output_format=OutputFormat.INTERNAL
)
# Access option data by index
print(f"Number of options: {len(quotes.optionSymbol)}")
print(f"First option symbol: {quotes.optionSymbol[0]}")
print(f"First option bid: {quotes.bid[0]}")
print(f"First option ask: {quotes.ask[0]}")
```
### Example (JSON)
```python
from marketdata import MarketDataClient, OutputFormat
client = MarketDataClient()
# Get option quotes as JSON
quotes = client.options.quotes(
["AAPL271217C00250000", "AAPL271217P00250000"],
output_format=OutputFormat.JSON
)
print(quotes)
```
### Example (CSV)
```python
from marketdata import MarketDataClient, OutputFormat
from pathlib import Path
client = MarketDataClient()
# Get option quotes as CSV
csv_file = client.options.quotes(
["AAPL271217C00250000", "AAPL271217P00250000"],
output_format=OutputFormat.CSV,
filename=Path("options_quotes.csv")
)
print(f"CSV file saved to: {csv_file}")
```
### Example (Human Readable)
```python
from marketdata import MarketDataClient, OutputFormat
client = MarketDataClient()
# Get option quotes in human-readable format
quotes = client.options.quotes(
["AAPL271217C00250000", "AAPL271217P00250000"],
output_format=OutputFormat.INTERNAL,
use_human_readable=True
)
# Access option data by index
print(f"Number of options: {len(quotes.Symbol)}")
print(f"First option symbol: {quotes.Symbol[0]}")
print(f"First option underlying: {quotes.Underlying[0]}")
print(f"First option expiration: {quotes.Expiration_Date[0]}")
print(f"First option strike: {quotes.Strike[0]}")
print(f"First option bid: {quotes.Bid[0]}")
print(f"First option ask: {quotes.Ask[0]}")
```
## OptionsQuotes
```python
@dataclass
class OptionsQuotes:
s: str
optionSymbol: list[str]
underlying: list[str]
expiration: list[datetime.datetime]
side: list[str]
strike: list[float]
firstTraded: list[datetime.datetime]
dte: list[int]
updated: list[datetime.datetime]
bid: list[float]
bidSize: list[int]
mid: list[float]
ask: list[float]
askSize: list[int]
last: list[float]
openInterest: list[int]
volume: list[int]
inTheMoney: list[bool]
intrinsicValue: list[float]
extrinsicValue: list[float]
underlyingPrice: list[float]
iv: list[float]
delta: list[float]
gamma: list[float]
theta: list[float]
vega: list[float]
```
OptionsQuotes represents option quotes data with lists of equal length for each field. All lists have the same length, allowing you to access option data by index.
### Properties
- `s` (str): Status indicator ("ok" for successful responses).
- `optionSymbol` (list[str]): List of option symbols.
- `underlying` (list[str]): List of underlying symbols.
- `expiration` (list[datetime.datetime]): List of expiration dates (automatically converted from timestamps).
- `side` (list[str]): List of option sides ("call" or "put").
- `strike` (list[float]): List of strike prices.
- `firstTraded` (list[datetime.datetime]): List of first traded dates (automatically converted from timestamps).
- `dte` (list[int]): List of days to expiration.
- `updated` (list[datetime.datetime]): List of last update timestamps (automatically converted from timestamps).
- `bid` (list[float]): List of bid prices.
- `bidSize` (list[int]): List of bid sizes.
- `mid` (list[float]): List of mid prices.
- `ask` (list[float]): List of ask prices.
- `askSize` (list[int]): List of ask sizes.
- `last` (list[float]): List of last traded prices.
- `openInterest` (list[int]): List of open interest values.
- `volume` (list[int]): List of trading volumes.
- `inTheMoney` (list[bool]): List indicating if options are in the money.
- `intrinsicValue` (list[float]): List of intrinsic values.
- `extrinsicValue` (list[float]): List of extrinsic values.
- `underlyingPrice` (list[float]): List of underlying prices.
- `iv` (list[float]): List of implied volatilities.
- `delta` (list[float]): List of Delta values.
- `gamma` (list[float]): List of Gamma values.
- `theta` (list[float]): List of Theta values.
- `vega` (list[float]): List of Vega values.
### Notes
- All lists have the same length, allowing you to access option data by index (e.g., `quotes.optionSymbol[0]`, `quotes.bid[0]`, etc.).
- Timestamp fields (`expiration`, `firstTraded`, `updated`) are automatically converted to `datetime.datetime` objects.
## OptionsQuotesHumanReadable
```python
@dataclass
class OptionsQuotesHumanReadable:
Symbol: list[str]
Underlying: list[str]
Expiration_Date: list[datetime.datetime]
Option_Side: list[str]
Strike: list[float | int]
First_Traded: list[datetime.datetime]
Days_To_Expiration: list[int]
Date: list[datetime.datetime]
Bid: list[float]
Bid_Size: list[int]
Mid: list[float]
Ask: list[float]
Ask_Size: list[int]
Last: list[float]
Open_Interest: list[int]
Volume: list[int]
In_The_Money: list[bool]
Intrinsic_Value: list[float]
Extrinsic_Value: list[float]
Underlying_Price: list[float]
IV: list[float]
Delta: list[float]
Gamma: list[float]
Theta: list[float]
Vega: list[float]
```
OptionsQuotesHumanReadable represents option quotes in human-readable format with capitalized field names and formatted values.
### Properties
- `Symbol` (list[str]): List of option symbols.
- `Underlying` (list[str]): List of underlying symbols.
- `Expiration_Date` (list[datetime.datetime]): List of expiration dates (automatically converted from timestamps).
- `Option_Side` (list[str]): List of option sides ("call" or "put").
- `Strike` (list[float | int]): List of strike prices.
- `First_Traded` (list[datetime.datetime]): List of first traded dates (automatically converted from timestamps).
- `Days_To_Expiration` (list[int]): List of days to expiration.
- `Date` (list[datetime.datetime]): List of last update timestamps (automatically converted from timestamps).
- `Bid` (list[float]): List of bid prices.
- `Bid_Size` (list[int]): List of bid sizes.
- `Mid` (list[float]): List of mid prices.
- `Ask` (list[float]): List of ask prices.
- `Ask_Size` (list[int]): List of ask sizes.
- `Last` (list[float]): List of last traded prices.
- `Open_Interest` (list[int]): List of open interest values.
- `Volume` (list[int]): List of trading volumes.
- `In_The_Money` (list[bool]): List indicating if options are in the money.
- `Intrinsic_Value` (list[float]): List of intrinsic values.
- `Extrinsic_Value` (list[float]): List of extrinsic values.
- `Underlying_Price` (list[float]): List of underlying prices.
- `IV` (list[float]): List of implied volatilities.
- `Delta` (list[float]): List of Delta values.
- `Gamma` (list[float]): List of Gamma values.
- `Theta` (list[float]): List of Theta values.
- `Vega` (list[float]): List of Vega values.
### Notes
- All lists have the same length, allowing you to access option data by index (e.g., `quotes.Symbol[0]`, `quotes.Bid[0]`, etc.).
- Timestamp fields (`Expiration_Date`, `First_Traded`, `Date`) are automatically converted to `datetime.datetime` objects.
- Field names use capitalized format with underscores (e.g., `Expiration_Date` instead of `expiration`, `Option_Side` instead of `side`, `Open_Interest` instead of `openInterest`).
---
# Settings (Python SDK)
Source: https://www.marketdata.app/docs/sdk/py/settings/index.md
The Market Data Python SDK provides flexible configuration options for customizing API requests. You can configure universal parameters like output format, date format, data mode, and more through multiple methods with different priority levels.
## Configuration Priority
The SDK supports multiple ways to configure universal parameters. These configuration methods follow a priority hierarchy, where higher priority settings override lower priority ones.
### Priority Order (Lowest to Highest)
1. **Environment Variables** (Lowest Priority)
- Set via environment variables like `MARKETDATA_OUTPUT_FORMAT`, `MARKETDATA_DATE_FORMAT`, etc.
- Applied globally to all API calls unless overridden
2. **Client Default Parameters** (`client.default_params`)
- Set via `client.default_params` property
- Applied to all API calls made with that client instance unless overridden
3. **Direct Method Parameters** (Highest Priority)
- Passed directly as keyword arguments to resource methods
- Applied only to that specific API call
### How It Works
When making an API call, the SDK merges parameters in the following order:
1. **Start with environment variables** (lowest priority)
- Parameters are read from environment variables like `MARKETDATA_OUTPUT_FORMAT`, `MARKETDATA_DATE_FORMAT`, etc.
2. **Override with `client.default_params`** (medium priority)
- Parameters set via `client.default_params` override environment variables
- Example: `client.default_params.output_format = OutputFormat.JSON`
3. **Override with direct method parameters** (highest priority)
- Parameters passed directly to resource methods override both environment variables and `client.default_params`
- Example: `client.stocks.prices("AAPL", output_format=OutputFormat.DATAFRAME)`
### Examples
### Environment Variables
Set universal parameters via environment variables:
```python
import os
os.environ["MARKETDATA_OUTPUT_FORMAT"] = "json"
os.environ["MARKETDATA_DATE_FORMAT"] = "timestamp"
from marketdata import MarketDataClient
client = MarketDataClient()
# All calls will use JSON format and timestamp date format
# (unless overridden by client.default_params or method parameters)
prices = client.stocks.prices("AAPL")
# Uses: output_format=JSON, date_format=TIMESTAMP
```
### Client Default Params
Set universal parameters via `client.default_params`:
```python
from marketdata import MarketDataClient, OutputFormat, DateFormat
client = MarketDataClient()
# Set default parameters for this client instance
client.default_params.output_format = OutputFormat.JSON
client.default_params.date_format = DateFormat.TIMESTAMP
# All calls will use JSON format and timestamp date format
# (unless overridden by method parameters)
prices = client.stocks.prices("AAPL")
# Uses: output_format=JSON, date_format=TIMESTAMP
quotes = client.stocks.quotes("AAPL")
# Uses: output_format=JSON, date_format=TIMESTAMP
```
**Note:** `client.default_params` overrides environment variables.
### Direct Method Parameters
Pass parameters directly to resource methods:
```python
from marketdata import MarketDataClient, OutputFormat, DateFormat
client = MarketDataClient()
# Set default parameters
client.default_params.output_format = OutputFormat.JSON
client.default_params.date_format = DateFormat.TIMESTAMP
# Direct method parameters override client.default_params
prices = client.stocks.prices(
"AAPL",
output_format=OutputFormat.DATAFRAME, # Overrides JSON
date_format=DateFormat.UNIX # Overrides TIMESTAMP
)
# Uses: output_format=DATAFRAME, date_format=UNIX
# This call still uses client.default_params
quotes = client.stocks.quotes("AAPL")
# Uses: output_format=JSON, date_format=TIMESTAMP
```
**Note:** Direct method parameters override both environment variables and `client.default_params`.
## Available Configuration Options
### Output Format
Controls the format of the API response data.
**Available Values:**
- `OutputFormat.DATAFRAME` (default): Returns data as a pandas DataFrame
- `OutputFormat.JSON`: Returns data as JSON
- `OutputFormat.CSV`: Returns data as CSV (saves to file)
- `OutputFormat.INTERNAL`: Returns data in internal format
**Configuration Methods:**
1. **Environment Variable:** `MARKETDATA_OUTPUT_FORMAT` (values: `dataframe`, `internal`, `json`, `csv`)
2. **Client Default:** `client.default_params.output_format = OutputFormat.JSON`
3. **Direct Parameter:** `client.stocks.quotes("AAPL", output_format=OutputFormat.JSON)`
**Example:**
```python
from marketdata import MarketDataClient, OutputFormat
client = MarketDataClient()
# Method 1: Environment variable
# export MARKETDATA_OUTPUT_FORMAT=json
# Method 2: Client default params
client.default_params.output_format = OutputFormat.JSON
# Method 3: Direct parameter (highest priority)
quotes = client.stocks.quotes("AAPL", output_format=OutputFormat.DATAFRAME)
```
For more details, see the [API Format documentation](https://www.marketdata.app/docs/api/universal-parameters/format).
### Date Format
Specifies the format for date and time information in responses.
**Available Values:**
- `DateFormat.TIMESTAMP`: ISO 8601 timestamp format (e.g., `2020-12-30 16:00:00 -05:00`)
- `DateFormat.UNIX`: Unix timestamp in seconds (e.g., `1609362000`)
- `DateFormat.SPREADSHEET`: Excel spreadsheet format (e.g., `44195.66667`)
**Configuration Methods:**
1. **Environment Variable:** `MARKETDATA_DATE_FORMAT` (values: `timestamp`, `unix`, `spreadsheet`)
2. **Client Default:** `client.default_params.date_format = DateFormat.UNIX`
3. **Direct Parameter:** `client.stocks.candles("AAPL", date_format=DateFormat.UNIX)`
**Example:**
```python
from marketdata import MarketDataClient, DateFormat
client = MarketDataClient()
# Method 1: Environment variable
# export MARKETDATA_DATE_FORMAT=unix
# Method 2: Client default params
client.default_params.date_format = DateFormat.UNIX
# Method 3: Direct parameter (highest priority)
candles = client.stocks.candles("AAPL", date_format=DateFormat.TIMESTAMP)
```
For more details, see the [API Date Format documentation](https://www.marketdata.app/docs/api/universal-parameters/date-format).
### Columns
Limits the response to only the columns you need, reducing data transfer and processing time.
**Type:** `list[str]` or comma-separated string
**Configuration Methods:**
1. **Environment Variable:** `MARKETDATA_COLUMNS` (comma-separated list, e.g., `ask,bid`)
2. **Client Default:** `client.default_params.columns = ["ask", "bid"]`
3. **Direct Parameter:** `client.stocks.quotes("AAPL", columns=["ask", "bid"])`
**Example:**
```python
from marketdata import MarketDataClient
client = MarketDataClient()
# Method 1: Environment variable
# export MARKETDATA_COLUMNS=ask,bid
# Method 2: Client default params
client.default_params.columns = ["ask", "bid"]
# Method 3: Direct parameter (highest priority)
quotes = client.stocks.quotes("AAPL", columns=["ask", "bid"])
# Or as a comma-separated string
quotes = client.stocks.quotes("AAPL", columns="ask,bid")
```
For more details, see the [API Columns documentation](https://www.marketdata.app/docs/api/universal-parameters/columns).
### Headers
Controls whether headers are included in CSV output.
**Type:** `bool`
**Default:** `True`
**Configuration Methods:**
1. **Environment Variable:** `MARKETDATA_ADD_HEADERS` (values: `true`, `false`)
2. **Client Default:** `client.default_params.add_headers = False`
3. **Direct Parameter:** `client.stocks.candles("AAPL", add_headers=False)`
**Example:**
```python
from marketdata import MarketDataClient, OutputFormat
client = MarketDataClient()
# Method 1: Environment variable
# export MARKETDATA_ADD_HEADERS=false
# Method 2: Client default params
client.default_params.add_headers = False
# Method 3: Direct parameter (highest priority)
candles = client.stocks.candles(
"AAPL",
output_format=OutputFormat.CSV,
add_headers=False
)
```
For more details, see the [API Headers documentation](https://www.marketdata.app/docs/api/universal-parameters/headers).
### Human Readable
Uses human-readable attribute names in JSON or CSV output instead of camelCase. Only applies when `output_format=OutputFormat.INTERNAL`.
**Type:** `bool`
**Default:** `False`
**Configuration Methods:**
1. **Environment Variable:** `MARKETDATA_USE_HUMAN_READABLE` (values: `true`, `false`)
2. **Client Default:** `client.default_params.use_human_readable = True`
3. **Direct Parameter:** `client.stocks.quotes("AAPL", use_human_readable=True)`
**Example:**
```python
from marketdata import MarketDataClient, OutputFormat
client = MarketDataClient()
# Method 1: Environment variable
# export MARKETDATA_USE_HUMAN_READABLE=true
# Method 2: Client default params
client.default_params.use_human_readable = True
# Method 3: Direct parameter (highest priority)
quotes = client.stocks.quotes(
"AAPL",
output_format=OutputFormat.INTERNAL,
use_human_readable=True
)
```
For more details, see the [API Human Readable documentation](https://www.marketdata.app/docs/api/universal-parameters/human-readable).
### Data Mode
Controls how an API request is fulfilled, including data freshness guarantees and credit usage.
**Available Values:**
- `Mode.LIVE`: Real-time data (default for paid accounts)
- `Mode.CACHED`: Recently cached data (reduces credit usage for bulk quotes)
- `Mode.DELAYED`: Data delayed by at least 15 minutes (default for free/trial accounts)
**Configuration Methods:**
1. **Environment Variable:** `MARKETDATA_MODE` (values: `live`, `cached`, `delayed`)
2. **Client Default:** `client.default_params.mode = Mode.CACHED`
3. **Direct Parameter:** `client.options.chain("SPY", mode=Mode.CACHED)`
**Example:**
```python
from marketdata import MarketDataClient, Mode
client = MarketDataClient()
# Method 1: Environment variable
# export MARKETDATA_MODE=cached
# Method 2: Client default params
client.default_params.mode = Mode.CACHED
# Method 3: Direct parameter (highest priority)
chain = client.options.chain("SPY", mode=Mode.CACHED)
quotes = client.stocks.quotes("AAPL", mode=Mode.LIVE)
```
> [!NOTE]
> **[Premium Parameter]**
>
> The `mode` parameter is available only on paid plans. Free and trial plans cannot change the data mode and receive historical data (the last fully-closed session). See [Data Freshness](https://www.marketdata.app/docs/account/data-freshness).
For more details, see the [API Mode documentation](https://www.marketdata.app/docs/api/universal-parameters/mode).
## Available Environment Variables
You can set the following environment variables to configure universal parameters globally:
- `MARKETDATA_OUTPUT_FORMAT`: Output format (`dataframe`, `internal`, `json`, `csv`)
- `MARKETDATA_DATE_FORMAT`: Date format (`timestamp`, `unix`, `spreadsheet`)
- `MARKETDATA_COLUMNS`: Comma-separated list of columns to include
- `MARKETDATA_ADD_HEADERS`: Whether to include headers (`true`, `false`)
- `MARKETDATA_USE_HUMAN_READABLE`: Whether to use human-readable format (`true`, `false`)
- `MARKETDATA_MODE`: Data mode (`live`, `cached`, `delayed`)
## Best Practices
- **Use environment variables** for global defaults that apply across your entire application
- **Use `client.default_params`** when you want different defaults for different client instances
- **Use direct method parameters** when you need to override defaults for specific API calls
This flexible configuration system allows you to set sensible defaults while still having fine-grained control over individual API calls.
---
# Stocks (Python SDK)
Source: https://www.marketdata.app/docs/sdk/py/stocks/index.md
The Python SDK from Market Data provides methods designed to streamline your use of the following Stocks endpoints. These intuitive methods provide a seamless interface, effectively masking the intricacies involved in managing HTTP requests and responses.
## Stocks Endpoints
---
# Stock Candles (Python SDK)
Source: https://www.marketdata.app/docs/sdk/py/stocks/candles/index.md
Retrieve historical price candles for any supported stock symbol.
## Making Requests
Use the `candles()` method on the `stocks` resource to fetch stock candles. The method supports multiple output formats and automatically handles large date ranges by splitting them into year-long chunks and fetching them concurrently:
| Output Format | Return Type | Description |
|---------------|----------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------|
| **DATAFRAME** | `pandas.DataFrame` or `polars.DataFrame` | Returns a DataFrame with candles data indexed by timestamp (default). |
| **INTERNAL** | `list[StockCandle]` or `list[StockCandlesHumanReadable]` | Returns a list of StockCandle objects. When `use_human_readable=True`, returns a list of StockCandlesHumanReadable objects with capitalized field names. |
| **JSON** | `dict` | Returns the raw JSON response as a dictionary. |
| **CSV** | `str` | Writes CSV data to file and returns the filename string. |
## candles
```python
def candles(
symbol: str,
*,
resolution: str = "D",
from_date: str | datetime.datetime = None,
to_date: str | datetime.datetime = None,
date: str | datetime.datetime = None,
countback: int = None,
adjust_splits: bool = None,
extended: bool = None,
exchange: str = None,
output_format: OutputFormat = OutputFormat.DATAFRAME,
date_format: DateFormat = None,
columns: list[str] = None,
add_headers: bool = None,
use_human_readable: bool = False,
mode: Mode = None,
filename: str | Path = None,
) -> list[StockCandle] | list[StockCandlesHumanReadable] | dict | str | MarketDataClientErrorResult
```
Fetches historical candles (OHLCV) data for a stock symbol. Supports various timeframes (minutely, hourly, daily, weekly, monthly, yearly) and automatically handles large date ranges by splitting them into year-long chunks and fetching them concurrently. The `symbol` parameter can be passed as the first positional argument or as a keyword argument. All other parameters must be keyword-only.
### Parameters
- `symbol` (str)
The stock symbol for which to fetch candles data.
- `resolution` (str, optional)
The granularity of the candle data (e.g., "1m", "5m", "1H", "4H", "1D", "1W", "1M", "1Y"). Defaults to `"D"` (daily).
- `from_date` (str | datetime.datetime, optional)
Start date for the date range.
- `to_date` (str | datetime.datetime, optional)
End date for the date range.
- `date` (str | datetime.datetime, optional)
Specific date for the candles data.
- `countback` (int, optional)
Number of candles to return, counting backwards from the `to_date`.
- `adjust_splits` (bool, optional)
Whether to adjust for stock splits. Uses API alias `adjustsplits`.
- `extended` (bool, optional)
Whether to include extended hours data.
- `exchange` (str, optional)
Filter by exchange.
- `output_format` ([OutputFormat](https://www.marketdata.app/docs/sdk/py/settings#output-format), optional)
The format of the returned data. Defaults to `OutputFormat.DATAFRAME`. See [Settings](https://www.marketdata.app/docs/sdk/py/settings) for details.
- `date_format` ([DateFormat](https://www.marketdata.app/docs/sdk/py/settings#date-format), optional)
The date format to use in the response. Defaults to `DateFormat.UNIX`. See [Settings](https://www.marketdata.app/docs/sdk/py/settings) for details.
- [`columns`](https://www.marketdata.app/docs/sdk/py/settings#columns) (optional)
Specify which columns to include in the response. See [Settings](https://www.marketdata.app/docs/sdk/py/settings) for details.
- [`add_headers`](https://www.marketdata.app/docs/sdk/py/settings#headers) (optional)
Whether to include headers in the response. See [Settings](https://www.marketdata.app/docs/sdk/py/settings) for details.
- [`use_human_readable`](https://www.marketdata.app/docs/sdk/py/settings#human-readable) (optional)
Whether to use human-readable format for values. Only applies when `output_format=OutputFormat.INTERNAL`. See [Settings](https://www.marketdata.app/docs/sdk/py/settings) for details.
- `mode` ([Mode](https://www.marketdata.app/docs/sdk/py/settings#data-mode), optional)
The data mode to use. See [Settings](https://www.marketdata.app/docs/sdk/py/settings) for details.
- `filename` (str | Path, optional)
File path for CSV output (only used with `output_format=OutputFormat.CSV`).
### Returns
- `list[StockCandle]` | `list[StockCandlesHumanReadable]` | `dict` | `str` | `MarketDataClientErrorResult`
The candles data in the requested format, or a `MarketDataClientErrorResult` if an error occurred.
### Notes
- For intraday resolutions (minutely/hourly), large date ranges are automatically split into year-long chunks and fetched concurrently (up to 50 concurrent requests by default).
- When using `OutputFormat.DATAFRAME`, the DataFrame is indexed by the timestamp column (`t` or `Date`).
- When using `OutputFormat.INTERNAL`, timestamps are automatically converted to `datetime.datetime` objects.
### Example (DataFrame)
```python
from marketdata import MarketDataClient
client = MarketDataClient()
# Get stock candles as DataFrame (default)
# symbol can be passed positionally or as keyword
df = client.stocks.candles("AAPL", resolution="4H", from_date="2023-01-01", to_date="2023-01-04")
# or
df = client.stocks.candles(symbol="AAPL", resolution="4H", from_date="2023-01-01", to_date="2023-01-04")
print(df)
```
**Output**
```
open high low close volume
t
2023-01-03 09:30:00 130.28 130.90 124.19 124.65 64192007
2023-01-03 13:30:00 124.67 125.42 124.17 125.05 30727802
2023-01-04 09:30:00 126.89 128.66 125.08 127.26 49096197
2023-01-04 13:30:00 127.26 127.87 125.28 126.38 28870578
```
### Example (Internal)
```python
from marketdata import MarketDataClient, OutputFormat
client = MarketDataClient()
# Get stock candles as internal objects
candles = client.stocks.candles(
"AAPL",
resolution="4H",
from_date="2023-01-01",
to_date="2023-01-04",
output_format=OutputFormat.INTERNAL
)
# Access individual candle properties
for candle in candles:
print(f"Time: {candle.t}")
print(f"Open: {candle.o}")
print(f"High: {candle.h}")
print(f"Low: {candle.l}")
print(f"Close: {candle.c}")
print(f"Volume: {candle.v}")
```
### Example (JSON)
```python
from marketdata import MarketDataClient, OutputFormat
client = MarketDataClient()
# Get stock candles as JSON
candles = client.stocks.candles(
"AAPL",
resolution="4H",
from_date="2023-01-01",
to_date="2023-01-04",
output_format=OutputFormat.JSON
)
print(candles)
```
### Example (CSV)
```python
from marketdata import MarketDataClient, OutputFormat
from pathlib import Path
client = MarketDataClient()
# Get stock candles as CSV
csv_file = client.stocks.candles(
"AAPL",
resolution="4H",
from_date="2023-01-01",
to_date="2023-01-04",
output_format=OutputFormat.CSV,
filename=Path("candles.csv")
)
print(f"CSV file saved to: {csv_file}")
```
### Example (Human Readable)
```python
from marketdata import MarketDataClient, OutputFormat
client = MarketDataClient()
# Get stock candles in human-readable format
candles = client.stocks.candles(
"AAPL",
resolution="4H",
from_date="2023-01-01",
to_date="2023-01-04",
output_format=OutputFormat.INTERNAL,
use_human_readable=True
)
# Access individual candle properties
for candle in candles:
print(f"Date: {candle.Date}")
print(f"Open: {candle.Open}")
print(f"High: {candle.High}")
print(f"Low: {candle.Low}")
print(f"Close: {candle.Close}")
print(f"Volume: {candle.Volume}")
```
## StockCandle
```python
@dataclass
class StockCandle:
t: datetime.datetime
o: float
h: float
l: float
c: float
v: int
```
StockCandle represents a single stock candle (OHLCV data), encapsulating price and volume information for a specific time period.
### Properties
- `t` (datetime.datetime): The timestamp for the candle (automatically converted from Unix timestamp).
- `o` (float): The opening price.
- `h` (float): The highest price.
- `l` (float): The lowest price.
- `c` (float): The closing price.
- `v` (int): The trading volume.
### Notes
- The `t` field is automatically converted to a `datetime.datetime` object from a Unix timestamp.
## StockCandlesHumanReadable
```python
@dataclass
class StockCandlesHumanReadable:
Date: datetime.datetime
Open: float
High: float
Low: float
Close: float
Volume: int
```
StockCandlesHumanReadable represents a stock candle in human-readable format with capitalized field names and formatted values.
### Properties
- `Date` (datetime.datetime): The timestamp for the candle (automatically converted from Unix timestamp).
- `Open` (float): The opening price.
- `High` (float): The highest price.
- `Low` (float): The lowest price.
- `Close` (float): The closing price.
- `Volume` (int): The trading volume.
### Notes
- The `Date` field is automatically converted to a `datetime.datetime` object from a Unix timestamp.
- Field names use capitalized format (e.g., `Open` instead of `o`, `Date` instead of `t`).
---
# Earnings (Python SDK)
Source: https://www.marketdata.app/docs/sdk/py/stocks/earnings/index.md
Retrieve earnings data for any supported stock symbol.
## Making Requests
Use the `earnings()` method on the `stocks` resource to fetch earnings data. The method supports multiple output formats:
| Output Format | Return Type | Description |
|---------------|-------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------|
| **DATAFRAME** | `pandas.DataFrame` or `polars.DataFrame` | Returns a DataFrame with earnings data indexed by symbol (default). |
| **INTERNAL** | `StockEarnings` or `StockEarningsHumanReadable` | Returns a StockEarnings object. When `use_human_readable=True`, returns a StockEarningsHumanReadable object with capitalized field names. |
| **JSON** | `dict` | Returns the raw JSON response as a dictionary. |
| **CSV** | `str` | Writes CSV data to file and returns the filename string. |
## earnings
```python
def earnings(
symbol: str,
*,
report: str = None,
date: str | datetime.datetime = None,
from_date: str | datetime.datetime = None,
to_date: str | datetime.datetime = None,
countback: int = None,
output_format: OutputFormat = OutputFormat.DATAFRAME,
date_format: DateFormat = None,
columns: list[str] = None,
add_headers: bool = None,
use_human_readable: bool = False,
mode: Mode = None,
filename: str | Path = None,
) -> StockEarnings | StockEarningsHumanReadable | dict | str | MarketDataClientErrorResult
```
Fetches earnings data for a stock symbol. The `symbol` parameter can be passed as the first positional argument or as a keyword argument. All other parameters must be keyword-only.
### Parameters
- `symbol` (str)
The stock symbol for which to fetch earnings data.
- `report` (str, optional)
Filter by report type (e.g., "annual", "quarterly").
- `date` (str | datetime.datetime, optional)
Specific date for the earnings data.
- `from_date` (str | datetime.datetime, optional)
Start date for the date range.
- `to_date` (str | datetime.datetime, optional)
End date for the date range.
- `countback` (int, optional)
Number of earnings reports to return, counting backwards from the `to_date`.
- `output_format` ([OutputFormat](https://www.marketdata.app/docs/sdk/py/settings#output-format), optional)
The format of the returned data. Defaults to `OutputFormat.DATAFRAME`. See [Settings](https://www.marketdata.app/docs/sdk/py/settings) for details.
- `date_format` ([DateFormat](https://www.marketdata.app/docs/sdk/py/settings#date-format), optional)
The date format to use in the response. Defaults to `DateFormat.UNIX`. See [Settings](https://www.marketdata.app/docs/sdk/py/settings) for details.
- [`columns`](https://www.marketdata.app/docs/sdk/py/settings#columns) (optional)
Specify which columns to include in the response. See [Settings](https://www.marketdata.app/docs/sdk/py/settings) for details.
- [`add_headers`](https://www.marketdata.app/docs/sdk/py/settings#headers) (optional)
Whether to include headers in the response. See [Settings](https://www.marketdata.app/docs/sdk/py/settings) for details.
- [`use_human_readable`](https://www.marketdata.app/docs/sdk/py/settings#human-readable) (optional)
Whether to use human-readable format for values. Only applies when `output_format=OutputFormat.INTERNAL`. See [Settings](https://www.marketdata.app/docs/sdk/py/settings) for details.
- `mode` ([Mode](https://www.marketdata.app/docs/sdk/py/settings#data-mode), optional)
The data mode to use. See [Settings](https://www.marketdata.app/docs/sdk/py/settings) for details.
- `filename` (str | Path, optional)
File path for CSV output (only used with `output_format=OutputFormat.CSV`).
### Returns
- `StockEarnings` | `StockEarningsHumanReadable` | `dict` | `str` | `MarketDataClientErrorResult`
The earnings data in the requested format, or a `MarketDataClientErrorResult` if an error occurred.
### Example (DataFrame)
```python
from marketdata import MarketDataClient
client = MarketDataClient()
# Get stock earnings as DataFrame (default)
# symbol can be passed positionally or as keyword
df = client.stocks.earnings("AAPL")
# or
df = client.stocks.earnings(symbol="AAPL")
print(df)
```
### Example (Internal)
```python
from marketdata import MarketDataClient, OutputFormat
client = MarketDataClient()
# Get stock earnings as internal object
earnings = client.stocks.earnings("AAPL", output_format=OutputFormat.INTERNAL)
# Access earnings properties
print(f"Symbol: {earnings.symbol}")
print(f"Fiscal Year: {earnings.fiscalYear}")
print(f"Fiscal Quarter: {earnings.fiscalQuarter}")
print(f"Reported EPS: {earnings.reportedEPS}")
print(f"Estimated EPS: {earnings.estimatedEPS}")
```
### Example (JSON)
```python
from marketdata import MarketDataClient, OutputFormat
client = MarketDataClient()
# Get stock earnings as JSON
earnings = client.stocks.earnings("AAPL", output_format=OutputFormat.JSON)
print(earnings)
```
### Example (CSV)
```python
from marketdata import MarketDataClient, OutputFormat
from pathlib import Path
client = MarketDataClient()
# Get stock earnings as CSV
csv_file = client.stocks.earnings(
"AAPL",
output_format=OutputFormat.CSV,
filename=Path("earnings.csv")
)
print(f"CSV file saved to: {csv_file}")
```
### Example (Human Readable)
```python
from marketdata import MarketDataClient, OutputFormat
client = MarketDataClient()
# Get stock earnings in human-readable format
earnings = client.stocks.earnings(
"AAPL",
output_format=OutputFormat.INTERNAL,
use_human_readable=True
)
# Access earnings properties
print(f"Symbol: {earnings.Symbol}")
print(f"Fiscal Year: {earnings.Fiscal_Year}")
print(f"Fiscal Quarter: {earnings.Fiscal_Quarter}")
print(f"Reported EPS: {earnings.Reported_EPS}")
print(f"Estimated EPS: {earnings.Estimated_EPS}")
print(f"Surprise EPS: {earnings.Surprise_EPS}")
```
## StockEarnings
```python
@dataclass
class StockEarnings:
s: str
symbol: list[str]
fiscalYear: list[int]
fiscalQuarter: list[int]
date: list[datetime.datetime]
reportDate: list[datetime.datetime]
reportTime: list[str]
currency: list[str]
reportedEPS: list[float]
estimatedEPS: list[float]
surpriseEPS: list[float]
surpriseEPSpct: list[float]
updated: list[datetime.datetime]
```
StockEarnings represents earnings data for a stock, encapsulating fiscal year, quarter, and EPS information. All lists have the same length, allowing you to access earnings data by index.
### Properties
- `s` (str): Status indicator ("ok" for successful responses).
- `symbol` (list[str]): List of stock symbols.
- `fiscalYear` (list[int]): List of fiscal years.
- `fiscalQuarter` (list[int]): List of fiscal quarters.
- `date` (list[datetime.datetime]): List of earnings dates (automatically converted from timestamps).
- `reportDate` (list[datetime.datetime]): List of report dates (automatically converted from timestamps).
- `reportTime` (list[str]): List of report times.
- `currency` (list[str]): List of currencies.
- `reportedEPS` (list[float]): List of reported earnings per share.
- `estimatedEPS` (list[float]): List of estimated earnings per share.
- `surpriseEPS` (list[float]): List of surprise earnings per share (difference between reported and estimated).
- `surpriseEPSpct` (list[float]): List of surprise EPS percentages.
- `updated` (list[datetime.datetime]): List of last update timestamps (automatically converted from timestamps).
## StockEarningsHumanReadable
```python
@dataclass
class StockEarningsHumanReadable:
Symbol: list[str]
Fiscal_Year: list[int]
Fiscal_Quarter: list[int]
Date: list[datetime.datetime]
Report_Date: list[datetime.datetime]
Report_Time: list[str]
Currency: list[str]
Reported_EPS: list[float]
Estimated_EPS: list[float]
Surprise_EPS: list[float]
Surprise_EPS_Percent: list[float]
Updated: list[datetime.datetime]
```
StockEarningsHumanReadable represents earnings data in human-readable format with capitalized field names and formatted values. All lists have the same length, allowing you to access earnings data by index.
### Properties
- `Symbol` (list[str]): List of stock symbols.
- `Fiscal_Year` (list[int]): List of fiscal years.
- `Fiscal_Quarter` (list[int]): List of fiscal quarters.
- `Date` (list[datetime.datetime]): List of earnings dates (automatically converted from timestamps).
- `Report_Date` (list[datetime.datetime]): List of report dates (automatically converted from timestamps).
- `Report_Time` (list[str]): List of report times.
- `Currency` (list[str]): List of currencies.
- `Reported_EPS` (list[float]): List of reported earnings per share.
- `Estimated_EPS` (list[float]): List of estimated earnings per share.
- `Surprise_EPS` (list[float]): List of surprise earnings per share (difference between reported and estimated).
- `Surprise_EPS_Percent` (list[float]): List of surprise EPS percentages.
- `Updated` (list[datetime.datetime]): List of last update timestamps (automatically converted from timestamps).
### Notes
- Field names use capitalized format with underscores (e.g., `Fiscal_Year` instead of `fiscalYear`, `Reported_EPS` instead of `reportedEPS`).
---
# News (Python SDK)
Source: https://www.marketdata.app/docs/sdk/py/stocks/news/index.md
Retrieve news articles for any supported stock symbol.
## Making Requests
Use the `news()` method on the `stocks` resource to fetch news articles. The method supports multiple output formats:
| Output Format | Return Type | Description |
|---------------|-----------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------|
| **DATAFRAME** | `pandas.DataFrame` or `polars.DataFrame` | Returns a DataFrame with news articles indexed by symbol (default). |
| **INTERNAL** | `list[StockNews]` or `list[StockNewsHumanReadable]` | Returns a list of StockNews objects. When `use_human_readable=True`, returns a list of StockNewsHumanReadable objects with capitalized field names. |
| **JSON** | `dict` | Returns the raw JSON response as a dictionary. |
| **CSV** | `str` | Writes CSV data to file and returns the filename string. |
## news
```python
def news(
symbol: str,
*,
date: str | datetime.datetime = None,
from_date: str | datetime.datetime = None,
to_date: str | datetime.datetime = None,
countback: int = None,
output_format: OutputFormat = OutputFormat.DATAFRAME,
date_format: DateFormat = None,
columns: list[str] = None,
add_headers: bool = None,
use_human_readable: bool = False,
mode: Mode = None,
filename: str | Path = None,
) -> list[StockNews] | list[StockNewsHumanReadable] | dict | str | MarketDataClientErrorResult
```
Fetches news articles for a stock symbol. The `symbol` parameter can be passed as the first positional argument or as a keyword argument. All other parameters must be keyword-only.
### Parameters
- `symbol` (str)
The stock symbol for which to fetch news articles.
- `date` (str | datetime.datetime, optional)
Specific date for the news articles.
- `from_date` (str | datetime.datetime, optional)
Start date for the date range.
- `to_date` (str | datetime.datetime, optional)
End date for the date range.
- `countback` (int, optional)
Number of news articles to return, counting backwards from the `to_date`.
- `output_format` ([OutputFormat](https://www.marketdata.app/docs/sdk/py/settings#output-format), optional)
The format of the returned data. Defaults to `OutputFormat.DATAFRAME`. See [Settings](https://www.marketdata.app/docs/sdk/py/settings) for details.
- `date_format` ([DateFormat](https://www.marketdata.app/docs/sdk/py/settings#date-format), optional)
The date format to use in the response. Defaults to `DateFormat.UNIX`. See [Settings](https://www.marketdata.app/docs/sdk/py/settings) for details.
- [`columns`](https://www.marketdata.app/docs/sdk/py/settings#columns) (optional)
Specify which columns to include in the response. See [Settings](https://www.marketdata.app/docs/sdk/py/settings) for details.
- [`add_headers`](https://www.marketdata.app/docs/sdk/py/settings#headers) (optional)
Whether to include headers in the response. See [Settings](https://www.marketdata.app/docs/sdk/py/settings) for details.
- [`use_human_readable`](https://www.marketdata.app/docs/sdk/py/settings#human-readable) (optional)
Whether to use human-readable format for values. Only applies when `output_format=OutputFormat.INTERNAL`. See [Settings](https://www.marketdata.app/docs/sdk/py/settings) for details.
- `mode` ([Mode](https://www.marketdata.app/docs/sdk/py/settings#data-mode), optional)
The data mode to use. See [Settings](https://www.marketdata.app/docs/sdk/py/settings) for details.
- `filename` (str | Path, optional)
File path for CSV output (only used with `output_format=OutputFormat.CSV`).
### Returns
- `list[StockNews]` | `list[StockNewsHumanReadable]` | `dict` | `str` | `MarketDataClientErrorResult`
The news articles in the requested format, or a `MarketDataClientErrorResult` if an error occurred.
### Example (DataFrame)
```python
from marketdata import MarketDataClient
client = MarketDataClient()
# Get stock news as DataFrame (default)
# symbol can be passed positionally or as keyword
df = client.stocks.news("AAPL")
# or
df = client.stocks.news(symbol="AAPL")
print(df)
```
### Example (Internal)
```python
from marketdata import MarketDataClient, OutputFormat
client = MarketDataClient()
# Get stock news as internal objects
news_list = client.stocks.news("AAPL", output_format=OutputFormat.INTERNAL)
# Access individual news article properties
for news in news_list:
print(f"Symbol: {news.symbol}")
print(f"Headline: {news.headline}")
print(f"Source: {news.source}")
print(f"Publication Date: {news.publicationDate}")
print(f"Updated: {news.updated}")
```
### Example (JSON)
```python
from marketdata import MarketDataClient, OutputFormat
client = MarketDataClient()
# Get stock news as JSON
news = client.stocks.news("AAPL", output_format=OutputFormat.JSON)
print(news)
```
### Example (CSV)
```python
from marketdata import MarketDataClient, OutputFormat
from pathlib import Path
client = MarketDataClient()
# Get stock news as CSV
csv_file = client.stocks.news(
"AAPL",
output_format=OutputFormat.CSV,
filename=Path("news.csv")
)
print(f"CSV file saved to: {csv_file}")
```
### Example (Human Readable)
```python
from marketdata import MarketDataClient, OutputFormat
client = MarketDataClient()
# Get stock news in human-readable format
news_list = client.stocks.news(
"AAPL",
output_format=OutputFormat.INTERNAL,
use_human_readable=True
)
# Access individual news article properties
for news in news_list:
print(f"Symbol: {news.Symbol}")
print(f"Headline: {news.headline}")
print(f"Source: {news.source}")
print(f"Publication Date: {news.publicationDate}")
print(f"Date: {news.Date}")
```
## StockNews
```python
@dataclass
class StockNews:
symbol: str
headline: str
content: str
source: str
publicationDate: datetime.datetime
updated: datetime.datetime
```
StockNews represents a single news article for a stock, encapsulating headline, content, source, and publication information.
### Properties
- `symbol` (str): The stock symbol.
- `headline` (str): The news headline.
- `content` (str): The news article content.
- `source` (str): The news source.
- `publicationDate` (datetime.datetime): The publication date (automatically converted from timestamp).
- `updated` (datetime.datetime): The time when the news was last updated (automatically converted from timestamp).
### Notes
- The `publicationDate` and `updated` fields are automatically converted to `datetime.datetime` objects from Unix timestamps.
## StockNewsHumanReadable
```python
@dataclass
class StockNewsHumanReadable:
Symbol: str
headline: str
content: str
source: str
publicationDate: datetime.datetime
Date: datetime.datetime
```
StockNewsHumanReadable represents a news article in human-readable format with capitalized field names and formatted values.
### Properties
- `Symbol` (str): The stock symbol.
- `headline` (str): The news headline.
- `content` (str): The news article content.
- `source` (str): The news source.
- `publicationDate` (datetime.datetime): The publication date (automatically converted from timestamp).
- `Date` (datetime.datetime): The time when the news was last updated (automatically converted from timestamp).
### Notes
- The `publicationDate` and `Date` fields are automatically converted to `datetime.datetime` objects from Unix timestamps.
- Field names use capitalized format with underscores where applicable (e.g., `Symbol` instead of `symbol`, `Date` instead of `updated`).
---
# Prices (Python SDK)
Source: https://www.marketdata.app/docs/sdk/py/stocks/prices/index.md
Retrieve stock prices for any supported stock symbol.
## Making Requests
Use the `prices()` method on the `stocks` resource to fetch stock prices. The method supports multiple output formats:
| Output Format | Return Type | Description |
|---------------|--------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------|
| **DATAFRAME** | `pandas.DataFrame` or `polars.DataFrame` | Returns a DataFrame with prices indexed by symbol (default). |
| **INTERNAL** | `list[StockPrice]` or `list[StockPricesHumanReadable]` | Returns a list of StockPrice objects. When `use_human_readable=True`, returns a list of StockPricesHumanReadable objects with capitalized field names. |
| **JSON** | `dict` | Returns the raw JSON response as a dictionary. |
| **CSV** | `str` | Writes CSV data to file and returns the filename string. |
## prices
```python
def prices(
symbols: list[str] | str,
*,
output_format: OutputFormat = OutputFormat.DATAFRAME,
date_format: DateFormat = None,
columns: list[str] = None,
add_headers: bool = None,
use_human_readable: bool = False,
mode: Mode = None,
filename: str | Path = None,
) -> list[StockPrice] | list[StockPricesHumanReadable] | dict | str | MarketDataClientErrorResult
```
Fetches stock prices for one or more symbols. The `symbols` parameter can be passed as the first positional argument or as a keyword argument. All other parameters must be keyword-only.
### Parameters
- `symbols` (list[str] | str)
A single symbol string or a list of symbol strings for which to fetch prices.
- `output_format` ([OutputFormat](https://www.marketdata.app/docs/sdk/py/settings#output-format), optional)
The format of the returned data. Defaults to `OutputFormat.DATAFRAME`. See [Settings](https://www.marketdata.app/docs/sdk/py/settings) for details.
- `date_format` ([DateFormat](https://www.marketdata.app/docs/sdk/py/settings#date-format), optional)
The date format to use in the response. Defaults to `DateFormat.UNIX`. See [Settings](https://www.marketdata.app/docs/sdk/py/settings) for details.
- [`columns`](https://www.marketdata.app/docs/sdk/py/settings#columns) (optional)
Specify which columns to include in the response. See [Settings](https://www.marketdata.app/docs/sdk/py/settings) for details.
- [`add_headers`](https://www.marketdata.app/docs/sdk/py/settings#headers) (optional)
Whether to include headers in the response. See [Settings](https://www.marketdata.app/docs/sdk/py/settings) for details.
- [`use_human_readable`](https://www.marketdata.app/docs/sdk/py/settings#human-readable) (optional)
Whether to use human-readable format for values. Only applies when `output_format=OutputFormat.INTERNAL`. See [Settings](https://www.marketdata.app/docs/sdk/py/settings) for details.
- `mode` ([Mode](https://www.marketdata.app/docs/sdk/py/settings#data-mode), optional)
The data mode to use. See [Settings](https://www.marketdata.app/docs/sdk/py/settings) for details.
- `filename` (str | Path, optional)
File path for CSV output (only used with `output_format=OutputFormat.CSV`).
### Returns
- `list[StockPrice]` | `list[StockPricesHumanReadable]` | `dict` | `str` | `MarketDataClientErrorResult`
The prices data in the requested format, or a `MarketDataClientErrorResult` if an error occurred.
### Example (DataFrame)
```python
from marketdata import MarketDataClient
client = MarketDataClient()
# Get stock prices as DataFrame (default)
# symbols can be passed positionally or as keyword
df = client.stocks.prices("AAPL")
# or
df = client.stocks.prices(symbols="AAPL")
# Get prices for multiple symbols
df = client.stocks.prices(["AAPL", "MSFT"])
print(df)
```
### Example (Internal)
```python
from marketdata import MarketDataClient, OutputFormat
client = MarketDataClient()
# Get stock prices as internal objects
prices = client.stocks.prices("AAPL", output_format=OutputFormat.INTERNAL)
# Access individual price properties
for price in prices:
print(f"Symbol: {price.symbol}")
print(f"Mid: {price.mid}")
print(f"Change: {price.change}")
print(f"Change Percent: {price.changepct}")
print(f"Updated: {price.updated}")
```
### Example (JSON)
```python
from marketdata import MarketDataClient, OutputFormat
client = MarketDataClient()
# Get stock prices as JSON
prices = client.stocks.prices(["AAPL", "MSFT"], output_format=OutputFormat.JSON)
print(prices)
```
### Example (CSV)
```python
from marketdata import MarketDataClient, OutputFormat
from pathlib import Path
client = MarketDataClient()
# Get stock prices as CSV
csv_file = client.stocks.prices(
["AAPL", "MSFT"],
output_format=OutputFormat.CSV,
filename=Path("prices.csv")
)
print(f"CSV file saved to: {csv_file}")
```
### Example (Human Readable)
```python
from marketdata import MarketDataClient, OutputFormat
client = MarketDataClient()
# Get stock prices in human-readable format
prices = client.stocks.prices(
"AAPL",
output_format=OutputFormat.INTERNAL,
use_human_readable=True
)
for price in prices:
print(f"Symbol: {price.Symbol}")
print(f"Mid: {price.Mid}")
print(f"Change Price: {price.Change_Price}")
print(f"Change Percent: {price.Change_Percent}")
print(f"Date: {price.Date}")
```
## StockPrice
```python
@dataclass
class StockPrice:
s: str
symbol: str
mid: float
change: float
changepct: float
updated: datetime.datetime
```
StockPrice represents a single stock price, encapsulating various details such as prices and timestamps.
### Properties
- `s` (str): Status indicator ("ok" for successful responses).
- `symbol` (str): The stock symbol.
- `mid` (float): The mid price calculated between the ask and bid prices.
- `change` (float): The price change.
- `changepct` (float): The percentage change in price.
- `updated` (datetime.datetime): The time when the price was last updated (automatically converted from timestamp).
### Notes
- The `updated` field is automatically converted to a `datetime.datetime` object from a Unix timestamp.
## StockPricesHumanReadable
```python
@dataclass
class StockPricesHumanReadable:
Symbol: str
Mid: float
Change_Price: float
Change_Percent: float
Date: datetime.datetime
```
StockPricesHumanReadable represents a stock price in human-readable format with capitalized field names and formatted values.
### Properties
- `Symbol` (str): The stock symbol.
- `Mid` (float): The mid price calculated between the ask and bid prices.
- `Change_Price` (float): The price change.
- `Change_Percent` (float): The percentage change in price.
- `Date` (datetime.datetime): The time when the price was last updated (automatically converted from timestamp).
### Notes
- The `Date` field is automatically converted to a `datetime.datetime` object from a Unix timestamp.
- Field names use capitalized format with underscores (e.g., `Change_Price` instead of `change`).
---
# Stock Quotes (Python SDK)
Source: https://www.marketdata.app/docs/sdk/py/stocks/quotes/index.md
Retrieve live quotes for any supported stock symbol.
## Making Requests
Use the `quotes()` method on the `stocks` resource to fetch stock quotes. The method supports multiple output formats:
| Output Format | Return Type | Description |
|---------------|--------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------|
| **DATAFRAME** | `pandas.DataFrame` or `polars.DataFrame` | Returns a DataFrame with quotes indexed by symbol (default). |
| **INTERNAL** | `list[StockQuote]` or `list[StockQuotesHumanReadable]` | Returns a list of StockQuote objects. When `use_human_readable=True`, returns a list of StockQuotesHumanReadable objects with capitalized field names. |
| **JSON** | `dict` | Returns the raw JSON response as a dictionary. |
| **CSV** | `str` | Writes CSV data to file and returns the filename string. |
## quotes
```python
def quotes(
symbols: list[str] | str,
*,
use_52_week: bool = None,
extended: bool = None,
output_format: OutputFormat = OutputFormat.DATAFRAME,
date_format: DateFormat = None,
columns: list[str] = None,
add_headers: bool = None,
use_human_readable: bool = False,
mode: Mode = None,
filename: str | Path = None,
) -> list[StockQuote] | list[StockQuotesHumanReadable] | dict | str | MarketDataClientErrorResult
```
Fetches stock quotes for one or more symbols. The `symbols` parameter can be passed as the first positional argument or as a keyword argument. All other parameters must be keyword-only.
### Parameters
- `symbols` (list[str] | str)
A single symbol string or a list of symbol strings for which to fetch quotes.
- `use_52_week` (bool, optional)
Whether to use the 52 week high and low. Uses API alias `52week`.
- `extended` (bool, optional)
Whether to use the extended quotes.
- `output_format` ([OutputFormat](https://www.marketdata.app/docs/sdk/py/settings#output-format), optional)
The format of the returned data. Defaults to `OutputFormat.DATAFRAME`. See [Settings](https://www.marketdata.app/docs/sdk/py/settings) for details.
- `date_format` ([DateFormat](https://www.marketdata.app/docs/sdk/py/settings#date-format), optional)
The date format to use in the response. Defaults to `DateFormat.UNIX`. See [Settings](https://www.marketdata.app/docs/sdk/py/settings) for details.
- [`columns`](https://www.marketdata.app/docs/sdk/py/settings#columns) (optional)
Specify which columns to include in the response. If not provided, all available columns are returned. See [Settings](https://www.marketdata.app/docs/sdk/py/settings) for details.
- [`add_headers`](https://www.marketdata.app/docs/sdk/py/settings#headers) (optional)
Whether to include headers in the response. Uses API alias `headers`. See [Settings](https://www.marketdata.app/docs/sdk/py/settings) for details.
- [`use_human_readable`](https://www.marketdata.app/docs/sdk/py/settings#human-readable) (optional)
Whether to use human-readable format for values. Uses API alias `human`. Only applies when `output_format=OutputFormat.INTERNAL`. See [Settings](https://www.marketdata.app/docs/sdk/py/settings) for details.
- `mode` ([Mode](https://www.marketdata.app/docs/sdk/py/settings#data-mode), optional)
The data mode to use. Available options: `Mode.LIVE`, `Mode.CACHED`, `Mode.DELAYED`. See [Settings](https://www.marketdata.app/docs/sdk/py/settings) for details.
- `filename` (str | Path, optional)
File path for CSV output (only used with `output_format=OutputFormat.CSV`). Must end with `.csv`. Directory must exist. File must not already exist. If not provided, a timestamped file is created in `output/` directory.
### Returns
- `list[StockQuote]` | `list[StockQuotesHumanReadable]` | `dict` | `str` | `MarketDataClientErrorResult`
The quotes data in the requested format, or a `MarketDataClientErrorResult` if an error occurred.
### Notes
- When using `OutputFormat.DATAFRAME`, the DataFrame is indexed by the `symbol` column.
- When using `OutputFormat.INTERNAL`, timestamps are automatically converted to `datetime.datetime` objects.
- When using `OutputFormat.CSV`, the method writes to a file and returns the filename string.
### Example (DataFrame)
```python
from marketdata import MarketDataClient
client = MarketDataClient()
# Get stock quotes as DataFrame (default)
# symbols can be passed positionally or as keyword
df = client.stocks.quotes("AAPL")
# or
df = client.stocks.quotes(symbols="AAPL")
# Get quotes for multiple symbols
df = client.stocks.quotes(["AAPL", "MSFT"])
print(df)
```
**Output**
```
ask askSize bid bidSize mid last change changepct volume updated
symbol
AAPL 278.02 100 277.97 100 277.995 278.0188 -0.0112 0.0 4964676 2025-01-13 16:21:46
```
### Example (Internal)
```python
from marketdata import MarketDataClient, OutputFormat
client = MarketDataClient()
# Get stock quotes as internal objects
quotes = client.stocks.quotes("AAPL", output_format=OutputFormat.INTERNAL)
# Access individual quote properties
for quote in quotes:
print(f"Symbol: {quote.symbol}")
print(f"Ask: {quote.ask}")
print(f"Bid: {quote.bid}")
print(f"Mid: {quote.mid}")
print(f"Last: {quote.last}")
print(f"Change: {quote.change}")
print(f"Change Percent: {quote.change_percent}")
print(f"Volume: {quote.volume}")
print(f"Updated: {quote.updated}")
```
**Output**
```
Symbol: AAPL
Ask: 278.02
Bid: 277.97
Mid: 277.995
Last: 278.0188
Change: -0.0112
Change Percent: 0.0
Volume: 4964676
Updated: 2025-01-13 16:21:46
```
### Example (JSON)
```python
from marketdata import MarketDataClient, OutputFormat
client = MarketDataClient()
# Get stock quotes as JSON
quotes = client.stocks.quotes(["AAPL", "MSFT"], output_format=OutputFormat.JSON)
print(quotes)
```
**Output**
```json
{
"s": "ok",
"symbol": ["AAPL", "MSFT"],
"ask": [278.02, 479.45],
"askSize": [100, 40],
"bid": [277.97, 479.37],
"bidSize": [100, 40],
"mid": [277.995, 479.41],
"last": [278.0188, 479.42],
"change": [-0.0112, -4.05],
"changepct": [0.0, -0.0084],
"volume": [4964676, 3581398],
"updated": [1765552906, 1765552906]
}
```
### Example (CSV)
```python
from marketdata import MarketDataClient, OutputFormat
from pathlib import Path
client = MarketDataClient()
# Get stock quotes as CSV
csv_file = client.stocks.quotes(
["AAPL", "MSFT"],
output_format=OutputFormat.CSV,
filename=Path("quotes.csv")
)
print(f"CSV file saved to: {csv_file}")
```
**Output**
```
CSV file saved to: quotes.csv
```
### Example (Human Readable)
```python
from marketdata import MarketDataClient, OutputFormat
client = MarketDataClient()
# Get stock quotes in human-readable format
quotes = client.stocks.quotes(
"AAPL",
output_format=OutputFormat.INTERNAL,
use_human_readable=True
)
for quote in quotes:
print(f"Symbol: {quote.Symbol}")
print(f"Ask: {quote.Ask}")
print(f"Bid: {quote.Bid}")
print(f"Change Price: {quote.Change_Price}")
print(f"Change Percent: {quote.Change_Percent}")
```
**Output**
```
Symbol: AAPL
Ask: 278.55
Bid: 278.54
Change Price: 0.51
Change Percent: 0.0018
```
## StockQuote
```python
@dataclass
class StockQuote:
symbol: str
ask: float
askSize: int
bid: float
bidSize: int
mid: float
last: float
change: float
changepct: float
volume: int
updated: datetime.datetime
```
StockQuote represents a single stock quote, encapsulating various details such as prices, volumes, and timestamps.
### Properties
- `symbol` (str): The stock symbol.
- `ask` (float): The asking price for the stock.
- `askSize` (int): The size (quantity) of the ask.
- `bid` (float): The bidding price for the stock.
- `bidSize` (int): The size (quantity) of the bid.
- `mid` (float): The mid price calculated between the ask and bid prices.
- `last` (float): The last traded price for the stock.
- `change` (float): The price change.
- `changepct` (float): The percentage change in price.
- `change_percent` (float): Property that returns `changepct` for convenience.
- `volume` (int): The trading volume for the stock.
- `updated` (datetime.datetime): The time when the quote was last updated (automatically converted from timestamp).
### Notes
- The `updated` field is automatically converted to a `datetime.datetime` object from a Unix timestamp.
- The `change_percent` property provides convenient access to the `changepct` field.
## StockQuotesHumanReadable
```python
@dataclass
class StockQuotesHumanReadable:
Symbol: str
Ask: float
Ask_Size: int
Bid: float
Bid_Size: int
Mid: float
Last: float
Change_Price: float
Change_Percent: float
Volume: int
Date: datetime.datetime
```
StockQuotesHumanReadable represents a stock quote in human-readable format with capitalized field names and formatted values.
### Properties
- `Symbol` (str): The stock symbol.
- `Ask` (float): The asking price for the stock.
- `Ask_Size` (int): The size (quantity) of the ask.
- `Bid` (float): The bidding price for the stock.
- `Bid_Size` (int): The size (quantity) of the bid.
- `Mid` (float): The mid price calculated between the ask and bid prices.
- `Last` (float): The last traded price for the stock.
- `Change_Price` (float): The price change.
- `Change_Percent` (float): The percentage change in price.
- `Volume` (int): The trading volume for the stock.
- `Date` (datetime.datetime): The time when the quote was last updated (automatically converted from timestamp).
### Notes
- The `Date` field is automatically converted to a `datetime.datetime` object from a Unix timestamp.
- Field names use capitalized format with underscores (e.g., `Ask_Size` instead of `askSize`).
---
# Google Sheets Add-on Documentation
Source: https://www.marketdata.app/docs/sheets/index.md
Welcome to Market Data’s Google Sheets Add-On documentation.
---
# Authentication (Sheets)
Source: https://www.marketdata.app/docs/sheets/authentication/index.md
Market Data's Sheets Add-on uses **automatic Google Authentication** to authorize requests to Market Data's servers. This means that once you login to Sheets using your Google account, the Market Data Add-on will automatically link to your Market Data account _as long as you signed-up for a Market Data account using the same Google e-mail address_.
> [!WARNING]
> If you registered for Market Data with an e-mail address different from the one you use to log in to Google, you must update your Market Data account's e-mail to match your Google Sheets login e-mail.
## Changing Your Market Data Account E-mail Address
1. **[Login](https://dashboard.marketdata.app/marketdata/profile)** to your Market Data account.
2. This will open your account **Profile**.
3. Click on the **E-Your E-Mail Address** field.
4. Enter the e-mail address you use to login to Google Sheets.
5. Click on the **Save Profile** button.
6. Confirm the change by clicking on the confirmation link in the e-mail you receive.
## Troubleshooting
Almost all issues related to authentication can be solved by changing your Market Data account's e-mail address to the same e-mail address you use to login to Google Sheets.
If you continue to experience issues, please open a support ticket at our [helpdesk](https://dashboard.marketdata.app/marketdata/helpdesk).
### Multiple Google Accounts
If you have multiple Google accounts, you will need to make sure that you link your Market Data account with the same Google account you use to login to Google Sheets.
---
# Automatic Refreshing
Source: https://www.marketdata.app/docs/sheets/automatic-refresh/index.md
The WebSocket protocol is the technology used to deliver streaming quotes, such as the ones provided by your broker platform. Unfortunately, Google Workspace Add-ons do not yet offer support for WebSockets. This is why no Google Sheets Add-on has been able to deliver a product that supports streaming quotes.
Please be aware that this workaround is not officially supported by Market Data.
## Refresh Button
Market Data has provided a refresh button in the sidebar to allow customers to refresh whenever needed. We understand some customers would like to use streaming quotes, but that is impossible due to Google Sheets limitations.
## Workaround
There is a workaround that allows your formulas to update every 2-minutes. You can embed the result of the **GOOGLEFINANCE** formula as a column attribute in any of our formulas. Please be aware that during the standard session, this will consume 195 credits for each formula you prepare in this way.
> [!WARNING]
> Google Sheets has a hard limit of 20,000 [urlfetch](https://www.marketdata.app/docs/sheets/troubleshooting/urlfetch) requests per day. Even if you are on a Trader plan and have 100,000 credits, Google will not allow you to make more than 20,000 requests.
### Example Formulas
Place `=GOOGLEFINANCE("AAPL")` in a cell somewhere in your workbook. For this example, we'll assume it is in cell A1.
```excel-formula
=OPTIONDATA("AAPL271217C00250000","all,"&A1)
=STOCKDATA("AAPL","all,"&A1)
```
#### Why Is GOOGLEFINANCE Needed?
The GOOGLEFINANCE formula is a special formula that updates once every two minutes. By using it as a parameter in a Market Data formula, you force the Market Data formula to refresh itself every two minutes without the need to press the refresh button manually.
#### Why Can't Market Data Formulas Do This Automatically?
Google Sheets places strict limits on the ability of third party developers such as Market Data. Google does not give us the ability to make your formulas refresh automatically. However, by using this workaround, we can trigger a refresh every 2-minutes as GOOGLEFINANCE updates.
---
# Dates and Times (Sheets)
Source: https://www.marketdata.app/docs/sheets/dates-and-times/index.md
All Market Data formulas support advanced date-handling features to allow you to work with dates in a way that works best for your spreadsheet. Formulas will accept any of the following date formats:
- **American Numeric Notation** Dates and times in MM/DD/YYYY format. For example, closing bell on Dec 30, 2020 for the NYSE would be: 12/30/2020 4:00 PM.
- **Timestamp** An ISO 8601 timestamp in the format YYYY-MM-DD. For example, closing bell on Dec 30, 2020 for the NYSE would be: 2020-12-30 16:00:00.
- **Unix** Dates and times in unix format (seconds after the unix epoch). For example, closing bell on Dec 30, 2020 for the NYSE would be: 1609362000.
- **Spreadsheet** Dates and times in spreadsheet format (days after the Excel epoch). For example, closing bell on Dec 30, 2020 for the NYSE would be: 44195.66667
- **Relative Dates and Times** Keywords or key phrases that indicate specific days, relative to the current date. For example, "today" or "yesterday".
- **Option Expiration Dates** Keyphrase that select specific dates that correspond with dates in the US option expiration calendar.
## Relative Dates and Times
Relative dates allow Market Data formulas to continually modify the date sent to the formula based on the current date. We have a lot of relative date keywords supported already and quite a few more planned for the future, so keep an eye out on this section for continual improvements to this feature.
- **Time-based Parameters** Time keyphrases let you select a specific time of day, relative to the current time. Time-based parameters are typically used to model intraday stock movements.
- `now` The current time. Use this keyword to select the current open candle, for example. This is the same as the Google Sheets built-in formula `now()`. Please note that due to technical limitations by Google Sheets, `now()` cannot be embedded in or referenced by any Market Data formula. Use the `now` relative keyword as a replacement.
- `-[number] minutes` Use negative minutes to specify a time in the past _n_ minutes before. When this is used alone, it is relative to the current time. When used in conjunction in `from` field (i.e. the starting date/time), it is relative to the `to` field (i.e. the ending date/time). For example, if the current time is 10:30 AM, but 10:00 AM is used in the `to` field and `-10 minutes` in the `from` field, then the starting time will be 9:50 AM. The query would return values from 9:50 AM to 10:00 AM. However, if the `to` field were to be omitted, then the same query would return data from 10:20 AM to 10:30 AM since `-10 minutes` would be relative to the current time of 10:30 AM.
- `[number] minutes ago` The `minutes ago` keyword lets you select a relative time, _n_ minutes before the current time. For example, if the time is 10:00 AM then `30 minutes ago` would refer to 9:30 AM of the current day.
- `-[number] hours` Use negative hours to specify a time in the past _n_ hours before. When this is used alone, it is relative to the current time. When used in conjunction in `from` field (i.e. the starting date/time), it is relative to the `to` field (i.e. the ending date/time). For example, if the current time is 10:30 AM, but 10:00 AM is used in the `to` field and `-1 hour` in the `from` field, then the starting time will be 9:00 AM. The query would return values from 9:00 AM to 10:00 AM. However, if the `to` field were to be omitted, then the same query would return data from 9:30 AM to 10:30 AM since `-1 hour` would be relative to the current time of 10:30 AM.
- `[number] hours ago` The `hours ago` keyword lets you select a relative time, _n_ hours before the current time. For example, if the time is 4:00 PM then `4 hours ago` would refer to 12:00 PM of the current day.
- **Daily Parameters** Daily keyphrases let you select a specific day, relative to the current day.
- `today` Equivalent to today's date. This keyword can be used interchangeably with Sheets' built-in formula `today()`.
- `yesterday` Yesterday's date. The same as Sheets formula `today()-1`.
- `last session` Returns the date of the last closed market session. This keyphrase always gets the previous closed session, accounting for weekends, holidays, and half-days (which are counted as valid sessions). For example, on Monday during market hours, it would return Friday's date. After market close on Monday, it would return Monday's date. This allows you to always track the previous session without having to account for weekends, holidays, or other market closures.
- `-[number] days` Use negative days to specify a time in the past _n_ days before. When this is used alone, it is relative to the current day. When used in conjunction in `from` field (i.e. the starting date), it is relative to the `to` field (i.e. the ending date). For example, if the current date is January 20, but January 10 is used in the `to` field and `-5 days` in the `from` field, then the starting day will be January 5. The query would return values from January 5 to January 10. However, if the `to` field were to be omitted, then the same query would return data from January 15 to January 20 since `-5 days` would be relative to the current date of January 20.
- `[number] days ago` The `days ago` keyword lets you select a relative day, _n_ days before the current date. For example, if today is January 5, 2024, then using `2 days ago` would select the date January 3, 2024.
- **Weekly Parameters** Weekly keyphrases let you select a day of the week in the current, previous, or following week.
- `-[number] weeks` Use negative weeks to specify a date in the past _n_ weeks before. When this is used alone, it is relative to the current day. When used in conjunction in `from` field (i.e. the starting date), it is relative to the date in the `to` field (i.e. the ending date). For example, if the current date is October 15, 2023 but October 8 is used in the `to` field and `-1 week` in the `from` field, then the starting day will be October 2, 2023. The query would return values from October 2 to October 8. However, if the `to` field were to be omitted, then the same query would return data from October 9 to October 15 since `-5 days` would be relative to the current date of January 20.
- `[number] weeks ago` The `weeks ago` keyword lets you select a relative week, _n_ weeks before the current date. For example, if today is January 1, 2024, then using `2 weeks ago` would select the date January 3, 2024.
- **Monthly Dates** Monthly keyphrases let you select a specific day of a specific month.
- `-[number] months` Use negative months to specify a date in the past _n_ months before. When this is used alone, it is relative to the current day. When used in conjunction in `from` field (i.e. the starting date), it is relative to the date in the `to` field (i.e. the ending date). For example, if the current date is October 15 but October 8 is used in the `to` field and `-1 month` in the `from` field, then the starting day will be September 8. The query would return values from September 8 to October 8. However, if the `to` field were to be omitted, then the same query would return data from September 15 to October since `-1 month` would be relative to the current date of October 15.
- `[number] months ago` The months ago keyword lets you select a relative date, _n_ months before the current date. For example, if today is January 5, 2024, then using `3 months ago` would select the date October 5, 2023.
- **Yearly Dates** Yearly keyphrases let you select a specific day of in the current, previous, or following year.
- `-[number] years` Use negative years to specify a date in the past _n_ years before. When this is used alone, it is relative to the current day. When used in conjunction in `from` field (i.e. the starting date), it is relative to the date in the `to` field (i.e. the ending date). For example, if the current date is October 15, 2023 but October 8, 2023 is used in the `to` field and `-1 year` in the `from` field, then the starting day will be September 8, 2022. The query would return values from September 8, 2022 to October 8, 2023. However, if the `to` field were to be omitted, then the same query would return data from September 15, 2022 to October 15, 2023 since `-1 year` would be relative to the current date of October 15, 2023.
- `[number] years ago` The years ago keyword lets you select a relative date, 365 days before the current date. For example, if today is January 5, 2024, then using `2 years ago` would select the date January 5, 2022.
> [!CAUTION]
> **[Coming Soon]**
>
>
> The following relative date parameters are planned for the future and have not yet been implemented.
- **Time-based Parameters** Time keyphrases let you select a specific time of day, relative to the current time. Time-based parameters are typically used to model intraday stock movements.
- `at open`, `opening bell`, `market open` These keyphrases let you select the opening time for the market day. The phase is relative to each exchange's opening time. For example, if you were trading AAPL in the United States, using `at open` would set a time of 9:30 AM ET.
- `at close`, `closing bell`, `market close` These keyphrases let you select the closing time for the market day. The phase is relative to each exchange's closing time. For example, if you were trading AAPL in the United States, using `at close` would set a time of 4:00 PM ET.
- `[number] [minutes|hours] before [open|close]` These before keyword lets you select a relative time before market open or close. For example `30 minutes before close` would select the time 3:30 PM ET if you are trading a stock on a U.S. exchange.
- `[number] [minutes|hours] after [open|close]` These after keyword lets you select a relative time after market open or close. For example `1 hour after open` would select the time 10:30 AM ET if you are trading a stock on a U.S. exchange.
- **Weekly Parameters** Weekly keyphrases let you select a day of the week in the current, previous, or following week.
- `this [day of the week]` Works the same way as specifying the day without adding _this_. The day in the _current_ week. For example, if today is Tuesday and the expression is `this Monday`, the date returned would be yesterday. If the expression were `this Wednesday` the date returned would be tomorrow. The word _this_ is optional. If it is omitted, the keyword will still return the date in the current week that corresponds with the day mentioned.
- `last [day of the week]` The day in the _previous_ week. For example, if today is Tuesday and the expression used is `last Monday`, it would not refer to the Monday that occurred yesterday, but the Monday 8 days prior that occurred in the previous week.
- `next [day of the week]` The day in the _following_ week. For example, if today is Monday and the expression is `next Tuesday` it would not refer to tomorrow, but the Tuesday that occurs 8 days from now.
- **Monthly Dates** Monthly keyphrases let you select a specific day of a specific month.
- `[ordinal number] of [the|this] month` - The nth day of the current month. For example, if today is September 10th and the phrase used is, `8th of this month` the date returned would be September 8. The keyphrase `of [the/this] month` is optional. Using a single ordinal number `8th` will also return the 8th of the current month.
- `[ordinal number] of last month` - The nth day of the current month. For example, if today is December 15th and the phrase used is, `8th of last month` the date returned would be November 8.
- `ordinal number] of next month` - The nth day of the following month. For example, if today is December 15th and the phrase used is, `8th of next month` the date returned would be January 8 of the following year.
- `last day of [the|this|last|next] month` - Using the `last day of` keyword will always select the final day of the month. Since months can end on the 28th, 29th, 30th, or 31st, this keyword allows you to always select the final day of a month. For example: `last day of this month`, `last day of next month`. It can also be used to select the last day in February without needing to determine whether the current year is a leap year, `last day of february`.
- `ordinal number] [day of the week] of [the|this|last|next] month` - Combine ordinal numbers and weekdays to specify a specific day of the week in the current, previous, or following month. For example, ``3nd Friday of last month``.
- `last [day of the week] of [the|this|last|next] month` - Selects the last day of the week in a month relative to the current month. If the last Monday of the month is needed, instead of using the keyphrase `4th Monday of this month`, it is safer to use `last Monday of this month`, since months can have 4 or 5 Mondays, depending on length.
- `last [day of the week] in [month` - Selects the last day of the week in a specific month. For example, Memorial Day could be selected by using the keyphrase `last Monday in May`.
- **Yearly Dates** Yearly keyphrases let you select a specific day of in the current, previous, or following year.
- `[month] [number]` A specific date in the current year. For example `February 18` would return February 18 of the current year.
- `[month] [number] [this|last|next] year` A specific date in the current, previous, or following year. For example, if today was Dec 31, 2022, `February 18 next year` would return February 18, 2023.
## Option Expiration Dates
Option expiration dates let you target the expiration dates for option contracts. Dates are based on the US option expirations calendar and are only meant for use with US markets.
> [!CAUTION]
>
> Option date parameters are planned for the future and have not yet been implemented.
>
> ---
>
> Option-related keyphrases cannot be used to return expiration dates far in the future for options which have not yet been traded or for options in the past which have already expired. For example, if today is January 15, 2023, you couldn't use `November 2023's 1st weekly expiration` since weekly options for November would not exist yet. The formula will return a `No data` response if you try to request an expiration that does not exist, whether in the future or the past.
- **Monthly Expirations** - Target a relative month or specific month's option expiration date.
- `[month] [year] expiration` - The standard monthly option expiration date for [month] during [year]. This is useful for targeting the expiration date for a specific month. Although options normally expire the 3rd Friday, sometimes market holidays can modify this schedule. Using an option expiration keyphrase will ensure that you always obtain the exact date that options expire in a specific month. For example, if today was January 1, 2022, using `December expiration` or `December 2022 expiration` would both return _December 16, 2022_.
- [year] is optional. If [month] is used without [year] the lookup is relative to the current date and expired options will not be returned. For example, if today is April 8, 2022, `January expiration` will return January 20, 2023 and not the options which expired in January of 2022.
- `this|last|next] month's expiration` - Returns the monthly option expiration date for the current, previous, or following month relative to the current month. For example if today is October 5, 2022, and `next month's expiration` is used, the date returned would be _November 18, 2022_.
> [!TIP]
>
> Not all underlying tickers offer weekly or quarterly options. Before building a spreadsheet that uses them, ensure that your underlying offers weekly or quarterly option contracts.
- **Weekly Expirations** - Target a relative week or specific week's option expiration date.
- `[this|last|next] week's expiration` - Returns the weekly option expiration date for the current, previous, or following week relative to the current week. For example if today is October 5, 2022, and `next week's expiration` is used, the date returned would be _October 14, 2022_.
- `expiration in [number] weeks` - Returns closest expiration that will occur [number] weeks from today without taking into account the current week. For example, if today is August 1, 2022 the phrase `expiration in 6 weeks` would return September 16, 2022.
- `[month] [year] [ordinal number] weekly expiration` - Returns the nth option expiration date for [month] during [year]. When both a month and year are combined, this can be used to lookup a weekly option date for an expired or unexpired option. For example, `March 2020's 2nd expiration` would return _March 14, 2020_.
- **Quarterly Expirations** - Returns a quarterly expiration date for a relative date or specifically targeted date.
- `[ordinal number] quarter's expiration` - Returns the quarterly option expiration date for the 1st, 2nd, 3rd, or 4th quarter in the current financial year. For example if today is March 1, 2022, and `4th quarter's expiration` is used, the date returned would be _December 30, 2022_. This will lookup both expired and unexpired options.
- `[this|last|next] quarter's expiration` - Returns the quarterly option expiration date for the current, previous, or following quarter relative to the current date. For example if today is March 1, 2022, and `this quarter's expiration` is used, the date returned would be _March 31, 2022_.
- `[expiration in [number] quarters` - Returns closest quarterly expiration that will occur [number] quarters from today without taking into account the current quarter. For example, if today is March 1, 2022 the phrase `expiration in 2 quarters` would return September 30, 2022.
- `[year] [ordinal number] quarter expiration` - Returns the option expiration date for [nth] quarter during [year]. For example, `2020's 2nd quarter expiration` would return _June 30, 2020_.
- **Specific Contract Expirations** - Target a specific date based on when a contract is first traded or when it expires.
- `at expiration` - Returns the expiration date for the option contract. This must be used in the context of a specific option contract. For example, if you used at expiration with AAPL271217C00250000, the date returned would be December 17, 2027.
- `first traded` - Returns the date when the contract was traded for the first time. This must be used in the context of a specific option contract. For example, if you used first traded with AAPL271217C00250000, the date returned would be March 13, 2025.
---
# Market Formulas
Source: https://www.marketdata.app/docs/sheets/markets/index.md
---
# MARKETSTATUS
Source: https://www.marketdata.app/docs/sheets/markets/marketstatus/index.md
Get the past, present, or future status for a stock market for a single date or multiple dates. The formula will respond with "open" for trading days or "closed" for weekends or market holidays.
## Sample Usage
```excel-formula
=MARKETSTATUS()
=MARKETSTATUS("US","all","1/1/2022","12/31/2022")
=MARKETSTATUS("US","status","yesterday")
```
## Syntax
```excel-formula
=MARKETSTATUS(country, [attributes], start date, end date)
```
- **country** _(OPTIONAL)_ The two-letter country code. Currently only the US is supported.
- **[attributes]** _(OPTIONAL)_ Use one or more of the following attributes:
- "date" – The date that the market was either open or closed.
- "status" – The status of the market, either `open` or `closed`.
- "all" – Returns all values.
- **start date** _(OPTIONAL)_ The start date when fetching the market's status. If start date is specified, but end date is not, only the single day’s data is returned.
- **end date** _(OPTIONAL)_ The end date when fetching the market's status, or the number of calendar days (not trading days) from the `start date` from which to return data.
## Notes
- All parameters must be enclosed in quotation marks or be references to cells containing text. A possible exception is when end date is specified as a number of days.
---
# Option Formulas
Source: https://www.marketdata.app/docs/sheets/options/index.md
---
# OPTIONCHAIN
Source: https://www.marketdata.app/docs/sheets/options/optionchain/index.md
Fetches a current option chain, or the end-of-day option chain of a past trading day, from Market Data.
## Video Tutorial
## Sample Usage
```excel-formula
=OPTIONCHAIN("AAPL","all","1/17/2025")
=OPTIONCHAIN("AAPL","side,strike,bid,ask,","1/17/2025")
=OPTIONCHAIN("AAPL","all,noheaders","60 DTE","150,160)
=OPTIONCHAIN("AAPL","all","60 DTE","100-200","calls")
```
### Historical Chains
```excel-formula
=OPTIONCHAIN("AAPL","strike,bid,ask","45 DTE","200-250","puts","2026-09-01")
=OPTIONCHAIN("AAPL",,,,,"last session")
=OPTIONCHAIN(A2,"strike,bid,ask","45 DTE","200-250","puts",B2)
```
## Syntax
```excel-formula
=OPTIONCHAIN(underlying symbol, [attributes], expiration date, [strikes], [filters], [as of])
```
- **underlying symbol** _(REQUIRED)_ Use the stock, etf, or underlying index symbol.
- **attributes** _(OPTIONAL "all" by default)_ Use one or more of the following attributes; seperate multiple attributes with commas:
- "symbol" - The OCC option symbol.
- "underlying" - The underlying symbol.
- "expiration" - The option's expiration date.
- "side" - Call or put.
- "strike" - The option's strike price.
- "first traded" - The date this option first began to trade.
- "dte" - Days to expiration: the calendar days until the option expires, counted from today on a current quote and from the quote date on a historical one.
- "date", "updated" - The date and time of the quote.
- "bid" – The bid price of the option.
- "bid size" – The quantity of contracts offered at the bid price.
- "mid", "price", "mark" – The midpoint price of the option.
- "ask" – The ask price of the option.
- "ask size" – The quantity of contracts offered at the ask price.
- "last" – The last price of the option. Depending on the liquidity of the symbol, the last traded price could have occurred one second ago or one day ago.
- "open interest" – The number of open contracts. Open interest is published once per trading day, before the open, and does not change intraday. On a historical request it is the figure settled out of the previous session, so it lags every other field in the row by one session.
- "volume" – The number of contracts negotiated during the day.
- "in the money" – Will return TRUE if the option contract was in the money at the time of the quote or FALSE if the contract was not in the money at the time of the quote.
- "intrinsic value" - The intrinsic value of the option, if any.
- "extrinsic value" - The extrinsic or time value of the option.
- "underlying price" – The price of the underlying security at the time of this option quote.
- "iv", "implied volatility" - The implied volatility of the option.
- "delta" - The delta of the option.
- "gamma" - The gamma of the option.
- "theta" - The theta of the option.
- "vega" - The vega of the option.
- "all" – Returns all values.
- "noheaders" – Returns values without column headers.
- **expiration date** - _(OPTIONAL)_ - The expiration date of the option chain. Options from this expiration will be returned. If no value is specified, the next monthly expiration will be used.
- "date" - A single date in YYYY-MM-DD or MM/DD/YYYY format enclosed between quotes.
- \[date cell reference] - A cell reference to a date in Sheets.
- "dte _number_" - Days to expiry. Return the expiration date most closely matching the indicated number. For example, if today was Jan 1 and you used a DTE of 45, the expiration closest to Feb 15 would be selected. With an **as of** date, the days are counted from that date instead of today.
- The expiration date is always the contract's expiration, never the quote date. To see a chain as it was on a past day, use **as of**.
- **strikes** _(OPTIONAL)_ – Limit the strikes returned from the option chain formula to only the specified strikes or deltas. The formula will assume strikes for numbers greater than 1 and deltas for numbers less than 1 or when the word `delta` is placed before the number(s).
- \[number] - A single number or a cell reference to a number. Example: `150`
- \[decimal] - A decimal number will be interpreted as a delta value to be matched and the formula will return the strike that most closely matches the delta provided. Example: `.60`
- \[range of numbers] - A range of strikes falling between two numbers. Example: `"100-200"`
- \[range of decimals] - A range of deltas falling between two decimals. Example: `".50-.60"`
- "delta \[number]" - Use a single number for delta or a cell reference to a number. Example: `"delta .60"`
- \{array of numbers\} - Use a one column array containing each strike or a cell reference to the array. Example: `{1;2;3;4}`
- \{array of decimals\} - Use a one column array containing each delta or a cell reference to the array. Example: `{.50;.60;.70;.80}`
- "string of numbers" - Seperate multiple strikes with commas. Example: `"150,160,170"`
- "string of decimals" - Seperate multiple deltas with commas. Example: `".50,.60.,70"`
- "logical expression" - A logical expression. Example: `"<200 delta <.50"`
- "limit \[number]" - Limit the output to \[number] strikes closest to the money. Example: `"limit 4"`
- Deltas are only available for current chains. Selecting strikes by delta together with an **as of** date returns an error; use strikes instead.
- **filters** _(OPTIONAL)_ – Use specific keywords to further filter the option chain.
- "call", "calls" - Only return calls.
- "put", "puts" - Only return puts.
- "itm", "in the money" - Only return in the money options.
- "otm", "out of the money" - Only return out of the money options.
- "nonstandard", "non-standard" - Include non-standard contracts in the optionchain output.
- **as of** _(OPTIONAL)_ – The quote date. Leave it out for the current chain, or give one past trading day to get that day's end-of-day chain. See [Working With Historical Chains](#working-with-historical-chains).
- _(omitted)_ or "current" - The current chain, the same as a formula without this parameter.
- "date" - A single date in YYYY-MM-DD or MM/DD/YYYY format enclosed between quotes.
- \[date cell reference] - A cell reference to a date in Sheets.
- "last session" - The most recent trading day whose end-of-day chain has been published.
- "yesterday", "today" - The calendar day before today, or today. On a weekend or holiday these return an error, so "last session" is usually the better choice.
- An empty cell or `""` returns an error, not the current chain. To switch a sheet between current and historical chains with one cell, write "current" in it.
## Usage Information
### Data Availability
Without an **as of** date, the `OPTIONCHAIN` function fetches current option chain data. The type of data you receive depends on your user type and OPRA entitlement. This may include real-time data, 15-minute delayed data, or historical data, depending on the plan or access level. To get real-time options data, users need to sign the OPRA agreement.
| User Type | OPRA Entitlement | Data Type |
|------------------|------------------|------------------------|
| Non-Professional | ✅ | Real-time |
| Non-Professional | ❌ | 15-min delayed |
| Professional | ✅ | 15-min delayed |
| Professional | ❌ | Historical (1 day old) |
| Unknown | Any | Historical (1 day old) |
### Working With Historical Chains
With an **as of** date, `OPTIONCHAIN` returns the chain as it closed on that trading day.
- Only end-of-day chains are available. There are no intraday snapshots, and only one date per formula.
- The columns are the same as for a current chain. Implied volatility and the greeks (delta, gamma, theta, vega) are blank, and selecting strikes by delta is not available.
- Open interest is the figure settled out of the previous session, as described under the "open interest" attribute.
- A date in the future, a weekend or a market holiday returns an error. Today's chain returns a "not available yet" error until the end-of-day chain is published after the close.
- A relative date such as "last session" is resolved when the formula calculates. It updates when the sheet is refreshed or a referenced cell changes, not on its own as days pass.
- Historical data is subject to your plan's limits. [Learn more about plan limits](https://www.marketdata.app/docs/account/plan-limits).
> [!NOTE]
> **[What are entitlements?]**
>
> Entitlements are permissions granted by exchanges that allow access to their data. To get real-time options data, users need to sign the [OPRA agreement](https://www.marketdata.app/docs/account/entitlements). [Learn more about entitlements](https://www.marketdata.app/docs/account/entitlements).
## Notes
- All parameters must be enclosed in quotation marks or be references to cells containing text.
- Dates and times are returned in the same timezone of the exchange.
---
# OPTIONDATA
Source: https://www.marketdata.app/docs/sheets/options/optiondata/index.md
Fetches current or historical option quotes from Market Data, for one option contract or many at once.
## Sample Usage
```excel-formula
=OPTIONDATA("AAPL271217C00250000")
=OPTIONDATA("AAPL271217C00250000", "bid")
=OPTIONDATA("AAPL271217C00250000", "date,bid,ask", "9/1/2022", "1/31/2023")
=OPTIONDATA("AAPL271217C00250000", "all", TODAY()-30, 30)
```
### Multiple Contracts
```excel-formula
=OPTIONDATA(A1:A500)
=OPTIONDATA(A1:A500, "bid,ask,noheaders")
=OPTIONDATA("AAPL271217C00250000,AAPL271217P00250000", "mid")
=OPTIONDATA(A1:A500, "mid", "9/15/2026")
=OPTIONDATA(A1:D50, "symbol,mid")
```
## Syntax
```excel-formula
=OPTIONDATA(option symbol, [attributes], start date, end date)
```
- **option symbol** _(REQUIRED)_ Use the current OCC option symbol format for the option symbol, even for historic options prior to the symbol format change in 2010. Several contracts can be fetched at once: pass a range of cells in a single row or a single column, several OCC symbols separated by commas, or a table of four columns with one contract per row. See [Working With Multiple Contracts](#working-with-multiple-contracts).
- **attribute** _(OPTIONAL "price" by default)_ Use at least one of the following attributes; seperate multiple attributes with commas:
- "symbol" - The OCC option symbol.
- "underlying" - The underlying symbol.
- "expiration" - The option's expiration date.
- "side" - Call or put.
- "strike" - The option's strike price.
- "first traded" - The date this option first began to trade.
- "dte" - Days to expiration: the calendar days until the option expires, counted from today on a current quote and from the quote date on a historical one.
- "date", "updated" - The date and time of the quote.
- "price", "mid", "mark" – The midpoint price of the option.
- "bid" – The bid price of the option.
- "ask" – The ask price of the option.
- "last" – The last price of the option. Depending on the liquidity of the symbol, the last traded price could have occurred one second ago or one day ago.
- "bid size" – The quantity of contracts offered at the bid price.
- "ask size" – The quantity of contracts offered at the ask price.
- "volume" – The number of contracts negotiated during the day.
- "open interest" – The number of open contracts. Open interest is published once per trading day, before the open, and does not change intraday. On a historical request it is the figure settled out of the previous session, so it lags every other field in the row by one session.
- "underlying price" – The price of the underlying security at the time of this option quote.
- "in the money" – Will return TRUE if the option contract was in the money at the time of the quote or FALSE if the contract was not in the money at the time of the quote.
- "intrinsic value" - The intrinsic value of the option, if any.
- "extrinsic value" - The extrinsic or time value of the option.
- "iv", "implied volatility" - The implied volatility of the option.
- "delta" - The delta of the option.
- "gamma" - The gamma of the option.
- "theta" - The theta of the option.
- "vega" - The vega of the option.
- "all" – Returns all values.
- "noheaders" – Returns values without column headers.
- **start date** _(OPTIONAL)_ – The start date when fetching historical data. If start date is specified, but endDate is not, only the single day's data is returned. When fetching more than one contract, only a single date may be used.
- **end date** _(OPTIONAL)_ – The end date when fetching historical data, or the number of calendar days (not trading days) from startDate for which to return data.
## Usage Information
### Data Availability
The `OPTIONDATA` function can return both current option quotes and historical option quotes, depending on whether date parameters are specified. **Data availability restrictions based on user type and exchange entitlements only apply to current quotes.** Historical data is available to all users, with access limits based on your plan.
> [!NOTE]
> **[What are entitlements?]**
>
> Entitlements are permissions granted by exchanges that allow access to their data. To get real-time options data, users need to sign the [OPRA agreement](https://www.marketdata.app/docs/account/entitlements). [Learn more about entitlements](https://www.marketdata.app/docs/account/entitlements).
#### Current Quotes (No Date Parameters)
When you use `OPTIONDATA` without date parameters, it returns current option quote data. **The data type you receive depends on your user type and OPRA entitlement.** This may include real-time data, 15-minute delayed data, or historical data (1 day old), depending on your entitlements and user classification.
| User Type | OPRA Entitlement | Data Type |
|------------------|------------------|------------------------|
| Non-Professional | ✅ | Real-time |
| Non-Professional | ❌ | 15-min delayed |
| Professional | Any | Historical (1 day old) |
| Unknown | Any | Historical (1 day old) |
#### Historical Quotes (With Date Parameters)
When you use `OPTIONDATA` with date parameters, it returns historical option quote data. **Historical data is available to all users regardless of exchange entitlements.** However, the age of historical data you can access depends on your plan:
| Plan | Historical Data Availability |
|-------------------------------|------------------------------|
| Free Forever | 1 year |
| Trial Plans (Starter, Trader) | 1 year |
| Starter | 5 years |
| Trader, Quant, Prime | No limit (full access) |
> [!NOTE]
> **[Plan Limits]**
>
> If you attempt to access historical data older than your plan's limit permits, the formula will return an error. [Learn more about plan limits](https://www.marketdata.app/docs/account/plan-limits).
### Working With Multiple Contracts
A single `OPTIONDATA` formula can fetch quotes for many option contracts at once. Pass a range of cells, several OCC symbols separated by commas, or a table of contracts as the option symbol.
- One row comes back for each contract, in the same order as your cells, even when the range is a row. Wrap the formula in `TRANSPOSE()` to lay the results out horizontally.
- A contract that cannot be served (not found, expired, or misspelled) keeps its place, so the results stay aligned with your contracts. Its row shows what you entered in the symbol column, with the other columns blank, so you can spot it. Request the `symbol` attribute to see it; without it the row is blank.
- Use a single historical date (start date only). Date ranges are not supported with more than one contract.
- A range must be a single row, a single column, or a table of exactly four columns. Any other table, such as three or five columns, returns an error.
- A row of four cells can describe one contract in parts: underlying, expiration date, strike and side (for example, `AAPL | 12/17/2027 | 250 | call`). On its own, a row like that is read as a single contract, so it also accepts a date range.
- With more than one contract the results include a header row. Add `noheaders` to the attributes to line the results up with your cells.
- For best results use OCC symbols, or a table with dates in `YYYY-MM-DD` format and numeric strikes. Contracts written in words are slower to read, and a long list of them may fill in over a few refreshes.
#### Tables of Contracts
A table of four columns is read as one contract per row, with the underlying, expiration date, strike and side in its columns:
| | A | B | C | D |
|---|------|------------|-----|------|
| 1 | AAPL | 2027-12-17 | 250 | call |
| 2 | AAPL | 2027-12-17 | 250 | put |
| 3 | MSFT | 2027-12-17 | 500 | call |
`=OPTIONDATA(A1:D3, "symbol,mid")` returns a header row and one row for each of the three contracts.
- The columns can be in any order. The first row sets it, and every other row is read the same way.
- Because of that, the first row must be a contract, not a header. A table that starts with a header row returns an error, so start the range on the first contract (for example, `A2:D50`).
- A later row that does not fit the order of the first row (columns swapped, a missing or misspelled cell) fails on its own, without affecting the other rows.
## Notes
- All parameters must be enclosed in quotation marks or be references to cells containing text. A possible exception is when end date is specified as a number of days.
- Results will be returned as a value within a single cell if a single attribute is requested for a single contract. Multiple attributes, multiple contracts or multi-day results will be returned with column headers.
- Dates and times are returned in the same timezone of the exchange.
---
# OPTIONLOOKUP
Source: https://www.marketdata.app/docs/sheets/options/optionlookup/index.md
Look-up the OCC option symbol from text or 4 cell references containing (1) underlying symbol, (2) expiration date, (3) strike, (4) call or put.
> [!TIP]
> It is not necessary to know the exact date of the option expiration. The formula will assume the monthly option expiration if both the month and the year are provided. If only the month is provided with no day or year, the formula will assume an unexpired option for the current year or the next year.
## Video Tutorial
## Sample Usage
```excel-formula
=OPTIONLOOKUP("AAPL 7/21/2023 200 Call")
=OPTIONLOOKUP("AAPL 7/2023 $200 Call")
=OPTIONLOOKUP("AAPL July 2023 200 Call")
=OPTIONLOOKUP("AAPL Jan 200 Call")
=OPTIONLOOKUP(A1:D1)
```
## Syntax
```excel-formula
=OPTIONLOOKUP("text")
```
- **text** _(REQUIRED)_ Text or 4 cell references containing (1) underlying symbol, (2) expiration date, (3) strike, (4) call or put.
## Notes
- All parameters must be enclosed in quotation marks or be references to 4 cells containing (1) underlying symbol, (2) expiration date, (3) strike, (4) call or put.
---
# Sharing Your Sheet
Source: https://www.marketdata.app/docs/sheets/sharing/index.md
It is possible to share you sheet with other users by using the **Share** button in the top right corner of the sheet. You can share the sheet with anyone who has a Google account. The only two requirements are that each user who receives a copy of your sheet must have the [Market Data Add-on](https://workspace.google.com/marketplace/app/market_data/453586334945) installed from the Google Workspace Marketplace and have a Market Data account.
> [!WARNING]
> If you share your sheet with a user who does not have a Market Data account, they will not be able to execute the formulas in the sheet. They will receive an error message and the Market Data formulas will not execute.
## Sharing Mode
You must share your sheet in **Edit** mode to allow a user to open the sidebar and execute the formulas. If you share your sheet in **View** or **Comment** mode, the Market Data formulas will not execute because the user will not have access to the sidebar.
## Sharing with Free or Trial Users
You can share your sheet with free or trial users but these users will not have access to real-time data. They will only have access to delayed and historical data. If you need to share your sheet with another user who needs real-time data, each user will need to have a paid Market Data account.
---
# Stock Formulas
Source: https://www.marketdata.app/docs/sheets/stocks/index.md
---
# EARNINGS
Source: https://www.marketdata.app/docs/sheets/stocks/earnings/index.md
> [!NOTE]
> **[Premium Formula]**
>
> This formula can only be used with paid plans. Free plans or trial plans will not work.
Fetches current or historical earnings data for a stock ticker.
## Sample Usage
```excel-formula
=EARNINGS("AAPL")
=EARNINGS("AAPL", "all,noheaders")
=EARNINGS("AAPL", "year,quarter,eps,eps surprise", "1/1/2021", "12/31/2021")
```
## Syntax
```excel-formula
=EARNINGS(symbol, [attributes], start date, end date)
```
- **symbol** _(REQUIRED)_ The stock’s ticker symbol.
- **[attributes]** _(OPTIONAL)_ Use one or more attributes to customize the response:
- "symbol" – The ticker symbol for the stock.
- "year" – The fiscal year for the earnings report.
- "quarter" – The fiscal quarter for the earnings report.
- "date" – The date of the earnings report. This is usually expressed as the last day of the quarter.
- "report date" – The date the company reported the earnings.
- "report time" - The time the company plans to report earnings.
- "currency" - The currency earnings are reported in.
- "reported eps" - The earnings per share reported by the company.
- "estimated eps" - The estimated earnings per share by Wall Street.
- "surprise eps" - The difference in eps between Wall Street and the actual earnings report.
- "surprise eps percent" - The difference in percentage terms between the reported EPS and estimated EPS.
- "updated" - The date and time the earnings data for this ticker was lasted refreshed.
- "all" – Returns all values.
- **start date** _(OPTIONAL)_ The start date when fetching data. If start date is specified, but end date is not, only the single day’s data is returned.
- **end date** _(OPTIONAL)_ The end date when fetching data, or the number of calendar days (not trading days) from start date for which to return data.
## Notes
Non-GAAP earnings are reported for most tickers. If the company does not report non-GAAP earnings, GAAP earnings will be used instead.
> [!WARNING]
> **[Estimated Dates for Future Earnings]**
>
> For upcoming earnings events, the report date is an **estimate** based on historical reporting patterns and is not a confirmed date. These dates frequently change as companies update their reporting schedules. Only after a company has actually reported its earnings does the report date become a confirmed, historical data point. Do not make trading decisions based on estimated future earnings dates.
---
# STOCKDATA
Source: https://www.marketdata.app/docs/sheets/stocks/stockdata/index.md
Fetches a current stock quote or historical stock candles from Market Data. It can also fetch a single historical candle for multiple stocks.
## Sample Usage For Quotes
```excel-formula
=STOCKDATA("AAPL")
```
### Bulk Quotes
```excel-formula
=STOCKDATA("AAPL,MSFT,TSLA")
=STOCKDATA("AAPL,MSFT,TSLA", "all")
=STOCKDATA(A1:A500, "bid,ask,last")
```
## Sample Usage For Candles
```excel-formula
=STOCKDATA("AAPL", "close", "1/1/2021", "1/31/2021", "hourly")
=STOCKDATA("AAPL", "all", TODAY()-30, 30)
```
### Bulk Candles
```excel-formula
=STOCKDATA("AAPL,MSFT,TSLA", "all", "today")
=STOCKDATA("AAPL,MSFT,TSLA", "all", "12/20/2023")
=STOCKDATA(A1:A3, "all", "12/20/2023")
```
## Syntax
```excel-formula
=STOCKDATA(symbols, [historial attributes|quote attributes], start date, end date, resolution)
```
- **symbols** _(REQUIRED)_ One or more ticker symbols for the stocks.
- **[historial attributes | quote attributes]** _(Optional)_ Use a historical or quote attribute:
- **"price"** _(OPTIONAL)_ Special dual-mode quote/candle attribute.
- Displays the midpoint price during the regular and sessions.
- Displays the closing price of the previous session outside of market hours.
- **historical attributes** _(OPTIONAL – "close" by default)_ Use one of the following attributes when requesting historical candles:
- "open" – The opening price of the stock.
- "high" – The high price of the stock.
- "low" – The low price of the stock.
- "close" – The closing price of the stock.
- "volume" – The number of shares traded.
- "all" – Returns all values.
- "symbol" - The ticker symbol of the stock. _Only returned when using a bulk candles formula._
- "adjusted" - Returns split- and dividend-adjusted prices (CRSP methodology). On daily resolutions both split and dividend adjustments are applied; on intraday resolutions only split adjustment is applied, since dividend adjustment is available for daily resolutions only. Can be used on its own — `=STOCKDATA("AAPL", "adjusted", ...)` returns the full adjusted OHLCV row, just like "all" — or combined with a specific column, e.g. "adjusted,close".
- "unadjusted" - Returns raw prices with no split or dividend adjustment. Can be used on its own — `=STOCKDATA("AAPL", "unadjusted", ...)` returns the full unadjusted OHLCV row, just like "all" — or combined with a specific column, e.g. "unadjusted,close".
- **quote attributes** _(OPTIONAL – "mid" by default)_ Use one of the following attributes when requesting a quote:
- "mid", "mark" – The midpoint price of the stock.
- "bid" – The bid price of the stock.
- "ask" – The ask price of the stock.
- "last" – The last price of the stock.
- "bidSize" – The quantity of shares offered at the bid price.
- "askSize" – The quantity of shares offered at the ask price.
- "volume" – The quantity of shares traded.
- "52weekHigh" – The 52-week high for the stock.
- "52weekLow" – The 52-week low for the stock.
- "52week" – Adds both 52-week columns. "all" does not include them: use "all,52week" to return every value and the 52-week high and low.
- "symbol" - The ticker symbol of the stock. _Only returned when using a bulk quotes formula._
- "all" – Returns all values except the 52-week high and low.
- **start date** _(OPTIONAL)_ The start date when fetching historical data. If start date is specified, but endDate is not, only the single day’s data is returned. Multiple tickers may be used if only a single day's data is being returned.
- **end date** _(OPTIONAL)_ The end date when fetching historical data, or the number of calendar days (not trading days) from startDate for which to return data.
- **resolution** _(OPTIONAL)_ The duration of each candle when fetching historical candles. Daily resolution is default if no value is specified. Use one of the following resolutions:
- Minutely Resolutions: (_minutely_, _1_, _3_, _5_, _15_, _30_, _45_, ...)
- Hourly Resolutions: (_hourly_, _H_, _1H_, _2H_, ...)
- Daily Resolutions: (_daily_, _D_, _1D_, _2D_, ...)
- Weekly Resolutions: (_weekly_, _W_, _1W_, _2W_, ...)
- Monthly Resolutions: (_monthly_, _M_, _1M_, _2M_, ...)
- Yearly Resolutions: (_yearly_, _Y_, _1Y_, _2Y_, ...)
## Price vs Close vs Last vs Mid
When you are looking for a single price for a stock, depending on what data you would like the `STOCKDATA` formula to return during the extended session (or when the market is closed), it may make sense to use the "close", "last", or "mid" attributes instead of STOCKDATA's default "price" attribute.
| Function Call | During The Regular Session | During The Extended Session | Market Closed, Holidays, etc. |
|-------------------------------|-----------------------------------------|------------------------------------------|-----------------------------------------------|
| `=STOCKDATA("AAPL")` | Midpoint bid/ask of the regular session | Midpoint bid/ask of the extended session | Closing price of the previous regular session |
| `=STOCKDATA("AAPL", "PRICE")` | Midpoint bid/ask of the regular session | Midpoint bid/ask of the extended session | Closing price of the previous regular session |
| `=STOCKDATA("AAPL", "CLOSE")` | Last trade of the regular session | Closing price of the previous session | Closing price of the previous regular session |
| `=STOCKDATA("AAPL", "LAST")` | Last trade of the regular session | Last trade of the extended session | Last trade of the previous extended session |
| `=STOCKDATA("AAPL", "MID")` | Midpoint bid/ask of the regular session | Midpoint bid/ask of the extended session | No data |
## Usage Information
### Data Availability
The `STOCKDATA` function can return both quotes and candles, depending on whether date parameters are specified. The data type you receive depends on your user type and exchange entitlements.
> [!NOTE]
> **[What are entitlements?]**
>
> Entitlements are permissions granted by exchanges that allow access to their data. To get quotes, users need to sign the [IEX agreement](https://www.marketdata.app/docs/account/entitlements). To get candles, users need to sign the [UTP agreement](https://www.marketdata.app/docs/account/entitlements). [Learn more about entitlements](https://www.marketdata.app/docs/account/entitlements).
#### Quotes (No Date Parameters)
When you use `STOCKDATA` without date parameters, it returns quote data. The type of quote you receive depends on your user type and IEX entitlement. This may include a real-time quote, a 15-minute delayed quote or historical (1 day old) quote, depending on the plan or access level. Real-time quotes are not currently available.
| User Type | IEX Entitlement | Quote Type |
|------------------|-----------------|------------------------|
| Non-Professional | ✅ | Real-time |
| Non-Professional | ❌ | 15-min delayed |
| Professional | ✅ | Real-time |
| Professional | ❌ | Historical (1 day old) |
| Unknown | ✅ | Real-time |
| Unknown | ❌ | Historical (1 day old) |
#### Current Day Candles
When you use `STOCKDATA` with date parameters to request candles from the current trading session (today), you receive current day candle data. **Real-time candle data is not available for candles under any plan or entitlement.** The type of candle data you receive depends on your user type and UTP entitlement. This may include 15-minute delayed candles or historical candles (1 day old), depending on the plan or access level.
| User Type | UTP Entitlement | Candle Type |
|------------------|-----------------|------------------------|
| Non-Professional | ✅ | 15-min delayed |
| Non-Professional | ❌ | 15-min delayed |
| Professional | ✅ | 15-min delayed |
| Unknown | Any | Historical (1 day old) |
#### Historical Candles
When you use `STOCKDATA` with date parameters to request candles from past dates, you receive historical candle data. Historical candles can use any resolution (intraday, daily, weekly, etc.) from past trading sessions. **Historical data is available to all users regardless of exchange entitlements.** However, the age of historical data you can access depends on your plan:
| Plan | Historical Data Availability |
|-------------------------------|------------------------------|
| Free Forever | 1 year |
| Trial Plans (Starter, Trader) | 1 year |
| Starter | 5 years |
| Trader, Quant, Prime | No limit (full access) |
> [!NOTE]
> **[Plan Limits]**
>
> If you attempt to access historical data older than your plan's limit permits, the formula will return an error. [Learn more about plan limits](https://www.marketdata.app/docs/account/plan-limits).
## Notes
- All parameters must be enclosed in quotation marks or be references to cells containing text. A possible exception is when endDate is specified as a number of days.
- Results with a single data point will be returned as a value within a single cell. Multiple data points will be returned as an expanded array with column headers.
- If any date parameters are specified, the request is considered historical and only the historical attributes are allowed.
- Dates and times are returned in the same timezone of the exchange.
- When writing bulk candles formulas, only a single date is allowed. Date ranges are not permitted. Only daily candles are supported for bulk candles.
---
# Troubleshooting (Sheets)
Source: https://www.marketdata.app/docs/sheets/troubleshooting/index.md
From time to time you may encounter different error messages while using the Google Sheets Add-On. These messages are almost always due to limitations that Google places on Sheets Add-ons, which have certain limitations that most users are not aware of. By learning about the limitations Google has placed on your use of Add-ons, you will be able to avoid these common errors in the future.
## Errors when Opening Your Sheet
Sometimes you may get an error when you open your spreadsheet. These errors are usually related to Add-on authorization issues.
- `#NAME?` - This error in your formulas indicates the Add-on is not loaded properly in the current sheet. Open the sidebar in Extensions > Market Data > Start to load the Add-on in the current sheet. See [Unknown Function Error](https://www.marketdata.app/docs/sheets/troubleshooting/unknown-function).
- `Error: Unable to start a Market Data session with sidebar closed.` - This error occurs when you first open your sheet for the day. Open the sidebar in Extensions > Market Data > Start. Refresh your data using one of the refresh options provided.
- `ScriptError: Authorization is required to perform that action.` - The Market Data Add-on is not installed correctly in this spreadsheet or in your Google account. This typically occurs when customers are logged into multiple Google accounts at the same time. See [Permissions Not Granted During Installation](https://www.marketdata.app/docs/sheets/troubleshooting/permissions-not-granted).
## Errors in Market Data Sidebar
The Market Data sidebar can detect service outages and other problems with your Google account. If you begin to have trouble with Market Data, open the sidebar and see if an error message is displayed.
- `Multiple Google accounts error.` - Your browser has multiple Google accounts open at once. Google does not permit multi-login with Sheets Add-ons, such as Market Data. You will need to log out of your other Google accounts or use Google Sheets with a single Google account in a private browsing window. See [Multiple Google Accounts Error](https://www.marketdata.app/docs/sheets/troubleshooting/multiple-google-accounts).
- `Authentication error.` - The add-on could not authenticate your Google account. Make sure the Google account you use to login to Sheets matches the e-mail address on your Market Data account. See [Authentication](https://www.marketdata.app/docs/sheets/authentication).
- `Market Data is offline.` - Your sheet is cannot reach Market Data's servers. Check our status page to see if there is a service outage. As soon as service is restored this error will resolve.
## Errors in Formulas
Formulas will give errors in their output due to three reasons:
1. Incorrect user input
2. Problems or issues with Market Data or your Market Data account
3. Limits or throttling placed by Google on your Google account.
You can see the complete list of error messages for each category below:
### Incorrect User Input
The following errors are usually easily correceted by modifying the input to your formula.
- `No data.` - This actually isn't an error, but it is one of the most common messages. It means Market Data does not have any data for the symbol you input. Try a different symbol or a different timeframe.
- `Invalid symbol.` - The symbol you specified is not included our database of valid symbols and we cannot provide you with any data for this symbol. Check to make sure the symbol is valid.
- `Invalid option symbol.` - Use valid OCC symbology for the option symbol. The option symbol you used is not valid. Learn how to form a correct OCC option symbol and try again.
- `Non-string symbol.` - The 'Symbol' parameter must be text surrounded by quotes or a cell reference that contains text. You most likely forgot to add quotes around the symbol you are using or you used an incorrect cell reference. Double check the formula to make sure it is formatted correctly.
- `Invalid attribute.` - You are requesting an attribute that is not valid for the data you are requesting. Usually this happens when requesting a real-time quote attribute for historic data or vice versa.
- `Invalid resolution.` - We cannot generate timeseries data for the resolution you are requsting. Read the documentation to see what resolutions are supported.
### Market Data Account Issues
These issues are related to problems with your specific Market Data account and are usually easily solvable.
- `Authentication error.` - The add-on could not authenticate your Google account with Market Data. Make sure the e-mail address on your Market Data account matches the Google account you use to login to Sheets. See [Authentication](https://www.marketdata.app/docs/sheets/authentication).
- `Unable to start a Market Data session with sidebar closed.` - This error occurs when you first open your sheet for the day. Open the sidebar in Extensions > Market Data > Start and refresh your data using one of the refresh options provided.
- `Your Market Data plan has exceeded its daily limit.` - You have used all your Market Data requests for the day. Your account will be refilled with new requests at opening bell (9:30 AM Eastern Time) tomorrow.
### Market Data Service Issues
These issues relate to general Market Data technical or service issues. The only solution is to check back later or submit a support ticket if the problem does not resolve itself after a few minutes.
- `Internal server error, please try again later.` - This is a usually temporary failure of Market Data's server. If the error continues for more than 24 hours, open a ticket with the helpdesk.
- `API Endpoint Offline.` - The Market Data API endpoint that should be responding to your formula's request is offline. If this problem continues for more than 15 minutes, report it to the helpdesk.
- `API Gateway Offline.` - The gateway server is not responding or unavailable. If this problem continues for more than 15 minutes, report it to the helpdesk.
- `Market Data is offline.` - Market Data servers are offline. The Add-on will not function until our servers are back online. [Check our status page](https://www.marketdata.app/status/) to see details about the service outage.
- `Exceeded maximum execution time (line 0)` - It took more than 30 seconds for Market Data's servers to respond to your request. You can retry using the Refresh Errors option in the sidebar and most times this will work. If the problem is frequent, please submit a ticket to our helpdesk with your formula so we can evaluate why it is taking too long to complete the request.
### Google Account Issues
These issues relate to problems with your Google account. Google places strict limits on the use of Add-ons for free (@gmail.com accounts). If you exceed those limits, an error message will be shown and your account will be throttled.
- `Your Google account has exceeded the minute request limit.` - Your account was throttled by Google for making too many requests. Try refreshing your cells using Market Data's refresh options, which are calibrated to avoid throttling issues. See [Excessive Refreshing](https://www.marketdata.app/docs/sheets/troubleshooting/excessive-refreshing).
- [`Your Google account has exceeded the urlfetch limit.`](https://www.marketdata.app/docs/sheets/troubleshooting/urlfetch) - You have exceeded Google's urlfetch limit. For 24 hours your account will be blocked from using all Google Workspace Add-ons, including Market Data. Please try again 24 hours from now.
---
# Excessive Refreshing
Source: https://www.marketdata.app/docs/sheets/troubleshooting/excessive-refreshing/index.md
Due to Google's strict quota on urlfetch requests, unwanted refreshing of cells can become troublesome. Google will refresh your spreadsheet if any of the following take place:
- Reopening a spreadsheet
- Adding/deleting a row
- Adding/deleting a column
- Sorting a row/column
## Background Formula Refreshing
Google Sheets automatically refreshes all formulas in the background once per hour, even when the spreadsheet is not actively being edited. This background refresh can trigger urlfetch requests for any formulas that use our functions, potentially causing you to hit the quota limit unexpectedly.
**Strategy to Avoid Background Refreshing**: Close the spreadsheet tab when you're not actively working on it. This prevents Google from performing the hourly background refresh of all formulas, which can help you stay within the urlfetch quota limits.
## Add-ons, Scripts & Macros
If you have other add-ons, scripts, or macros that perform any cell or row actions such as those listed above, your sheet may recaculate excessively, causing you to hit the urlfetch quota very quickly. We recommend disabling them.
---
# Extensions Menu Disabled in Google Sheets
Source: https://www.marketdata.app/docs/sheets/troubleshooting/extension-disabled/index.md
If the **Extensions** menu in Google Sheets appears grayed out (lighter text, unclickable) when trying to use the Market Data add-on, it is almost always due to a Google Sheets behavior when viewing a fully protected sheet — it is **not** caused by the Market Data add-on itself.
**What to look for:** The Extensions menu will be visible but appear lighter in color and won't respond when clicked.
## Why This Happens
- If **every cell** in the current sheet is protected for your account, Google Sheets automatically disables certain menus — including **Extensions** and **Format**.
- This behavior is built into Google Sheets and applies to all add-ons, not just Market Data.
- If the spreadsheet you're using was provided by another person or company and contains fully locked or protected, you may encounter this when viewing those sheets.
## Quick Diagnostic
To confirm this is the issue:
1. Look at the bottom-left corner of Google Sheets
2. If you see "Protected sheet" or similar text, this confirms the sheet is fully protected
3. Try clicking in any cell - if you can't edit any cells, the sheet is fully protected
## How to Fix It
### 1. Switch to a Tab With Editable Cells
1. Click on a sheet tab where you can edit at least one cell.
2. Once you are in an editable sheet, the **Extensions** menu will become active again.
### 2. Ask the Sheet Owner to Add an Editable Cell
If you need to run Market Data from a protected tab:
1. Ask the sheet owner to make a cell on that sheet editable for you.
2. This keeps the menu available without removing important protections.
### 3. Work From Your Own Copy
If you have permission:
1. Go to **File > Make a copy**.
2. Save it to your own Google Drive where you are the owner.
3. You will have full access to all menus (but this removes the original owner’s protections).
## Important Notes
- This issue occurs because of the spreadsheet’s protection settings — not because of the add-on’s installation or your subscription.
- Once you are in a sheet with at least one editable cell, the add-on will be accessible again.
## Still Having Trouble?
If the Extensions menu stays disabled even when on an editable tab:
### Step 1: Refresh and Check
1. Refresh the sheet (**Ctrl+R** or **Cmd+R**)
2. Try switching to a different tab and back
3. Check that you can edit at least one cell on the current tab
### Step 2: Verify Add-on Installation
1. Go to **Extensions > Add-ons > Manage add-ons**
2. Look for "Market Data" in the list
3. Make sure it shows as "Enabled" (not "Disabled" or missing)
### Step 3: Check Permissions
1. Click **Share** in the top-right corner
2. Verify your email has "Editor" access (not just "Viewer")
3. If you only have "Viewer" access, ask the owner to change it to "Editor"
### Step 4: Contact Support
If the problem persists, contact our support team and include:
- The name of the spreadsheet
- Which tab you were on when the menu was disabled
- A screenshot showing the menu state
- Your permission level (Viewer/Editor/Owner)
We typically respond within a few hours during market hours.
---
# Mobile Devices
Source: https://www.marketdata.app/docs/sheets/troubleshooting/mobile-devices/index.md
Google Workspace Add-ons are not supported on mobile devices yet. This means there is no way to launch the Market Data sidebar on your mobile device. However, if you would like to use our service on your mobile device there are several workarounds you can try. Our custom formulas like [STOCKDATA](https://www.marketdata.app/docs/sheets/stocks/stockdata) and [OPTIONDATA](https://www.marketdata.app/docs/sheets/options/optiondata) will work on your mobile device.
> [!CAUTION]
> The following recommendations are only for users who want to experiment with Market Data on their mobile device. We do not officially support mobile devices with our add-on.
## Enable Your Sheet For Mobile
To use Market Data on a mobile device, you need to disable the sidebar check. The add-on authenticates automatically using your Google account, but since there is no way to open the sidebar on a mobile device, you must disable the sidebar requirement first from a computer.
### Disable the Sidebar Check
The system currently validates that the sidebar has been opened before allowing you to execute Market Data formulas. Disable this in your sheet by using the following command (type it into any cell):
=DEBUG("disable_sidebar_check")
Please be aware that command will stop the sidebar check when running your custom formulas. If you leave your spreadsheet open for an extended period of time formulas will continue to execute and you may run into [urlfetch errors](https://www.marketdata.app/docs/sheets/troubleshooting/urlfetch). If you find yourself running into urlfetch errors, enable the sidebar check again using the following command (type it into any cell):
=DEBUG("enable_sidebar_check")
## Using Market Data in Mobile
You can continue to use all the Market Data formulas in mobile as you would on a computer. However, to refresh your sheet, since you cannot use the refresh button, there is a workaround:
> [!TIP]
> Insert a row above row 1 to refresh all cells in your sheet. After adding the new row, delete it again. This quick sequence of adding and deleting a new row 1 on your sheet will cause all cells in your active sheet to refresh.
---
# Multiple Google Accounts Error
Source: https://www.marketdata.app/docs/sheets/troubleshooting/multiple-google-accounts/index.md
Google does not support multi-login with Google Workspace Add-ons. Google's official statement on the issue:
> [Multi-login, or being logged into multiple Google Accounts at once, isn't supported for Apps Script, add-ons, or web apps.](https://developers.google.com/apps-script/guides/projects#fix_issues_with_multiple_google_accounts)
For users who work with multiple Google accounts during the day, such as a work and home account at the same time, this can be a serious problem, since it will cause errors with Add-ons such as Market Data, which need to access your Google account to function properly.
## Error Messages
This error may present itself when you first open the sheet or during your use of the sheet, depending on whether Market Data has been installed in the secondary Google account. The error messages you may see are as follows:
- `ScriptError: Authorization is required to perform that action.`
- `Multiple Google accounts error.`
## Workarounds
Fortunately this is an easy error to fix. There are two confirmed workarounds:
1. Log out of all your Google accounts then log-in to the account that uses Market Data and use it while being signed-in to a single account.
2. Open a private browsing window (Icognito mode) and open the Google account you use with Market Data in the private window.
### Unconfirmed Workaround
There is also an unconfirmed workaround that some users have reported success with and that will allow you to remain logged-in to multiple Google accounts at once:
- Set the Google account you use with the Market Data Add-On as your Default Google account.
- The default Google account is simply the account you sign-in first to Google with. You can check this by clicking the profile icon in the upper right corner.
- If another account is showing up as the Default account, then you are not using Market Data with your default Google account.
To fix this, use the following steps (not guaranteed to work, but reported successful by multiple users):
1. Sign out of all your Google accounts.
2. Sign-in to the Google account you use with Market Data. This is now your default Google account.
3. Sign-in to the rest of your Google accounts.
4. Switch back to the default account.
5. Open Google Sheets and try using Market Data.
6. If Market Data works without errors for you, you can continue to use all your Google accounts with multiple sign-in, just make sure to always sign-in first to the account that uses Market Data.
---
# Permissions Not Granted During Installation
Source: https://www.marketdata.app/docs/sheets/troubleshooting/permissions-not-granted/index.md
## Problem Overview
If the Market Data Google Sheets add-on is installed but **functions do not work**, **menus do nothing**, or spreadsheet formulas fail to initialize, the most common cause is **missing permissions during the original installation**.
Due to a recent change by Google, users can now **enable or disable individual permissions during installation**.
The Market Data add-on **requires all requested permissions** to function correctly.
If any permission was left unchecked during install, the add-on cannot run.
## Why This Happens
Google recently introduced **granular OAuth consent** for Google Sheets add-ons.
This means:
- The add-on can be installed **without granting all permissions**
- Google may **not re-prompt** for missing permissions afterward
- The add-on cannot execute without full consent
- There is currently **no way for the add-on to force the consent screen to reappear**
This behavior is enforced by Google and is not controlled by Market Data.
## Required Fix: Uninstall and Reinstall the Add-on
At this time, the **only reliable solution** is to remove the add-on completely and reinstall it while granting all permissions.
### Step-by-Step Instructions
1. Open Google Sheets
2. Go to **Extensions → Add-ons → Manage add-ons**
3. Locate **Market Data**
4. Click **Uninstall**
5. Close the spreadsheet
6. Reopen Google Sheets
7. Reinstall the Market Data add-on from Google Workspace Marketplace
8. During installation, when the Google permission screen appears:
- Choose "Select all"
- **Ensure all permission toggles are enabled**
- Click **Continue**
## Important Notes
- Simply reloading the spreadsheet is **not sufficient**
- Re-enabling the add-on for a document will **not restore missing permissions**
- The add-on cannot request additional permissions after installation if they were denied
Until Google provides a way to re-trigger consent reliably, **reinstallation is required**.
## Google Workspace (Company Accounts)
If you are using a Google Workspace account:
- Your organization may restrict third-party add-ons
- Some permissions may be blocked by policy
If permissions cannot be enabled:
1. Contact your IT administrator
2. Ask them to allow the Market Data add-on
3. Confirm all requested permissions are permitted for your account
## Key Takeaway
- The add-on must be installed with **all permissions enabled**
- Partial permission installs will not work
- Reinstallation is currently the only fix
- This behavior is controlled by Google
## Still Need Help?
If you have reinstalled the add-on and enabled all permissions but still experience issues, please contact support and include:
- Confirmation that you reinstalled the add-on
- A screenshot of the permission screen
- Whether you are using a personal Google account or Google Workspace
We typically respond within a few hours during market hours.
---
# Price Differences
Source: https://www.marketdata.app/docs/sheets/troubleshooting/price-differences/index.md
You may notice that from time to time prices differ when using Market Data compared to Google Finance, TradingView, Yahoo Finance, or other financial websites, especially after hours. This is normal and it to be expected since those platforms display real-time prices using trades (i.e. the last trade or closing price), while Market Data displays real-time prices using quotes.
## Trades vs Quotes
A trade is a transaction that took place between a buyer and a seller in the past. A quote is a bid/ask price from the top of the order book and represents the price a buyer or seller would pay right now if a new transaction were to take place. Trades are indiciatve of the current stock price, but they are a lagging indicator. A quote represents the most current price.
## STOCKDATA vs GOOGLEFINANCE After Hours
When you run `STOCKDATA` after hours you will be shown the midpoint price between the bid and the ask. `GOOGLEFINANCE` after hours will always provide you with the last trade (i.e. the closing price). During the extended session (after hours) trading, the bid and the ask can be much further apart than during the market hours. This means the midpoint price between the bid and the ask could be much further away from the last price than usual.
To get more detailed information, use the "all" parameter with STOCKDATA like this: `=STOCKDATA("TICKER","ALL")`. This will provide you with a more detailed quote with column names and help you understand where the price is coming from.
### Example From 3 AM
In the example shown, we've requested a price using both STOCKDATA and GOOGLEFINANCE at 3 AM in the early morning for a stock that was thinly traded in the extended session. Note how STOCKDATA shows a price of $128.64 (midpoint between the bid/ask) while GOOGLEFINANCE shows $129.42, the day's closing price. When STOCKDATA is run with the "ALL" parameter we can see the bid/ask and verify how the midpoint price is calculated.
## Force STOCKDATA to Use Trades
If you prefer to see trades instead of quotes for real-time prices, you can modify the STOCKDATA formula slightly and the price shown will be the last trade instead of the most up to date quote. Instead of using `=STOCKDATA("TICKER")`, use instead `=STOCKDATA("TICKER","LAST")`. This will force the formula to use the last price instead of the midpoint price when outputting the result to a single cell.
Please be aware that by using this method, the price shown will be a historical price instead of a price that is likely to result in an order fill. If you are using the formula for trading, the midpoint price is recommended.
---
# Unknown Function Error
Source: https://www.marketdata.app/docs/sheets/troubleshooting/unknown-function/index.md
When you encounter a #NAME error in your spreadsheet while using the Market Data Google Sheets add-on, it typically indicates that the add-on hasn't been properly initialized or connected to your open spreadsheet. This prevents you from using any of the market data functions like =STOCKDATA(), =OPTIONDATA(), etc.
If you've already activated the add-on in your Google account but still see this error, here are several solutions to resolve the issue:
## Multiple Google Account Sessions
If you're using multiple Google accounts in the same browser, this can sometimes cause authentication issues with Google Sheets add-ons. This is a common scenario when switching between personal and work accounts.
To resolve this:
1. Create separate Chrome profiles for different Google accounts
- This keeps your work and personal accounts completely separated
- Ensures proper add-on authentication for each account
- Log-in to a single Google account per Chrome session
2. Alternative solution: Use an incognito window
- Open Chrome Menu > File > New Incognito Window
- Sign in to your Google account
- Access your spreadsheet with the Market Data add-on
## Re-enable the Add-on
If the above solution doesn't work, try re-enabling the add-on specifically for your current spreadsheet:
1. Go to Extensions > Add-ons > Manage add-ons
2. Find the Market Data add-on
3. Unroll the options and uncheck "Use in this document"
4. Reload your spreadsheet
5. Return to the add-ons manager
6. Check "Use in this document" again
## Perform a Clean Installation
If you're still experiencing issues, try a complete reinstallation:
1. Visit https://myaccount.google.com/permissions
2. Remove the Market Data add-on from your permissions list
3. Go to Google Workspace Marketplace
4. Uninstall the Market Data add-on
5. Reinstall the add-on
6. Reload your spreadsheet
## Google Workspace Users
If you're using Google Workspace (formerly G Suite) through your organization, there might be additional considerations:
1. Check Workspace Settings
- Contact your IT administrator to verify that third-party add-ons are allowed
- Ensure the Market Data add-on is on your organization's allowed apps list
- Confirm you have the necessary permissions to install and use add-ons
2. Domain-wide Installation
- If your organization uses domain-wide installation, the add-on should be installed by your IT administrator
- Wait for the add-on to propagate across your organization (can take up to 24 hours)
- Ensure your account is part of the organizational unit where the add-on is deployed
## Additional Troubleshooting Steps
If none of the above solutions work, try these general fixes:
1. Clear your browser cache and cookies
2. Verify your subscription status is active
3. Try accessing the spreadsheet from a different browser
4. Check if the issue persists in a new spreadsheet
## Still Need Help?
If you've tried all the above steps and still encounter issues:
1. Contact our support team via the helpdesk
2. Include the following information:
- Screenshot of the error
- Steps you've already tried
- Whether you're using personal Google account or Google Workspace
Our support team typically responds within a few hours during market hours.
---
# Urlfetch Errors
Source: https://www.marketdata.app/docs/sheets/troubleshooting/urlfetch/index.md
Urlfetch is the service that Google Add-Ons use to fetch data from an external service (such as Market Data). The limit is set by Google on a per account basis. Consumer accounts (gmail) have a limit of 20,000 urlfetch calls per day, while business accounts (Google Workspace) can make up to 100,000 urlfetch calls daily.
Each time Market Data recalculates the data in a cell, that will consume one call from your urlfetch limit. **Google will recalculate your spreadsheet about once per hour**, so if you use 1000 Market Data formulas in your sheet and leave your spreadsheet open for 8 hours that will consume about 8000 urlfetch calls.
> [!CAUTION]
> Urlfetch calls are different from Market Data requests. Even if you have our Trader plan and can make 100,000 requests per day, if you use a consumer (gmail.com) account, you'll only be able to make 20,000 urlfetch calls with your spreadsheet. Your urlfetch limit is set by Google and cannot be modified by Market Data.
| Feature | Consumer Accounts (Gmail) | Google Workspace Accounts |
|--------------------------|-----------------------------------------------------------|---------------------------------------------|
| **Daily Urlfetch Limit** | 20,000 urlfetch calls | 100,000 urlfetch calls |
| **Typical Use Case** | Personal use, small projects | Business use, large projects |
| **Recalculation Impact** | Higher risk of hitting limit with frequent recalculations | Lower risk due to higher limit |
| **Market Data Requests** | Limited by lower urlfetch quota | More flexibility with higher quota |
| **Account Blocking** | 24-hour block after exceeding limit | 24-hour block after exceeding limit |
| **Strategies Needed** | More aggressive strategies to reduce usage | Fewer strategies needed due to higher limit |
## Error Messages You May See In The Add-on Due to Urlfetch Issues
Although there is no way to determine how many urlfetch calls can be made by your account, Market Data can detect when the limit has been exceeded and will display an error message. Each of the following error messages indicate that your Google account has exceeded the urlfetch limit:
- `Your Google account has exceeded the urlfetch limit.`
- `The Add-On cannot communicate with Market Data's servers due to your Google account exceeding the daily urlfetch limit.`
- `ScriptError: Exception: Service invoked too many times for one day: urlfetch.`
- `Urlfetch error.`
## Consequences Of Surpassing the Urlfetch Limit
Google will block your account from making new urlfetch requests for 24 hours when you surpass the limit. When you see the urlfetch error message, you must wait a full 24 hours before making another request with the affected Google account.
## Strategies To Reduce Urlfetch Usage
There are a number of strategies you can use to reduce your use of urlfetch calls.
### Copy & Paste Values For Historical Data
When you query Market Data for historical data, such as the price of a stock in the past, consider copying and using the _paste values_ option once the formula finishes its output. This deletes the Market Data formula, but it will preserve the formula's output.
There are a number of advantages to removing historical formulas and replacing them with the output:
- It will prevent future repeat queries for the same historical data, preserving your urlfetch quota.
- It will also prevent future Market Data requests, preserving your Market Data request quota.
- Your spreadsheet will load more quickly on initial open.
- Your spreadsheet will recalculate more quickly every hour.
If you make a habit of using Copy & Paste Values for your historical outputs, your overall Market Data experience will be significantly improved.
### Use A Single Formula For All Your Real-Time Quotes
Instead of using multiple [`STOCKDATA`](https://www.marketdata.app/docs/sheets/stocks/stockdata) formulas in your spreadsheet, use a single formula and send all the tickers you need at once. Not only will this use just one urlfetch call, but it will also speed up the loading process of your spreadsheet.
### Refresh Prices Less Often
If you are typically updating your prices every 10 minutes, for example, consider updating every 20 or 30 minutes. You can also make use of the "Current Sheet" refresh to only refresh prices on the current sheet instead of the entire workbook.
### Check For Troublesome Add-ons, Scripts & Macros
Your urlfetch quota is shared between all your Google Workspace Add-ons. If you are using other add-ons that are also making urlfetch calls, you may burn through your quota very quickly. Some add-ons may also cause your spreadsheet to recalculate cells much more frequently than Google's default of once per hour. If you have 1000 Market Data formulas and another add-on is recalculating your sheet once every 3 minutes, you'll hit the urlfetch limit in an hour.
#### How To Investigate Your Google Account's Add-ons, Scripts & Macros
Use the following links to investigate what other scripts and Add-ons may be running in your Google account:
- [Workspace Add-ons installed in your account](https://workspace.google.com/marketplace/myapps)
- [Scripts authorized to run in your account](https://script.google.com/home/all)
- [Log of scripts which are executing](https://script.google.com/home/executions)
#### Uninstall Unused Add-ons
Unless you are 100% sure that your other add-ons don't cause excessive recalculation of your spreadsheet and don't make excessive urlfetch calls, consider uninstalling add-ons that are no longer in use.
## Strategies to Increase Your Urlfetch Limit
### Switch From Gmail To Google Workspace
If you are currently using a standard Gmail account and find yourself frequently hitting the urlfetch limit, consider switching to a Google Workspace account. Google Workspace accounts often come with higher quotas for various services, including urlfetch. This upgrade can provide you with the additional capacity you need to continue using Market Data without interruptions.
---
# Universal Attributes
Source: https://www.marketdata.app/docs/sheets/universal-attributes/index.md
Universal attributes are special modifiers that are common to all Market Data formulas. You may use them in the attributes argument in any of our formulas and they will modify the output of the formula.
---
# No Headers
Source: https://www.marketdata.app/docs/sheets/universal-attributes/no-headers/index.md
Add the "noheaders" attribute to exclude the header row from the output of any Market Data formula.
## Sample Usage
```excel-formula
=STOCKDATA("AAPL", "all,noheaders")
=STOCKDATA(A1:A50, "mid,noheaders")
=OPTIONDATA(A1:A50, "bid,ask,noheaders")
=OPTIONDATA("AAPL271217C00250000", "bid,ask,noheaders", "1/5/2026", "2/5/2026")
```
## Syntax
```excel-formula
=FORMULA("symbol", "attribute1, attribute2, noheaders")
```
Add `noheaders` anywhere in the attribute list of any Market Data formula. Ensure that all attributes are seperated by commas.
## Notes
> [!NOTE]
>
> The `noheaders` attribute is needed whenever the output has more than one row or column: several attributes, several symbols or contracts, or a date range. A single attribute for a single symbol and date returns one cell with no header.
---
# Market Data
Source: https://www.marketdata.app/docs/index.md
Complete Documentation For All Market Data Products & Services
[Get Started With Our API](https://www.marketdata.app/docs/api/)
(image: Market Data API)
### [Market Data API](https://www.marketdata.app/docs/api/)
A complete reference of all Market Data API endpoints, authentication, and universal parameters.
(image: Google Sheets Add-On)
### [Google Sheets Add-On](https://www.marketdata.app/docs/sheets/)
Learn how to use each Market Data formula in our Add-On with practical examples.
(image: Accounts & Billing)
### [Accounts & Billing](https://www.marketdata.app/docs/account/)
Frequently asked questions about your account, our billing rules, and administrative information.