Market Data Python SDK

https://www.marketdata.app/docs/sdk/py
Admin
The Market Data Python SDK allows developers to easily integrate Market Data services into their...
Tokens:40,898
Snippets:145
Trust Score:8.2
Update:7 months ago
Show doc for...
Tokens:
Raw
================
LIBRARY RULES
================
- Always refer to this library as "Market Data Python SDK".
- If a user asks about an endpoint not covered in the Python SDK, suggest they check the REST API docs at https://www.marketdata.app/docs/api
- Use the exact method names, parameter names, and return types from the SDK documentation.
- When discussing authentication, always reference the MarketDataClient class.
- This library only covers the Python SDK. For other programming languages, direct users to the REST API docs at https://www.marketdata.app/docs/api or the SDK overview at https://www.marketdata.app/docs/sdk for other official Market Data SDKs.

================
CODE SNIPPETS
================
### Local Development Installation

Source: https://www.marketdata.app/docs/sdk/py/installation

Installs the Market Data Python SDK from a local project directory. This is useful for development and testing.

```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]"
```

--------------------------------

### Install Market Data Python SDK (pip)

Source: https://www.marketdata.app/docs/sdk/py/installation

Installs the Market Data Python SDK using pip. This is the basic installation command.

```bash
pip install marketdata-sdk-py
```

--------------------------------

### Install Market Data Python SDK (uv)

Source: https://www.marketdata.app/docs/sdk/py/installation

Installs the Market Data Python SDK using uv. This is an alternative to pip for faster dependency management.

```bash
uv pip install marketdata-sdk-py
```

--------------------------------

### Install SDK with Polars DataFrame Support (uv)

Source: https://www.marketdata.app/docs/sdk/py/installation

Installs the Market Data Python SDK with polars DataFrame support using uv. This enables the use of polars DataFrames for output.

```bash
uv pip install "marketdata-sdk-py[polars]"
```

--------------------------------

### Install SDK with Pandas DataFrame Support (uv)

Source: https://www.marketdata.app/docs/sdk/py/installation

Installs the Market Data Python SDK with pandas DataFrame support using uv. This enables the use of pandas DataFrames for output.

```bash
uv pip install "marketdata-sdk-py[pandas]"
```

--------------------------------

### Install SDK with Polars DataFrame Support (pip)

Source: https://www.marketdata.app/docs/sdk/py/installation

Installs the Market Data Python SDK with polars DataFrame support using pip. This enables the use of polars DataFrames for output.

```bash
pip install "marketdata-sdk-py[polars]"
```

--------------------------------

### Install SDK with Pandas DataFrame Support (pip)

Source: https://www.marketdata.app/docs/sdk/py/installation

Installs the Market Data Python SDK with pandas DataFrame support using pip. This enables the use of pandas DataFrames for output.

```bash
pip install "marketdata-sdk-py[pandas]"
```

--------------------------------

### Install SDK with Both Pandas and Polars Support (uv)

Source: https://www.marketdata.app/docs/sdk/py/installation

Installs the Market Data Python SDK with support for both pandas and polars DataFrames using uv. This allows the SDK to use either library for DataFrame output.

```bash
uv pip install "marketdata-sdk-py[pandas,polars]"
```

--------------------------------

### Install SDK with Both Pandas and Polars Support (pip)

Source: https://www.marketdata.app/docs/sdk/py/installation

Installs the Market Data Python SDK with support for both pandas and polars DataFrames using pip. This allows the SDK to use either library for DataFrame output.

```bash
pip install "marketdata-sdk-py[pandas,polars]"
```

--------------------------------

### Initialize MarketDataClient with Direct Token Assignment

Source: https://www.marketdata.app/docs/sdk/py/authentication

This Python example shows how to initialize the MarketDataClient by passing the authentication token directly as a parameter. It then makes a test request for 'SPY' quotes. This method is not recommended for production environments.

```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)
```

--------------------------------

### Handle No DataFrame Handler Found Error

Source: https://www.marketdata.app/docs/sdk/py/installation

Illustrates the ValueError raised when attempting to use DataFrame output format without installing pandas or polars.

```text
ValueError: No dataframe output handler found
```

--------------------------------

### Load Environment Variables from .env File with python-dotenv

Source: https://www.marketdata.app/docs/sdk/py/authentication

