bbg-fetch

Bloomberg Desktop API request/response data in pandas DataFrames for quantitative research.

It wraps BDP-, BDH-, and BDS-style requests and selected research workflows. Live requests require a running Bloomberg Terminal, suitable entitlements, and Bloomberg's separately installed blpapi; streaming and intraday subscriptions are out of scope.

Install: pip install bbg-fetch · Import: bbg_fetch · Status: Beta

import pandas as pd

from bbg_fetch import fetch_field_timeseries_per_tickers

prices = fetch_field_timeseries_per_tickers(
    tickers={'ES1 Index': 'SPX', 'TY1 Comdty': '10yUST'},
    field='PX_LAST',
    start_date=pd.Timestamp('2020-01-01')
)
# Returns a clean DataFrame with renamed columns, sorted index, split/div adjusted

Why bbg-fetch

Direct blpapi use requires session setup, request construction, event handling, and response parsing. bbg-fetch centralises that request/response plumbing for repeated research workflows.

With blpapi:

import blpapi

opts = blpapi.SessionOptions()
opts.setServerHost('localhost')
opts.setServerPort(8194)
session = blpapi.Session(opts)
session.start()
session.openService('//blp/refdata')
service = session.getService('//blp/refdata')
request = service.createRequest('HistoricalDataRequest')
request.getElement('securities').appendValue('AAPL US Equity')
request.getElement('fields').appendValue('PX_LAST')
request.set('startDate', '20200101')
request.set('endDate', '20241231')
request.set('adjustmentNormal', True)
request.set('adjustmentAbnormal', True)
request.set('adjustmentSplit', True)
session.sendRequest(request)
# Consume response events and assemble a DataFrame.

With bbg-fetch:

import pandas as pd

from bbg_fetch import fetch_field_timeseries_per_tickers

prices = fetch_field_timeseries_per_tickers(
    tickers=['AAPL US Equity'],
    field='PX_LAST',
    start_date=pd.Timestamp('2020-01-01')
)

The wrapper handles the session/request/response path and returns the result as a DataFrame.

bbg-fetch wraps BDP, BDH, and BDS requests in high-level functions that return pandas objects with documented column naming, corporate-action flags, and index handling. The direct blpapi session implementation is isolated in the private _blp_api.py module.

Key differentiators

Multi-asset coverage

• Equities: Historical prices with split/dividend adjustments, fundamentals, dividend history
• Futures: Contract tables with carry analysis, active contract series, roll handling
• Options: Implied volatility surfaces (moneyness and delta), option chains
• Fixed Income: Bond pricing and analytics by ISIN, yield curves, CDS spreads
• FX: Currency rates and volatility
• Indices: Constituent weights, ISIN-to-ticker resolution

Request/response conveniences

• Dict-based ticker renaming: {'ES1 Index': 'SPX'} → DataFrame columns named SPX
• Automatic retry on Bloomberg connection flakes
• Corporate action adjustments on by default (normal, abnormal, splits)
• Predefined field mappings for vol surfaces (30d/60d/3m/6m/12m moneyness, delta)
• Carry computation built into futures contract tables

When to use it — and when not

bbg-fetch targets research workflows: request/response pulls of reference data, price histories, volatility surfaces, and index constituents into analysis-ready DataFrames from a machine running the Bloomberg Terminal (Desktop API via blpapi). A terminal login and the corresponding data entitlements are required — the package wraps access, it does not provide data.

It is request/response by design: no streaming subscriptions and no intraday tick capture. Where no terminal is available, the examples in qis run on free Yahoo data instead.

Installation

1. Install blpapi

python -m pip install --index-url=https://blpapi.bloomberg.com/repository/releases/python/simple/ blpapi

Bloomberg's current API Library provides bundled Python wheels for community-supported Python versions. The live Desktop API workflow documented here targets Windows; Bloomberg's Linux and macOS API distributions serve different Bloomberg server products rather than a local Professional Terminal. Check the official API Library for the current platform and release matrix.

Corporate proxy? Download the .whl from https://blpapi.bloomberg.com/repository/releases/python/simple/blpapi/ via browser, then:

python -m pip install /path/to/blpapi-wheel.whl

2. Install bbg-fetch

pip install bbg-fetch

Or from source:

git clone https://github.com/ArturSepp/BloombergFetch.git
pip install .

Requirements: Python 3.10+, with the Bloomberg Desktop API and an entitled Bloomberg Terminal session available on the same Windows machine for live requests.

Five-minute quickstart

After installing blpapi and bbg-fetch, run the deterministic example from a source checkout:

python examples/quickstart_no_terminal.py

