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

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. Internally defined in 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. 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.

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.

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.

Real-Time Equity Quotes

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

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.

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. Pass chart=True to receive a visualization object.

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.

# 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, 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
Equity command router (search, profile, market cap)	openbb_platform/extensions/equity/openbb_equity/equity_router.py
Price-specific router (historical, quote)	openbb_platform/extensions/equity/openbb_equity/price/price_router.py
YFinance historical equity fetcher	openbb_platform/providers/yfinance/openbb_yfinance/models/equity_historical.py
Charting extension for .show()	openbb_platform/obbject_extensions/charting/openbb_charting/charting.py
DataFrame conversion utilities	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, 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}