This snippet demonstrates how to use a .env file to store the MARKETDATA_TOKEN. The MarketData SDK automatically loads this file if the 'python-dotenv' library is installed, simplifying token management.

```python
MARKETDATA_TOKEN=your_api_token  
```

--------------------------------

### GET /markets/status

Source: https://www.marketdata.app/docs/sdk/py/markets/status

Fetches market status information for specified dates and countries. All parameters must be keyword-only.

```APIDOC
## GET /markets/status

### Description
Retrieves market status information (open/closed) for specified dates and countries.

### Method
GET

### Endpoint
/markets/status

### Parameters
#### Query 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, optional) - The format of the returned data. Defaults to `OutputFormat.DATAFRAME`.
- **date_format** (DateFormat, optional) - The date format to use in the response. Defaults to `DateFormat.UNIX`.
- **columns** (list[str], optional) - Specify which columns to include in the response.
- **add_headers** (bool, optional) - Whether to include headers in the response.
- **use_human_readable** (bool, optional) - Whether to use human-readable format for values. Only applies when `output_format=OutputFormat.INTERNAL`.
- **mode** (Mode, optional) - The data mode to use.
- **filename** (str | Path, optional) - File path for CSV output (only used with `output_format=OutputFormat.CSV`).

### Request Example
```python
from marketdata import MarketDataClient

client = MarketDataClient()

# Get market status as DataFrame (default)
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)
```

### Response
#### Success Response (200)
- **market_status** (list[MarketStatus] | list[MarketStatusHumanReadable] | dict | str) - The market status data in the requested format.

#### Response Example (DataFrame)
```
       date  status
0  2023-10-26    Open
1  2023-10-27    Open
```

#### Response Example (Internal)
```python
[
    MarketStatus(date='2023-10-26', status='Open'),
    MarketStatus(date='2023-10-27', status='Open')
]
```

#### Response Example (JSON)
```json
{
    "market_status": [
        {
            "date": "2023-10-26",
            "status": "Open"
        },
        {
            "date": "2023-10-27",
            "status": "Open"
        }
    ]
}
```

#### Response Example (CSV)
```
date,status
2023-10-26,Open
2023-10-27,Open
```

#### Notes
- All parameters must be keyword-only.
- When using `countback`, it counts backwards from `to_date` or the current date if `to_date` is not provided.
```

--------------------------------

### Configure Output Format for Market Data SDK (Python)

Source: https://www.marketdata.app/docs/sdk/py/settings

Provides examples of configuring the output format for API responses using the Market Data Python SDK. This can be done via environment variables, client default parameters, or direct method parameters.

```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
```

--------------------------------

### GET /options/strikes

Source: https://www.marketdata.app/docs/sdk/py/options/strikes

Fetches a list of available strike prices for a given underlying symbol. Supports multiple output formats including DataFrame, internal objects, JSON, and CSV.

```APIDOC
## GET /options/strikes

### Description
Fetches available strike prices 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.

### Method
GET

### Endpoint
/options/strikes

### Parameters
#### Query Parameters
- **symbol** (str) - Required - The underlying stock symbol for which to fetch strike prices.
- **expiration** (str | datetime.datetime) - Optional - Filter by expiration date.
- **date** (str | datetime.datetime) - Optional - Historical date for the strike prices.
- **output_format** (OutputFormat) - Optional - The format of the returned data. Defaults to `OutputFormat.DATAFRAME`. Possible values: DATAFRAME, INTERNAL, JSON, CSV.
- **date_format** (DateFormat) - Optional - The date format to use in the response. Defaults to `DateFormat.UNIX`.
- **columns** (list[str]) - Optional - Specify which columns to include in the response.
- **add_headers** (bool) - Optional - Whether to include headers in the response.
- **use_human_readable** (bool) - Optional - Whether to use human-readable format for values. Only applies when `output_format=OutputFormat.INTERNAL`.
- **mode** (Mode) - Optional - The data mode to use.
- **filename** (str | Path) - Optional - File path for CSV output (only used with `output_format=OutputFormat.CSV`).

### Request Example
```python
from marketdata import MarketDataClient, OutputFormat

client = MarketDataClient()

# Get options strikes as DataFrame (default)
df = client.options.strikes("AAPL")