It checks the public API on a synthetic option chain and prints Bloomberg connection: NOT TESTED. It makes no live request and writes no data. See first success without a Terminal for the complete script and expected evidence.

Examples

Authoritative runnable scripts are indexed in examples/README.md. The index separates the terminal-free installation/API check from examples that require a running, entitled Bloomberg Terminal.

Start with the same two root scripts used by the documentation:

1. Run examples/quickstart_no_terminal.py to verify the installed API against deterministic synthetic data. It does not test a Bloomberg connection.
2. On an entitled Bloomberg machine, run examples/diagnose_terminal.py to make one scalar request and report only success state, dimensions, and schema. Select a different request with --ticker and --field.

The first script is exercised against the built wheel from outside the checkout in CI. The live diagnostic is deliberately local-only and never runs in CI.

Prices across tickers (with renaming)

import pandas as pd
from bbg_fetch import fetch_field_timeseries_per_tickers

# Pass a dict to auto-rename columns: Bloomberg ticker → your label
prices = fetch_field_timeseries_per_tickers(
    tickers={'ES1 Index': 'SPX', 'TY1 Comdty': '10yUST', 'GC1 Comdty': 'Gold'},
    field='PX_LAST',
    start_date=pd.Timestamp('2015-01-01')
)
# DataFrame with columns ['SPX', '10yUST', 'Gold'], DatetimeIndex, sorted, adjusted

# Or pass a list — column names stay as Bloomberg tickers
prices = fetch_field_timeseries_per_tickers(
    tickers=['AAPL US Equity', 'MSFT US Equity'],
    field='PX_LAST',
    start_date=pd.Timestamp('2020-01-01')
)

# Unadjusted prices (for futures, rates, etc.)
raw = fetch_field_timeseries_per_tickers(
    tickers=['TY1 Comdty'], field='PX_LAST',
    CshAdjNormal=False, CshAdjAbnormal=False, CapChg=False
)

Multiple fields for a single ticker

from bbg_fetch import fetch_fields_timeseries_per_ticker

# OHLC data
ohlc = fetch_fields_timeseries_per_ticker(
    ticker='AAPL US Equity',
    fields=['PX_OPEN', 'PX_HIGH', 'PX_LOW', 'PX_LAST'],
    start_date=pd.Timestamp('2023-01-01')
)

# Futures-specific fields
fut_data = fetch_fields_timeseries_per_ticker(
    ticker='ES1 Index',
    fields=['PX_LAST', 'FUT_DAYS_EXP'],
    CshAdjNormal=False, CshAdjAbnormal=False, CapChg=False
)

Company fundamentals

from bbg_fetch import fetch_fundamentals

# Basic security info
info = fetch_fundamentals(
    tickers=['AAPL US Equity', 'GOOGL US Equity'],
    fields=['security_name', 'gics_sector_name', 'crncy', 'market_cap']
)

# Fund-level data
fund_info = fetch_fundamentals(
    tickers=['HAHYIM2 HK Equity'],
    fields=['name', 'front_load', 'back_load', 'fund_mgr_stated_fee', 'fund_min_invest']
)

# Dict-based renaming works for both tickers and fields
info = fetch_fundamentals(
    tickers={'AAPL US Equity': 'Apple', 'MSFT US Equity': 'Microsoft'},
    fields={'security_name': 'Name', 'gics_sector_name': 'Sector'}
)

Balance sheet and credit metrics

from bbg_fetch import fetch_balance_data

credit = fetch_balance_data(
    tickers=['ABI BB Equity', 'T US Equity', 'JPM US Equity'],
    fields=('GICS_SECTOR_NAME', 'TOT_COMMON_EQY', 'BS_LT_BORROW',
            'NET_DEBT_TO_EBITDA', 'INTEREST_COVERAGE_RATIO',
            'FREE_CASH_FLOW_MARGIN', 'EARN_YLD')
)

Current market prices

from bbg_fetch import fetch_last_prices, FX_DICT

# FX rates (uses built-in FX_DICT by default: 19 major pairs)
fx = fetch_last_prices()

# Custom tickers
prices = fetch_last_prices(tickers=['AAPL US Equity', 'SPX Index', 'USGG10YR Index'])

# With renaming
prices = fetch_last_prices(
    tickers={'ES1 Index': 'SPX Fut', 'TY1 Comdty': '10y Fut', 'GC1 Comdty': 'Gold Fut'}
)

Implied volatility surface

