Quick start

From first request to async workflows.

This guide walks through the core Python helpers, backend choices, async variants, and a fixed-income example using the shared Rust/Arrow engine.

WARNING

You need an active Bloomberg Terminal, B-PIPE, or appropriately licensed Bloomberg connectivity to run these examples.

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.

1. Configure the session

import xbbg

xbbg.configure(host='localhost', port=8194)

Use configuration for connection facts such as host lists, auth, TLS, ZFP, SOCKS5, failover, and SDK logging. Keep individual request calls focused on the data they need.

2. Reference data with bdp

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

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

Example output:

ticker	field	value
AAPL US Equity	PX_LAST	185.50
AAPL US Equity	VOLUME	45234521
MSFT US Equity	PX_LAST	378.91

3. Historical data with bdh

from datetime import date

history = xbbg.bdh(
    'AAPL US Equity',
    ['PX_LAST', 'VOLUME'],
    start_date=date(2024, 1, 1),
    end_date=date(2024, 1, 31),
)

Dates accept ISO 8601 strings, YYYYMMDD strings, "today", datetime.date, datetime.datetime, or pandas.Timestamp. See the Dates and Datetimes guide for accepted values, override normalization, and timezone semantics.

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
)

4. Bulk data with bds

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

# Index members
members = 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 application code when you need a stable schema.

5. Choose an output backend

# Global setting
xbbg.set_backend('polars')
polars_df = xbbg.bdp('AAPL US Equity', 'PX_LAST')

# Per-call override
pandas_df = xbbg.bdp('AAPL US Equity', 'PX_LAST', backend='pandas')

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

See DataFrame Backends and Output Formats for the full output model.

6. Run concurrent requests

import asyncio
import xbbg

async def main():
    apple, microsoft, alphabet = 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 apple, microsoft, alphabet

results = asyncio.run(main())

The a-prefixed helpers use the same API shape as the blocking helpers while letting licensed Bloomberg data requests overlap without blocking application code.

7. Try a fixed-income workflow

from xbbg import blp

# Discover USD government curves
curves = blp.bcurves(currency='USD', curve_type='GOVERNMENT')

# Dealer quote request with bond-specific fields
quotes = blp.bqr(
    'US037833FB15@MSG1 Corp',
    date_offset='-2d',
    include_broker_codes=True,
    include_spread_price=True,
    include_yield=True,
)

See Fixed Income for curves, government securities, BQR, YAS, corporate bonds, and bond analytics.

8. Add production middleware

from xbbg import blp

@blp.add_middleware
async def tag_request(context, call_next):
    context.metadata['source'] = 'research-notebook'
    return await call_next(context)

Middleware is the supported place for tracing, metrics, audit tags, authorization checks, policy enforcement, and standardized request metadata.

Next steps

Async Patterns

Use true async helpers and understand GIL behavior.

Streaming Data

Work with subscriptions and runtime diagnostics.

Fixed Income

Discover instruments and run yield/quote/risk workflows.

API Reference

Browse generated Python API docs.