# How to Use the OpenBB Python SDK's obb Object for Equity Data Queries

> Learn to query equity data with the OpenBB Python SDKs obb object. Access typed results and easily convert them to DataFrames for analysis.

- Repository: [OpenBB/OpenBB](https://github.com/OpenBB-finance/OpenBB)
- Tags: how-to-guide
- Published: 2026-03-06

---

**The OpenBB Python SDK exposes a ready-to-use `obb` instance that routes equity data queries through FastAPI-style routers to provider-specific fetchers, returning typed results wrapped in an `OBBject` with helpers like `.to_df()` and `.show()`.**

The OpenBB Python SDK provides programmatic access to financial markets through a unified interface. By importing the pre-instantiated `obb` object from the `openbb` package, you can query historical stock prices, company profiles, and real-time quotes across multiple data providers without managing low-level API authentication or response parsing.

## What Is the `obb` Object?

The `obb` object is a singleton instance of **`OBBject`** created at import time and exposed through the package’s [`__init__.py`](https://github.com/OpenBB-finance/OpenBB/blob/main/__init__.py). Internally defined in [`openbb_platform/core/openbb_core/app/model/obbject.py`](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_platform/core/openbb_core/app/model/obbject.py), it acts as a thin wrapper around the OpenBB query engine. When you call methods like `obb.equity.price.historical()`, the `obb` instance constructs a fully-typed API request, executes it against your selected data provider, and returns an `OBBject` containing the raw results and conversion utilities.

## How Equity Data Queries Are Routed

Calls to `obb.equity.*` follow a structured execution pipeline:

1. **Command Routing** – Methods such as `obb.equity.profile()` or `obb.equity.price.historical()` map to FastAPI-style routers defined in [`openbb_platform/extensions/equity/openbb_equity/equity_router.py`](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_platform/extensions/equity/openbb_equity/equity_router.py). This router registers commands including `search`, `profile`, and `historical_market_cap`.

2. **Query Construction** – The router bundles your parameters (e.g., `symbol`, `start_date`, `provider`) into a **`Query`** object containing command context, provider choices, and standard or extra parameters.

3. **Execution** – The router invokes **`OBBject.from_query`**, which dispatches to a provider-specific fetcher. For example, when using `yfinance`, the system calls `openbb_yfinance.models.equity_historical.YFinanceEquityHistoricalFetcher` as defined in [`openbb_platform/providers/yfinance/openbb_yfinance/models/equity_historical.py`](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_platform/providers/yfinance/openbb_yfinance/models/equity_historical.py).

4. **Result Wrapping** – Raw data returns as a list of Pydantic BaseModel objects stored in the `results` attribute of a new `OBBject` instance.

## Querying Equity Data with `obb`

After installing the SDK (`pip install openbb-platform`), import the instance and begin querying immediately.

### Historical Stock Prices

Retrieve daily OHLCV data by calling the price router. The default provider is `yfinance`, but you can override it with the `provider` parameter.

```python
from openbb import obb

# Fetch 6 months of Apple price history

df = obb.equity.price.historical(
    symbol="AAPL",
    start_date="2024-07-01",
    end_date="2024-12-31",
    interval="1d",
    provider="yfinance"
).to_df()

print(df.head())

```

**What happens internally:** `obb.equity.price.historical` resolves to `openbb_equity.price.price_router`, which builds a `Query` object. `OBBject.from_query` executes via `YFinanceEquityHistoricalFetcher`, and `.to_df()` converts the BaseModel list to a Pandas DataFrame using the `basemodel_to_df` helper in [`openbb_core/app/utils.py`](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_core/app/utils.py).

### Real-Time Equity Quotes

Access current price snapshots and volume data through the quote endpoint.

```python
quote = obb.equity.price.quote(
    symbol="MSFT",
    provider="fmp"
)

# Inspect structured fields

print(quote.results.price)
print(quote.results.change_percent)

```

### Company Profiles and Fundamentals

Fetch descriptive metadata including sector, industry, and market cap.

```python
profile = obb.equity.profile(
    symbol="TSLA",
    provider="intrinio"
)

# Export to dictionary for JSON serialization

profile_dict = profile.to_dict()
print(profile_dict["company_name"])

```

### Visualizing Historical Data

Many equity endpoints support built-in charting via the charting extension defined in [`openbb_platform/obbject_extensions/charting/openbb_charting/charting.py`](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_platform/obbject_extensions/charting/openbb_charting/charting.py). Pass `chart=True` to receive a visualization object.

```python
chart_obj, chart_json = obb.equity.price.historical(
    symbol=["AAPL", "MSFT"],
    start_date="2024-01-01",
    provider="fmp",
    chart=True
)

# Render inline in Jupyter or compatible environments

chart_obj.show()

```

### Switching Data Providers on the Fly

The `provider` parameter accepts any configured source (`yfinance`, `fmp`, `intrinio`, `tiingo`) without changing the method signature. This provider abstraction is handled through the `ProviderChoices` enum.

```python

# Same query, different data source

df_tiingo = obb.equity.price.historical(
    symbol="GOOGL",
    start_date="2024-01-01",
    provider="tiingo"
).to_df()

```

## Working with OBBject Results

Every query returns an `OBBject` instance containing the following utilities:

- **`.to_df()`** – Converts `results` (a list of Pydantic models) into a Pandas DataFrame.
- **`.to_dict()`** – Exports results as a nested Python dictionary.
- **`.show()`** – Renders interactive charts when the endpoint includes visualization data.

The conversion logic relies on `basemodel_to_df` in [`openbb_core/app/utils.py`](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_core/app/utils.py), ensuring type-safe DataFrame generation even with nested financial data structures.

## Key Implementation Files

| Purpose | File Path |
|---------|-----------|
| Core `OBBject` class implementation | [`openbb_platform/core/openbb_core/app/model/obbject.py`](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_platform/core/openbb_core/app/model/obbject.py) |
| Equity command router (search, profile, market cap) | [`openbb_platform/extensions/equity/openbb_equity/equity_router.py`](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_platform/extensions/equity/openbb_equity/equity_router.py) |
| Price-specific router (historical, quote) | [`openbb_platform/extensions/equity/openbb_equity/price/price_router.py`](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_platform/extensions/equity/openbb_equity/price/price_router.py) |
| YFinance historical equity fetcher | [`openbb_platform/providers/yfinance/openbb_yfinance/models/equity_historical.py`](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_platform/providers/yfinance/openbb_yfinance/models/equity_historical.py) |
| Charting extension for `.show()` | [`openbb_platform/obbject_extensions/charting/openbb_charting/charting.py`](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_platform/obbject_extensions/charting/openbb_charting/charting.py) |
| DataFrame conversion utilities | [`openbb_core/app/utils.py`](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_core/app/utils.py) |

## Summary

- The **`obb`** object is a pre-instantiated `OBBject` that serves as the primary entry point for all OpenBB Python SDK queries.
- Equity commands route through **[`equity_router.py`](https://github.com/OpenBB-finance/OpenBB/blob/main/equity_router.py)**, construct **`Query`** objects, and execute via provider-specific fetchers.
- Results return as **`OBBject`** instances with **`.to_df()`**, **`.to_dict()`**, and **`.show()`** methods for immediate analysis.
- Switch providers using the **`provider`** parameter without changing code structure; supported sources include `yfinance`, `fmp`, `intrinio`, and `tiingo`.
- Charting support is built-in via the charting extension when passing `chart=True` to compatible endpoints.

## Frequently Asked Questions

### What is an OBBject in the OpenBB Python SDK?

An `OBBject` is a wrapper class defined in [`openbb_platform/core/openbb_core/app/model/obbject.py`](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_platform/core/openbb_core/app/model/obbject.py) that encapsulates query results, metadata, and conversion utilities. It provides a consistent interface for accessing financial data regardless of the underlying provider, exposing methods like `.to_df()` to transform raw Pydantic models into Pandas DataFrames.

### How do I convert OpenBB query results to a Pandas DataFrame?

Call the **`.to_df()`** method on any returned `OBBject`. For example, `obb.equity.price.historical(...).to_df()` executes a query and immediately converts the results list into a DataFrame using the internal `basemodel_to_df` utility. This works uniformly across equity, fixed income, and alternative data endpoints.

### Can I use multiple data providers with the same obb query method?

Yes. The `provider` parameter allows you to switch sources (e.g., `yfinance`, `fmp`, `tiingo`) without modifying the method signature or parameter names. The SDK’s `ProviderChoices` abstraction ensures that standard parameters like `symbol` and `start_date` map correctly to each provider’s API requirements.

### Does the obb object support real-time stock quotes?

Yes. Use `obb.equity.price.quote(symbol="TICKER")` to retrieve real-time price snapshots, change percentages, and volume data. The specific fields available depend on the selected provider; for instance, Financial Modeling Prep (`fmp`) and Intrinio return slightly different metadata structures within the `results` attribute.