from bbg_fetch import (fetch_vol_timeseries, fetch_vol_surface, IMPVOL_FIELDS_DELTA,
                       IMPVOL_FIELDS_MNY_30DAY, IMPVOL_FIELDS_MNY_60DAY,
                       IMPVOL_FIELDS_MNY_3MTH, IMPVOL_FIELDS_MNY_6MTH,
                       IMPVOL_FIELDS_MNY_12M)

# Delta-based vol for FX (1M and 2M, 10Δ to 50Δ puts and calls)
fx_vol = fetch_vol_timeseries(
    ticker='EURUSD Curncy',
    vol_fields=IMPVOL_FIELDS_DELTA,
    start_date=pd.Timestamp('2023-01-01')
)
# Returns: spot_price, div_yield, rf_rate + all vol columns

# Full moneyness surface across 5 tenors (30d, 60d, 3m, 6m, 12m × 9 strikes)
eq_vol = fetch_vol_timeseries(
    ticker='SPX Index',
    vol_fields=[IMPVOL_FIELDS_MNY_30DAY, IMPVOL_FIELDS_MNY_60DAY,
                IMPVOL_FIELDS_MNY_3MTH, IMPVOL_FIELDS_MNY_6MTH,
                IMPVOL_FIELDS_MNY_12M],
    start_date=pd.Timestamp('2010-01-01')
)

# Single tenor with raw field names (no renaming)
vol_30d = fetch_vol_timeseries(
    ticker='SPX Index',
    vol_fields=['30DAY_IMPVOL_100.0%MNY_DF', '30DAY_IMPVOL_90.0%MNY_DF'],
    start_date=pd.Timestamp('2020-01-01')
)

# Surface snapshot for one date: rows = tenor, columns = moneyness (percent)
surface = fetch_vol_surface(ticker='SPX Index', value_date=pd.Timestamp('2026-07-24'),
                            scaler=None)
# 5 tenors (30d, 60d, 3m, 6m, 12m) x 9 moneyness (80-120); last quote on/before the date

Option chains

import numpy as np
from bbg_fetch import (fetch_option_chain, recover_option_forward, run,
                       OptionPriceSource, OptionChainResult)

# One expiry, trimmed to a strike window around the money (bounds the per-option bdp count)
chain = fetch_option_chain(underlying='KOSPI2 Index', expiry='20260910',
                           num_strikes_per_side=20)

# ... or choose strikes explicitly; the listed strike nearest each target is kept
chain = fetch_option_chain(underlying='KOSPI2 Index', expiry='20260910',
                           strike_grid=np.linspace(700, 1400, 15))

# Implied forward from put-call parity: C(K) - P(K) = exp(-r T) (F - K)
params = recover_option_forward(chain, spot=1055.58, year_fraction=48 / 365,
                                price_source=OptionPriceSource.LAST)
# params: forward, rate, r2, num_strikes_used
# (the forward is well determined; the rate is only indicative at short maturity)

# One call end to end: fetch the chain, infer spot and year fraction from it, recover
# the forward and rate, and return an OptionChainResult snapshot
result = run(underlying='KOSPI2 Index', expiry='20260910',
             strike_grid=np.linspace(700, 1400, 15))
result.forward, result.rate, result.spot, result.year_fraction

# Persist the snapshot to one self-contained CSV and read it back
result.to_csv('kospi2_20260910.csv')
result = OptionChainResult.read_csv('kospi2_20260910.csv')

Futures contract table with carry

from bbg_fetch import fetch_futures_contract_table

# Full contract table: prices, bid/ask, volume, OI, days to expiry, annualised carry
curve = fetch_futures_contract_table(ticker="ES1 Index")

# Nikkei futures
nk_curve = fetch_futures_contract_table(ticker="NK1 Index")

Active futures price series

from bbg_fetch import fetch_active_futures

# Front and second month continuous series
front, second = fetch_active_futures(generic_ticker='ES1 Index')

# Start from second generic (e.g., for roll analysis)
gen2, gen3 = fetch_active_futures(generic_ticker='ES1 Index', first_gen=2)

# Custom retry budget (default: 3 attempts)
front, second = fetch_active_futures(generic_ticker='ES1 Index', max_attempts=5)

Futures ticker utilities

from bbg_fetch import instrument_to_active_ticker, contract_to_instrument

# ES1 Index → ES
instrument_to_active_ticker('ES1 Index', num=3)   # → 'ES3 Index'
contract_to_instrument('ES1 Index')                 # → 'ES'
contract_to_instrument('TY1 Comdty')                # → 'TY'

Bond analytics by ISIN

from bbg_fetch import fetch_bonds_info

bond_data = fetch_bonds_info(
    isins=['US03522AAJ97', 'US126650CZ11'],
    fields=['id_bb', 'name', 'security_des', 'crncy', 'amt_outstanding',
            'px_last', 'yas_bond_yld', 'yas_oas_sprd', 'yas_mod_dur']
)