print(df)
```

### Response
#### Success Response (200)
- **strikes** (OptionsStrikes | OptionsStrikesHumanReadable | dict | str) - The strike prices in the requested format.

#### Response Example (DataFrame)
```json
{
  "AAPL": {
    "2023-12-15": [
      400.0,
      405.0,
      410.0
    ],
    "2024-01-19": [
      405.0,
      410.0,
      415.0
    ]
  }
}
```

#### Response Example (JSON)
```json
{
  "symbol": "AAPL",
  "strikes": {
    "2023-12-15": [
      400.0,
      405.0,
      410.0
    ],
    "2024-01-19": [
      405.0,
      410.0,
      415.0
    ]
  },
  "expiration_dates": [
    "2023-12-15",
    "2024-01-19"
  ]
}
```

#### Response Example (CSV)
```csv
symbol,expiration_date,strike_price
AAPL,2023-12-15,400.0
AAPL,2023-12-15,405.0
AAPL,2023-12-15,410.0
AAPL,2024-01-19,405.0
AAPL,2024-01-19,410.0
AAPL,2024-01-19,415.0
```

#### Error Response (4xx/5xx)
- **error** (MarketDataClientErrorResult) - Details about the error that occurred.
```

--------------------------------

### Get Options Chain as JSON (Python)

Source: https://www.marketdata.app/docs/sdk/py/options/chain

Fetches an options chain for a specified symbol and date, returning the data in JSON format. This is useful for integrating with other systems or for easy parsing. Requires the MarketDataClient and OutputFormat. The output is a dictionary containing various option details.

```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)
```

--------------------------------

### Get Stock Quotes as CSV using MarketDataClient

Source: https://www.marketdata.app/docs/sdk/py/stocks/quotes

Fetches stock quotes for specified symbols and saves them to a CSV file. Requires the marketdata library and pathlib. Outputs the path to the saved CSV file.

```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}")
```

--------------------------------

### Get Fund Candles as CSV (Python)

Source: https://www.marketdata.app/docs/sdk/py/funds/candles

Retrieves fund candle data for a specified symbol and date range, saving it directly to a CSV file. Requires the marketdata library and Path for file handling. Outputs a file path string.

```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}")
```

--------------------------------

### Get Options Chain with Human-Readable Format (Python)

Source: https://www.marketdata.app/docs/sdk/py/options/chain

Fetches an options chain and formats the output for better human readability. This version modifies field names (e.g., 'Symbol' instead of 'optionSymbol') and date formats. It uses the `use_human_readable=True` flag. Dependencies include MarketDataClient.

```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]}")
```

--------------------------------

### Get Options Chain as CSV (Python)

Source: https://www.marketdata.app/docs/sdk/py/options/chain

Retrieves an options chain and saves it directly to a CSV file. This method is convenient for exporting data for analysis in spreadsheet software. It requires specifying a filename using the `filename` parameter. The function returns the path to the saved file.

```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}")
```

--------------------------------

### Initialize MarketDataClient

Source: https://www.marketdata.app/docs/sdk/py/client

Demonstrates how to create an instance of the MarketDataClient. It shows initialization with an environment variable, an explicit token, and with a custom logger.

```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)
```

--------------------------------

### MarketDataClient Initialization

Source: https://www.marketdata.app/docs/sdk/py/client

Demonstrates how to create an instance of the MarketDataClient, with options for providing an API token and a custom logger.

```APIDOC
## MarketDataClient

### Description
The `MarketDataClient` is the primary class for interacting with the Market Data API. It manages authentication, rate limits, and provides access to various market data resources.

### Method
`__init__`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
from marketdata import MarketDataClient

# Initialize with token from environment variable
client = MarketDataClient()

# Initialize with an explicit token
client = MarketDataClient(token="your_token_here")

# Initialize with a custom logger
from marketdata.logger import get_logger
custom_logger = get_logger()
client = MarketDataClient(token="your_token_here", logger=custom_logger)
```

### Response
#### Success Response (200)
Returns an initialized `MarketDataClient` instance.

#### Response Example
```json
{
  "message": "Client initialized successfully"
}
```

### Notes
- The client automatically fetches rate limits upon initialization.
- Includes a `User-Agent` header in the format `marketdata-py-{version}`.
- All requests include an `Authorization: Bearer {token}` header.
- Uses `httpx.Client` for efficient HTTP requests.
```

--------------------------------

### Configuration

Source: https://www.marketdata.app/docs/sdk/py/client

Details on how to configure universal parameters for the SDK.

```APIDOC
## Configuration

### Description

