Quick Start

This guide will help you make your first Bloomberg request.

If your environment uses Bloomberg ZFP over leased lines instead of a local Terminal or direct B-PIPE host, configure zfp_remote with TLS credentials before the first request. See ZFP over Leased Lines.

Reference Data (BDP)

Get point-in-time data for securities:

import xbbg

# Single ticker, single field
df = xbbg.bdp('AAPL US Equity', 'PX_LAST')

# Multiple tickers and fields
df = xbbg.bdp(
    ['AAPL US Equity', 'MSFT US Equity'],
    ['PX_LAST', 'VOLUME', 'NAME']
)

Output (long format):

ticker	field	value
AAPL US Equity	PX_LAST	185.50
AAPL US Equity	VOLUME	45234521
AAPL US Equity	NAME	Apple Inc
MSFT US Equity	PX_LAST	378.91
…	…	…

Historical Data (BDH)

Get time series data:

df = xbbg.bdh(
    'AAPL US Equity',
    ['PX_LAST', 'VOLUME'],
    start_date='2024-01-01',
    end_date='2024-01-31'
)

start_date and end_date accept ISO 8601 strings, YYYYMMDD strings, "today", datetime.date, datetime.datetime, or pandas.Timestamp — pass whichever your codebase already has:

from datetime import date

df = xbbg.bdh(
    'AAPL US Equity',
    'PX_LAST',
    start_date=date(2024, 1, 1),
    end_date=date(2024, 1, 31),
)

See the Dates and Datetimes guide for the full accepted set, override-path normalization, and timezone semantics.

Output:

ticker	date	field	value
AAPL US Equity	2024-01-02	PX_LAST	185.50
AAPL US Equity	2024-01-02	VOLUME	45234521
AAPL US Equity	2024-01-03	PX_LAST	186.20
…	…	…	…

Use Bloomberg Excel-style aliases when you want shorter historical request options:

weekly = xbbg.bdh(
    'AAPL US Equity',
    'PX_LAST',
    start_date='2024-01-01',
    end_date='2024-03-31',
    Per='W',        # periodicitySelection='WEEKLY'
    Fill='P',       # nonTradingDayFillMethod='PREVIOUS_VALUE'
    Points=12,      # maxDataPoints=12
    Dts='Show',     # keep date output
    DtFmt='Both',   # include period labels next to dates
    Sort='Reverse', # newest rows first
    Direction='V',  # vertical/long output shape
)

Bulk Data (BDS)

Get multi-row data like dividends or index members:

# Dividend history
df = xbbg.bds('AAPL US Equity', 'DVD_Hist_All')

# Index members
df = xbbg.bds('SPX Index', 'INDX_MEMBERS')

bds() and abds() preserve Bloomberg bulk subfield labels exactly as emitted. The only xbbg-added columns are ticker and field; field-specific columns may contain spaces, punctuation, and Bloomberg casing such as Future's Ticker or Last Trade Date. Normalize or rename these columns in your own code when you need a stable application schema.

Choose Your Backend

The default return is a Narwhals DataFrame. When PyArrow is installed, xbbg preserves the legacy behavior by backing that Narwhals frame with a real pyarrow.Table; otherwise it falls back through installed dataframe libraries and finally xbbg’s native Arrow carrier. That final native-plugin fallback emits a one-time RuntimeWarning because it intentionally does not implement the full PyArrow/Narwhals expression surface. Use backend="native" when you want the raw xbbg.ArrowTable, or backend="pyarrow" when you need a real pyarrow.Table.

# Default Narwhals DataFrame
df = xbbg.bdp('AAPL US Equity', 'PX_LAST')
print(df.columns, len(df))

# Per-call conversion when a library object is required
df_pd = xbbg.bdp('AAPL US Equity', 'PX_LAST', backend='pandas')  # pandas.DataFrame
table = xbbg.bdp('AAPL US Equity', 'PX_LAST', backend='native')  # xbbg.ArrowTable

# Available backends: narwhals, native, pyarrow, pandas, polars, duckdb, ...

Async Support

For concurrent requests, use the async API:

import asyncio
import xbbg

async def main():
    # Concurrent requests
    results = await asyncio.gather(
        xbbg.abdp('AAPL US Equity', 'PX_LAST'),
        xbbg.abdp('MSFT US Equity', 'PX_LAST'),
        xbbg.abdp('GOOGL US Equity', 'PX_LAST'),
    )
    return results

dfs = asyncio.run(main())

Next Steps

API Reference - Full function documentation
DataFrame Backends - Learn about backend options
Output Formats - Typed output formats