# With historical override
bond_hist = fetch_bonds_info(
    isins=['US03522AAJ97'],
    fields=['px_last', 'yas_bond_yld'],
    END_DATE_OVERRIDE='20231231'
)

CDS spreads

from bbg_fetch import fetch_cds_info

cds = fetch_cds_info(
    equity_tickers=['ABI BB Equity', 'CVS US Equity', 'JPM US Equity'],
    field='cds_spread_ticker_5y'
)

Bond ISIN → issuer equity ISIN mapping

from bbg_fetch import fetch_issuer_isins_from_bond_isins

# Map bond ISINs to their issuer's equity ISIN
issuer_map = fetch_issuer_isins_from_bond_isins(
    bond_isins=['XS3034073836', 'USY0616GAA14', 'XS3023923314']
)
# Returns: pd.Series with bond ISIN as index, issuer equity ISIN as values

Dividend history and yields

from bbg_fetch import fetch_dividend_history, fetch_div_yields

# Full dividend history
divs = fetch_dividend_history(ticker='AAPL US Equity')
# Columns: declared_date, ex_date, record_date, payable_date,
#          dividend_amount, dividend_frequency, dividend_type

# Trailing 1-year dividend yield for multiple tickers
_, _, div_yields_1y = fetch_div_yields(
    tickers=['AHYG SP Equity', 'TIP US Equity'],
    dividend_types=('Income', 'Distribution')
)

# With renaming
_, _, div_yields_1y = fetch_div_yields(
    tickers={'TIP US Equity': 'TIPS', 'SDHA LN Equity': 'Asia HY'}
)

Index members and weights

from bbg_fetch import fetch_index_members_weights, fetch_bonds_info

# Index with weights (INDX_MWEIGHT)
members = fetch_index_members_weights('SPCPGN Index')

# Index members only (some indices don't have weights)
members = fetch_index_members_weights('H04064US Index', field='INDX_MEMBERS')

# Historical members
members_hist = fetch_index_members_weights(
    'I31415US Index', END_DATE_OVERRIDE='20200101'
)

# Chain: get index members → fetch bond analytics
members = fetch_index_members_weights('LUACTRUU Index')
bond_data = fetch_bonds_info(
    isins=members.index.to_list(),
    fields=['name', 'px_last', 'yas_bond_yld', 'yas_mod_dur', 'bb_composite']
)

ISIN to Bloomberg ticker resolution

from bbg_fetch import fetch_tickers_from_isins

# Convert ISINs to Bloomberg composite tickers
tickers = fetch_tickers_from_isins(isins=['US88160R1014', 'IL0065100930'])
# Returns: ['TSLA US Equity', ...] (with primary exchange)

Direct BDP / BDH / BDS

For ad-hoc queries not covered by the high-level functions:

from bbg_fetch import bdp, bdh, bds

# Reference data (BDP)
ref = bdp('AAPL US Equity', ['Security_Name', 'GICS_Sector_Name', 'PX_LAST'])

# Historical data with adjustments (BDH)
hist = bdh('SPX Index', 'PX_LAST', '2024-01-01', '2024-12-31',
           CshAdjNormal=True, CshAdjAbnormal=True, CapChg=True)

# Bulk data — option chains (BDS)
chain = bds('TSLA US Equity', 'CHAIN_TICKERS',
            CHAIN_PUT_CALL_TYPE_OVRD='PUT', CHAIN_POINTS_OVRD=1000)

# Yield curve construction
yc_members = bds("YCGT0025 Index", "INDX_MEMBERS")
yc_data = bdp(yc_members.member_ticker_and_exchange_code.tolist(),
              ['YLD_YTM_ASK', 'SECURITY NAME', 'MATURITY'])

# Explicitly stop the shared session (also runs at interpreter exit via atexit)
from bbg_fetch import disconnect
disconnect()

Function reference

Price data

Fundamentals

Derivatives

Fixed income

Index and resolution

Futures utilities

Low-level blpapi wrappers

Predefined field mappings

FX currencies

from bbg_fetch import FX_DICT
# 19 major pairs: EUR, GBP, CHF, CAD, JPY, AUD, NZD, MXN, HKD, SEK,
#                 PLN, KRW, TRY, SGD, ZAR, CNY, INR, TWD, NOK

Implied volatility fields

All mappings are importable directly from bbg_fetch.

Configuration

Date defaults

from bbg_fetch import DEFAULT_START_DATE, VOLS_START_DATE
# DEFAULT_START_DATE = pd.Timestamp('01Jan1959')   # Historical data
# VOLS_START_DATE    = pd.Timestamp('03Jan2005')   # Volatility data