The SDK offers flexible configuration options for universal parameters, allowing you to customize settings such as output format, date format, data mode, and more.

### Method

N/A (Informational)

### Endpoint

N/A (Informational)

### Parameters

Refer to the [Settings documentation](link_to_settings_documentation) for a complete list of available configuration options and their usage.

### Request Example

```python
# Example of accessing configuration (specific method depends on SDK implementation)
# sdk_instance.configure(output_format='json', date_format='iso')
```

### Response

N/A (Configuration is applied client-side within the SDK.
```

--------------------------------

### Make Test Request with MarketDataClient (Environment Variable)

Source: https://www.marketdata.app/docs/sdk/py/authentication

This Python code initializes the MarketDataClient, which automatically reads the MARKETDATA_TOKEN from the environment variable. It then makes a test request for 'SPY' quotes and prints the result or any errors encountered. This verifies SDK authentication.

```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)
```

--------------------------------

### Get Stock Quotes (Human-Readable)

Source: https://www.marketdata.app/docs/sdk/py/stocks/quotes

Retrieves stock quotes for a single symbol in a human-readable format.

```APIDOC
## GET /stocks/quotes (Human-Readable)

### Description
Retrieves stock quotes for a single symbol in a human-readable format, with capitalized field names.

### Method
GET

### Endpoint
/stocks/quotes

### Query Parameters
- **symbol** (str) - Required - The stock symbol to retrieve the quote for.
- **output_format** (OutputFormat) - Optional - Specifies the output format. Defaults to JSON.
- **use_human_readable** (bool) - Optional - If True, returns data in a human-readable format.

### Request Example
```python
from marketdata import MarketDataClient, OutputFormat

client = MarketDataClient()
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}")
```

### Response
#### Success Response (200)
- **StockQuotesHumanReadable Object** - An object containing stock quote details in a human-readable format.
  - **Symbol** (str): The stock symbol.
  - **Ask** (float): The asking price.
  - **Ask_Size** (int): The size of the ask.
  - **Bid** (float): The bidding price.
  - **Bid_Size** (int): The size of the bid.
  - **Mid** (float): The mid price.
  - **Last** (float): The last traded price.
  - **Change_Price** (float): The price change.
  - **Change_Percent** (float): The percentage change.
  - **Volume** (int): The trading volume.
  - **Date** (datetime.datetime): The last updated time.

#### Response Example
```
Symbol: AAPL
Ask: 278.55
Bid: 278.54
Change Price: 0.51
Change Percent: 0.0018
```
```

--------------------------------

### Get Stock Quotes (JSON)

Source: https://www.marketdata.app/docs/sdk/py/stocks/quotes

Retrieves stock quotes for specified symbols in JSON format.

```APIDOC
## GET /stocks/quotes

### Description
Retrieves stock quotes for a list of symbols in JSON format.

### Method
GET

### Endpoint
/stocks/quotes

### Query Parameters
- **symbols** (list[str]) - Required - A list of stock symbols to retrieve quotes for.
- **output_format** (OutputFormat) - Optional - Specifies the output format. Defaults to JSON.

### Request Example
```python
from marketdata import MarketDataClient, OutputFormat

client = MarketDataClient()
quotes = client.stocks.quotes(["AAPL", "MSFT"], output_format=OutputFormat.JSON)
print(quotes)
```

### Response
#### Success Response (200)
- **s** (str) - Status indicator ('ok' or 'error').
- **symbol** (list[str]) - List of stock symbols.
- **ask** (list[float]) - List of asking prices.
- **askSize** (list[int]) - List of ask sizes.
- **bid** (list[float]) - List of bidding prices.
- **bidSize** (list[int]) - List of bid sizes.
- **mid** (list[float]) - List of mid prices.
- **last** (list[float]) - List of last traded prices.
- **change** (list[float]) - List of price changes.
- **changepct** (list[float]) - List of percentage changes.
- **volume** (list[int]) - List of trading volumes.
- **updated** (list[int]) - List of update timestamps (Unix timestamp).

#### Response Example
```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]
}
```
```

--------------------------------

### Get Stock Quotes (CSV)

Source: https://www.marketdata.app/docs/sdk/py/stocks/quotes

Retrieves stock quotes for specified symbols and saves them to a CSV file.

```APIDOC
## GET /stocks/quotes (CSV)

### Description
Retrieves stock quotes for a list of symbols and saves them to a CSV file.

### Method
GET

### Endpoint
/stocks/quotes

### Query Parameters
- **symbols** (list[str]) - Required - A list of stock symbols to retrieve quotes for.
- **output_format** (OutputFormat) - Required - Must be set to `OutputFormat.CSV`.
- **filename** (Path) - Required - The path to save the CSV file.

### Request Example
```python
from marketdata import MarketDataClient, OutputFormat
from pathlib import Path

client = MarketDataClient()
csv_file = client.stocks.quotes(
    ["AAPL", "MSFT"],
    output_format=OutputFormat.CSV,
    filename=Path("quotes.csv")
)
print(f"CSV file saved to: {csv_file}")
```

### Response
#### Success Response (200)
- **message** (str) - Confirmation message indicating the file save location.

#### Response Example
```
CSV file saved to: quotes.csv
```
```

--------------------------------

### MarketDataClient Constructor

Source: https://www.marketdata.app/docs/sdk/py/client

The constructor for the MarketDataClient class. It initializes the client with an optional authentication token and logger, sets up HTTP configurations, and fetches initial rate limits.

```python
def __init__(self, token: str = None, logger: Logger = None)

```

--------------------------------

### Get Options Chain as JSON

Source: https://www.marketdata.app/docs/sdk/py/options/chain

Retrieves the options chain data and returns it in JSON format. This is useful for integrating with other systems or for a machine-readable output.

```APIDOC
## GET /options/chain

### Description
Retrieves the options chain data for a given stock symbol and returns it as a JSON object. This format is suitable for machine-to-machine communication and data processing.

### Method
GET

### Endpoint
/options/chain

### Parameters
#### Query Parameters
- **symbol** (str) - Required - The stock ticker symbol (e.g., "AAPL").
- **side** (str) - Optional - The side of the option ('call' or 'put'). Defaults to 'call'.
- **date** (str) - Optional - The date for which to retrieve the options chain in 'YYYY-MM-DD' format.
- **output_format** (OutputFormat) - Optional - The desired output format. Use `OutputFormat.JSON` for JSON output.

### Request Example
```python
from marketdata import MarketDataClient, OutputFormat

client = MarketDataClient()
chain = client.options.chain(
    "AAPL",
    side="call",
    date="2022-01-03",
    output_format=OutputFormat.JSON
)

print(chain)
```

### Response
#### Success Response (200)
- **JSON Object** - A JSON object containing the options chain data.

#### Response Example
```json
{
  "s": "ok",
  "optionSymbol": ["AAPL220318C00175000", "AAPL220318C00180000"],
  "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],
  ...
}
```
```

--------------------------------

### Set Environment Variables for SDK Configuration (Python)

Source: https://www.marketdata.app/docs/sdk/py/settings

Demonstrates how to set environment variables to configure universal parameters for the Market Data Python SDK. These settings have the lowest priority and are applied globally unless overridden.

```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
```

--------------------------------

### GET /stocks/earnings

Source: https://www.marketdata.app/docs/sdk/py/stocks/earnings

Retrieve earnings data for any supported stock symbol. The `earnings()` method on the `stocks` resource can be used to fetch earnings data in various formats.

```APIDOC
## GET /stocks/earnings

### Description
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.

### Method
GET

### Endpoint
/stocks/earnings

### Parameters
#### Query Parameters
- **symbol** (str) - Required - 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) - Optional - The format of the returned data. Defaults to `OutputFormat.DATAFRAME`. See Settings for details.
- **date_format** (DateFormat) - Optional - The date format to use in the response. Defaults to `DateFormat.UNIX`. See Settings for details.
- **columns** (list[str]) - Optional - Specify which columns to include in the response. See Settings for details.
- **add_headers** (bool) - Optional - Whether to include headers in the response. See Settings for details.
- **use_human_readable** (bool) - Optional - Whether to use human-readable format for values. Only applies when `output_format=OutputFormat.INTERNAL`. See Settings for details.
- **mode** (Mode) - Optional - The data mode to use. See Settings for details.
- **filename** (str | Path) - Optional - File path for CSV output (only used with `output_format=OutputFormat.CSV`).

### Response
#### Success Response (200)
- **StockEarnings** | **StockEarningsHumanReadable** | **dict** | **str** | **MarketDataClientErrorResult** - The earnings data in the requested format, or a `MarketDataClientErrorResult` if an error occurred.