Corporate action adjustments

Most price functions support Bloomberg's adjustment flags:

Testing

Terminal-free automated tests live in tests/test_*.py and are the CI lane. The live adjusted-price pytest module lives in src/bbg_fetch/tests/bbg_adj_price_vs_tri_test.py; it requires an active Bloomberg Terminal and is invoked explicitly from a source checkout.

Component development diagnostics are source-only runners under src/bbg_fetch/run_local/. They use implicit namespace-package discovery, so the folder contains no __init__.py and is excluded from wheels and source distributions.

from bbg_fetch.run_local.core_run import Locals, run_local

run_local(local=Locals.FIELD_TIMESERIES_PER_TICKERS)
run_local(local=Locals.IMPLIED_VOL_TIME_SERIES)
run_local(local=Locals.CONTRACT_TABLE)
run_local(local=Locals.BOND_INFO)
run_local(local=Locals.DIVIDEND)
run_local(local=Locals.BOND_MEMBERS)

Available core diagnostics: FIELD_TIMESERIES_PER_TICKERS, FIELDS_TIMESERIES_PER_TICKER, FUNDAMENTALS, ACTIVE_FUTURES, CONTRACT_TABLE, IMPLIED_VOL_TIME_SERIES, BOND_INFO, LAST_PRICES, CDS_INFO, BALANCE_DATA, TICKERS_FROM_ISIN, DIVIDEND, BOND_MEMBERS, INDEX_MEMBERS, OPTION_CHAIN, YIELD_CURVE, CHECK, MEMBERS, FORWARD.

Package structure

src/
    bbg_fetch/
        __init__.py       # Public API
        _blp_api.py       # Direct blpapi shim (bdp, bdh, bds)
        core.py           # High-level fetch functions
        option_chain.py   # Option-chain fetching and parity recovery
        run_local/        # Source-only development runners; implicit namespace
            core_run.py
            adj_price_vs_tri_run.py
        tests/
            bbg_adj_price_vs_tri_test.py # Live adjusted-price pytest
tests/                    # Terminal-free CI tests
examples/                 # Authoritative runnable examples

Troubleshooting

"No module named blpapi"

Install from Bloomberg's package index — see Installation above.

"UnboundLocalError: cannot access local variable 'toPy'"

The C++ DLLs bundled with blpapi failed to load. Reinstall with pip uninstall blpapi -y, then install again from Bloomberg's official package index so the wheel matches your Python version.

Corporate proxy blocks Bloomberg's pip index

Download the .whl file manually from https://blpapi.bloomberg.com/repository/releases/python/simple/blpapi/ via browser and install locally with pip install /path/to/blpapi-*.whl.

Empty DataFrames returned

Ensure the Bloomberg Terminal is running (blpapi connects to localhost:8194). Verify field names using Bloomberg's FLDS function and instrument formatting (e.g., "AAPL US Equity", "ES1 Index", "EURUSD Curncy"). Some indices support INDX_MWEIGHT (with weights) while others only support INDX_MEMBERS — use the field parameter in fetch_index_members_weights() accordingly.

"No module named pip" in venv

Bootstrap pip first: python -m ensurepip --upgrade, then install.

PowerShell path errors

Use .\ prefix for relative paths: .\.venv\Scripts\python.exe, not .venv\Scripts\python.exe.

Changelog

See the changelog for release history and migration notes.

Ecosystem

This package is part of Artur Sepp's open-source Python stack for quantitative finance. The maintainer profile is the canonical ten-package catalogue.

bbg-fetch is a standalone data-access package. option-chain-analytics can use it through an optional Bloomberg provider; research data fetched here can also flow into qis, but neither workflow creates a runtime dependency for bbg-fetch.

Feedback & contributing

• Bug: open the bug-report form with the package/Python versions, platform, minimal request shape, expected result, and redacted actual result. Never attach licensed Bloomberg responses or credentials.
• Feature: open the feature-request form with the field, provider, or normalisation workflow that is missing, your current workaround, and the smallest useful API.
• Contribution: read CONTRIBUTING.md, then browse good first issue or help wanted work.

Citation

A machine-readable citation is available in CITATION.cff.

@software{bloombergfetch,
  author = {Sepp, Artur},
  title = {{BloombergFetch}: A Python Package for Bloomberg Terminal Data Access},
  year = {2026},
  publisher = {GitHub},
  url = {https://github.com/ArturSepp/BloombergFetch},
  version = {3.2.0}
}

License

MIT. See LICENSE.txt.