#### Response 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)
```

#### Response Example (Internal Object)
```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}")
```

#### Response 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)
```

#### Response 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}")
```

#### Response 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 human-readable 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}")
```
```

--------------------------------

### GET /options/quotes

Source: https://www.marketdata.app/docs/sdk/py/options/quotes

Fetches option quotes for one or more option symbols. Supports multiple output formats including DataFrame, internal object, JSON, and CSV.

```APIDOC
## GET /options/quotes

### Description
Retrieves quotes for one or more option symbols. This method supports multiple output formats and automatically handles multiple symbols by fetching them concurrently.

### Method
GET

### Endpoint
/options/quotes

### Parameters
#### Query Parameters
- **symbols** (str | list[str]) - Required - A single option symbol string or a list of option symbol strings for which to fetch quotes. Option symbols are like "AAPL240120C00150000".
- **output_format** (OutputFormat, optional) - The format of the returned data. Defaults to `OutputFormat.DATAFRAME`. Options include `DATAFRAME`, `INTERNAL`, `JSON`, `CSV`.
- **date_format** (DateFormat, optional) - The date format to use in the response. Defaults to `DateFormat.UNIX`.
- **columns** (list[str], optional) - Specify which columns to include in the response.
- **add_headers** (bool, optional) - Whether to include headers in the response.
- **use_human_readable** (bool, optional) - Whether to use human-readable format for values. Only applies when `output_format=OutputFormat.INTERNAL`.
- **mode** (Mode, optional) - The data mode to use.
- **filename** (str | Path, optional) - File path for CSV output (only used with `output_format=OutputFormat.CSV`).

### Request Example
```python
from marketdata import MarketDataClient

client = MarketDataClient()

# Get option quotes as DataFrame (default)
df = client.options.quotes("AAPL240120C00150000")
# or
df = client.options.quotes(symbols="AAPL240120C00150000")

# Get quotes for multiple option symbols
df = client.options.quotes(["AAPL240120C00150000", "AAPL240120P00150000"])

print(df)
```

### Response
#### Success Response (200)
- **OptionsQuotes | OptionsQuotesHumanReadable | dict | str** - The option quotes in the requested format.

#### Response Example (DataFrame)
```json
{
  "optionSymbol": "AAPL240120C00150000",
  "expirationDate": "2024-01-20",
  "strike": 150.0,
  "optionType": "Call",
  "bid": 10.50,
  "ask": 10.75,
  "volume": 1000,
  "openInterest": 5000,
  "lastPrice": 10.60,
  "lastVolume": 50,
  "impliedVolatility": 0.25,
  "delta": 0.60,
  "gamma": 0.10,
  "theta": -0.05,
  "vega": 0.02,
  "rho": 0.01
}
```

#### Response Example (Internal Object)
```python
from marketdata import MarketDataClient, OutputFormat

client = MarketDataClient()

quotes = client.options.quotes(
    ["AAPL240120C00150000", "AAPL240120P00150000"],
    output_format=OutputFormat.INTERNAL
)

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]}")
```

#### Response Example (JSON)
```python
from marketdata import MarketDataClient, OutputFormat

client = MarketDataClient()

quotes = client.options.quotes(
    ["AAPL240120C00150000", "AAPL240120P00150000"],
    output_format=OutputFormat.JSON
)

print(quotes)
```

#### Response Example (CSV)
```python
from marketdata import MarketDataClient, OutputFormat
from pathlib import Path

client = MarketDataClient()

filename = client.options.quotes(
    ["AAPL240120C00150000", "AAPL240120P00150000"],
    output_format=OutputFormat.CSV,
    filename="option_quotes.csv"
)

print(f"CSV data written to: {filename}")
```
```

--------------------------------

### Set Direct Parameters for Market Data Calls (Python)

Source: https://www.marketdata.app/docs/sdk/py/settings

Demonstrates how to set parameters directly within method calls for the Market Data SDK. The `mode` parameter, available on paid plans, allows specifying data retrieval mode (e.g., CACHED, LIVE). Free and trial plans are limited to delayed data.

```python
chain = client.options.chain("SPY", mode=Mode.CACHED)
quotes = client.stocks.quotes("AAPL", mode=Mode.LIVE)
```

--------------------------------

### GET /options/chain

Source: https://www.marketdata.app/docs/sdk/py/options/chain

Fetches the options chain for a specified stock symbol. Supports various filters for expiration, strike price, date, and option characteristics.

```APIDOC
## GET /options/chain

### Description
Fetches the options chain for a specified stock symbol. Supports various filters for expiration, strike price, date, and option characteristics.

### Method
GET

### Endpoint
/options/chain

### Parameters
#### Query Parameters
- **symbol** (str) - Required - 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, optional) - The format of the returned data. Defaults to `OutputFormat.DATAFRAME`.
- **date_format** (DateFormat, optional) - The date format to use in the response. Defaults to `DateFormat.UNIX`.
- **columns** (optional) - Specify which columns to include in the response.
- **add_headers** (optional) - Whether to include headers in the response.
- **use_human_readable** (optional) - Whether to use human-readable format for values. Only applies when `output_format=OutputFormat.INTERNAL`.
- **mode** (Mode, optional) - The data mode to use.
- **filename** (str | Path, optional) - File path for CSV output (only used with `output_format=OutputFormat.CSV`).

### Request Example
```python
from marketdata import MarketDataClient

client = MarketDataClient()

# Get options chain as DataFrame (default)
chain = client.options.chain("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)
```

### Response
#### Success Response (200)
- **OptionsChain** | **OptionsChainHumanReadable** | **dict** | **str** | **MarketDataClientErrorResult** - The options chain data in the requested format, or a `MarketDataClientErrorResult` if an error occurred.

#### Response Example (DataFrame)
```
                    underlying  expiration        side  strike  ...  volume  openInterest  inTheMoney  underlyingPrice  
optionSymbol                                                     ...  
AAPL220318C00175000       AAPL  2022-03-18       call   175.0  ...    1295         15232        True           182.01  
AAPL220318C00180000       AAPL  2022-03-18       call   180.0  ...    4609         18299        True           182.01  
```

### 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.
```

--------------------------------

### Override SDK Configuration with Direct Method Parameters (Python)

Source: https://www.marketdata.app/docs/sdk/py/settings

Illustrates how to pass parameters directly to resource methods, which provides the highest priority for configuration. These parameters override both environment variables and client default parameters for that specific API call.

```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
```

--------------------------------

### Get Options Chain as Internal Object

Source: https://www.marketdata.app/docs/sdk/py/options/chain

Retrieves the options chain data and returns it as an internal Python object. You can then access individual option attributes by index.

```APIDOC
## GET /options/chain

### Description
Retrieves the options chain data for a given stock symbol, returning it as an internal Python object. This object allows direct access to option attributes like symbol, strike, expiration, bid, ask, and mid by index.

### Method
GET

### Endpoint
/options/chain

### Parameters
#### Query Parameters
- **symbol** (str) - Required - The stock ticker symbol (e.g., "AAPL").
- **side** (str) - Optional - The side of the option ('call' or 'put'). Defaults to 'call'.
- **date** (str) - Optional - The date for which to retrieve the options chain in 'YYYY-MM-DD' format.
- **dte** (int) - Optional - Days to expiration filter.
- **strike_limit** (int) - Optional - The number of strikes to retrieve above and below the current price.
- **range** (str) - Optional - Filter options by 'itm' (in-the-money), 'otm' (out-of-the-money), or 'all'.
- **output_format** (OutputFormat) - Optional - The desired output format. Use `OutputFormat.INTERNAL` for an internal object.
- **use_human_readable** (bool) - Optional - If True, returns human-readable field names (e.g., 'Strike' instead of 'strike').

### Request Example
```python
from marketdata import MarketDataClient, OutputFormat

client = MarketDataClient()
chain = client.options.chain(
    "AAPL",
    side="call",
    date="2022-01-03",
    dte=60,
    strike_limit=2,
    range="itm",
    output_format=OutputFormat.INTERNAL
)

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]}")
```

### Response
#### Success Response (200)
- **OptionsChain** (object) - An object containing lists of option data attributes.

#### Response Example
```
Number of options: 2
First option symbol: AAPL220318C00175000
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
```
```

--------------------------------

### Verify MARKETDATA_TOKEN Environment Variable on Windows

Source: https://www.marketdata.app/docs/sdk/py/authentication

This command verifies if the MARKETDATA_TOKEN environment variable is set correctly on Windows. It outputs the variable's value if set, otherwise it outputs the variable name itself.

```bash
echo %MARKETDATA_TOKEN%
```
Tokens:
Raw