Usage

This page covers all available functions in bdshare with complete examples. For installation instructions, see Installation. For the full API specification, see api.

Dhaka Stock Exchange (DSE)

Live Trading Data 

Get current prices for all instruments or a specific symbol.

from bdshare import get_current_trade_data

# All instruments
df = get_current_trade_data()
print(df.to_string())

from bdshare import get_current_trade_data

# Single instrument (case-insensitive)
df = get_current_trade_data('GP')
print(df.to_string())

Returned columns:

Column	Type	Description
symbol	str	Trading symbol
ltp	float	Last trade price
high	float	Day high
low	float	Day low
close	float	Closing price
ycp	float	Yesterday’s closing price
change	float	Price change from ycp
trade	int	Number of trades
value	float	Total traded value
volume	int	Total traded volume

DSEX Index Data 

Get live DSEX index entries.

from bdshare import get_dsex_data

# All DSEX entries
df = get_dsex_data()
print(df.to_string())

from bdshare import get_dsex_data

# Filter by symbol
df = get_dsex_data('DSEX')
print(df.to_string())

Trading Codes 

Get the full list of currently tradeable symbols.

from bdshare import get_current_trading_code

df = get_current_trading_code()
print(df['symbol'].tolist())

Historical Data 

Get full OHLCV and metadata for a date range. Results are indexed by date, sorted newest-first.

from bdshare import get_hist_data

# All instruments for a date range
df = get_hist_data('2024-01-01', '2024-03-31')
print(df.to_string())

from bdshare import get_hist_data

# Specific instrument
df = get_hist_data('2024-01-01', '2024-03-31', 'ACI')
print(df.to_string())

Returned columns:

Column	Type	Description
date	str	Index — trading date
symbol	str	Trading symbol
ltp	float	Last trade price
high	float	Day high
low	float	Day low
open	float	Opening price
close	float	Closing price
ycp	float	Yesterday’s closing price
trade	int	Number of trades
value	float	Total traded value
volume	int	Total traded volume

Note

Deprecated alias: get_historical_data() still works but emits a DeprecationWarning. Migrate to get_hist_data().

Simplified OHLCV Historical Data 

Returns only open, high, low, close, volume — sorted oldest-first. This format is directly compatible with TA libraries such as ta, pandas-ta, and backtrader.

from bdshare import get_basic_hist_data

# All instruments
df = get_basic_hist_data('2024-01-01', '2024-03-31')
print(df.to_string())

from bdshare import get_basic_hist_data

# Specific instrument
df = get_basic_hist_data('2024-01-01', '2024-03-31', 'GP')
print(df.to_string())

from bdshare import get_basic_hist_data
import datetime as dt

# Rolling 2-year window with date set as the DataFrame index
end   = dt.date.today()
start = end - dt.timedelta(days=2 * 365)
df    = get_basic_hist_data(str(start), str(end), 'GP', index='date')
print(df.to_string())

Note

Deprecated alias: get_basic_historical_data() still works but emits a DeprecationWarning. Migrate to get_basic_hist_data().

Close Price Data 

Returns only closing price and prior close (ycp), indexed by date.

from bdshare import get_close_price_data

df = get_close_price_data('2024-01-01', '2024-03-31', 'ACI')
print(df.to_string())

Last Trade Price (Text File)

Fetches the DSE fixed-width text file for the most recent session.

from bdshare import get_last_trade_price_data

df = get_last_trade_price_data()
print(df.to_string())

Market & Index Summary 

Current Market Summary 

Returns the last 30 days of overall market data including all DSE indices, total volumes, and market capitalisation.

from bdshare import get_market_info

df = get_market_info()
print(df.to_string())

Returned columns: Date, Total Trade, Total Volume, Total Value (mn), Total Market Cap. (mn), DSEX Index, DSES Index, DS30 Index, DGEN Index.

Historical Market Summary 

Fetch extended market statistics between two dates via the DSE search form.

from bdshare import get_market_info_more_data

df = get_market_info_more_data('2024-01-01', '2024-03-31')
print(df.to_string())

from bdshare import get_market_info_more_data

# Set date as the DataFrame index, sorted ascending
df = get_market_info_more_data('2024-01-01', '2024-03-31', index='date')
print(df.to_string())

Market Depth (Order Book)

Returns the live buy and sell order book for a symbol.

from bdshare import get_market_depth_data

df = get_market_depth_data('ACI')
print(df.to_string())

Returned columns: buy_price, buy_volume, sell_price, sell_volume.

P/E Ratios 

Get the latest price-to-earnings ratios for all listed companies.

from bdshare import get_latest_pe

df = get_latest_pe()
print(df.to_string())

Company Profile 

Returns a list of DataFrames containing detailed company information (financials, directors, shareholding, etc.).

from bdshare import get_company_info

tables = get_company_info('GP')
for t in tables:
    print(t.to_string())
    print()

Sector Performance 

Get sector-wise performance across the market.

from bdshare import get_sector_performance

df = get_sector_performance()
print(df.to_string())

Top Gainers & Losers 

from bdshare import get_top_gainers_losers

# Default: top 10
df = get_top_gainers_losers()
print(df.to_string())

from bdshare import get_top_gainers_losers

# Custom limit
df = get_top_gainers_losers(limit=20)
print(df.to_string())

News & Announcements 

Unified News Dispatcher 

get_news() is the recommended entry point. Use news_type to select the category and code to filter by symbol.

news_type	Description
`'all'`	All DSE news items (default)
`'agm'`	AGM / dividend declarations
`'corporate'` \| Corporate announcements
`'psn'`	Price-sensitive news

from bdshare import get_news

# All news
df = get_news(news_type='all')
print(df.to_string())

from bdshare import get_news

# AGM declarations
df = get_news(news_type='agm')
print(df.to_string())

from bdshare import get_news

# Corporate announcements for a specific symbol
df = get_news(news_type='corporate', code='GP')
print(df.to_string())

from bdshare import get_news

# Price-sensitive news
df = get_news(news_type='psn', code='ACI')
print(df.to_string())

AGM News 

from bdshare import get_agm_news

df = get_agm_news()
print(df.to_string())

Returned columns: company, yearEnd, dividend, agmDate, recordDate, venue, time.

All News 

from bdshare import get_all_news

# All news (no filter)
df = get_all_news()
print(df.to_string())

from bdshare import get_all_news

# Filter by symbol
df = get_all_news(code='BEXIMCO')
print(df.to_string())

from bdshare import get_all_news

# Filter by date range and symbol
df = get_all_news('2024-01-01', '2024-03-31', 'GP')
print(df.to_string())

Corporate Announcements 

from bdshare import get_corporate_announcements

df = get_corporate_announcements()
print(df.to_string())

from bdshare import get_corporate_announcements

df = get_corporate_announcements(code='GP')
print(df.to_string())

Price-Sensitive News 

from bdshare import get_price_sensitive_news

df = get_price_sensitive_news()
print(df.to_string())

from bdshare import get_price_sensitive_news

df = get_price_sensitive_news(code='ACI')
print(df.to_string())

Saving Data 

Save any DataFrame to CSV using the built-in Store helper.

from bdshare import get_basic_hist_data, Store
import datetime as dt

end   = dt.date.today()
start = end - dt.timedelta(days=365)

df = get_basic_hist_data(str(start), str(end), 'GP')
Store(df).save()  # saved to current directory as CSV

OOP Client 

The BDShare class wraps all functions with automatic caching and rate limiting (5 calls/second sliding window).

Initialisation 

from bdshare import BDShare

bd = BDShare()                     # caching on by default
bd = BDShare(cache_enabled=False)  # disable caching
bd = BDShare(api_key='your-key')   # premium API key (future use)

Context Manager 

Use as a context manager to ensure the session and cache are cleaned up automatically on exit:

from bdshare import BDShare

with BDShare() as bd:
    df = bd.get_current_trades('GP')
    print(df.to_string())

Method Reference 

All methods accept a use_cache keyword argument (default True). The table below shows each method with its cache TTL.

Market methods

bd.get_market_summary()            # DSEX/DSES/DS30 indices    — 1-min  TTL
bd.get_company_profile('ACI')      # Company profile           — 1-hr   TTL
bd.get_latest_pe_ratios()          # All P/E ratios            — 1-hr   TTL
bd.get_top_movers(limit=10)        # Top gainers/losers        — 5-min  TTL
bd.get_sector_performance()        # Sector breakdown          — 5-min  TTL

Trading methods

bd.get_current_trades()            # All live prices           — 30-sec TTL
bd.get_current_trades('GP')        # Single symbol
bd.get_dsex_index()                # DSEX index entries        — 1-min  TTL
bd.get_trading_codes()             # All tradeable symbols     — 24-hr  TTL
bd.get_historical_data(            # Historical OHLCV          — no TTL (opt-in)
    'GP',
    '2024-01-01',
    '2024-03-31',
    use_cache=True,
)

News methods

bd.get_news(news_type='all')                      # All news   — 5-min TTL
bd.get_news(news_type='corporate', code='GP')
bd.get_news(news_type='psn')

Utility methods

bd.clear_cache()                   # Flush all cached responses
bd.configure(proxy_url='http://proxy:8080')
print(bd.version)                  # e.g. "2.0.0"

Error Handling 

All failures raise BDShareError. Catch it specifically rather than bare Exception so unexpected bugs are never silently swallowed.

from bdshare import get_hist_data, BDShareError

try:
    df = get_hist_data('2024-01-01', '2024-03-31', 'INVALID')
except BDShareError as e:
    print(f"DSE error: {e}")

Common causes of BDShareError:

Symbol not present in the response table
DSE site returned a non-200 status after all retries
Network timeout (default: 10 seconds per request)
Page structure changed on the DSE website — please open an issue

Warning

The library retries up to 3 times with exponential back-off (0.2 s → 0.4 s → 0.8 s) before raising BDShareError. Short-lived DSE outages are handled automatically.

Chittagong Stock Exchange (CSE)

Note

CSE support is currently in development. The functions below are placeholders — they will raise NotImplementedError until the CSE module is released. Track progress on GitHub.

from bdshare import get_cse_current_trade_data

# All CSE instruments
df = get_cse_current_trade_data()
print(df.to_string())

from bdshare import get_cse_current_trade_data

# Specific CSE instrument
df = get_cse_current_trade_data('GP')
print(df.to_string())

Proxy Support 

Route all requests through a proxy server (useful in restricted networks):

from bdshare import BDShare

with BDShare() as bd:
    bd.configure(proxy_url='http://your-proxy-server:8080')
    df = bd.get_current_trades()
    print(df.to_string())

Complete Example: Stock Screener 

The following example fetches live data for all instruments and screens for stocks with a positive change greater than 3 % and volume above a threshold.

from bdshare import get_current_trade_data, BDShareError

try:
    df = get_current_trade_data()
except BDShareError as e:
    print(f"Failed to fetch data: {e}")
    raise SystemExit(1)

# Numeric columns were already cast — no conversion needed
screened = df[
    (df['change'] > 3.0) &
    (df['volume'] > 100_000)
].sort_values('change', ascending=False)

print(screened[['symbol', 'ltp', 'change', 'volume']].to_string())

Complete Example: Portfolio P&L 

from bdshare import BDShare, BDShareError

PORTFOLIO = {
    'GP':      {'qty': 100, 'cost': 450.50},
    'ACI':     {'qty':  50, 'cost': 225.75},
    'BEXIMCO': {'qty': 200, 'cost': 125.25},
}

with BDShare() as bd:
    total_cost = total_value = 0.0

    for symbol, pos in PORTFOLIO.items():
        try:
            row   = bd.get_current_trades(symbol).iloc[0]
            price = row['ltp']
            mv    = pos['qty'] * price
            cost  = pos['qty'] * pos['cost']
            pnl   = mv - cost

            print(f"{symbol:10s}  ltp={price:8.2f}  P&L={pnl:+10.2f}")
            total_cost  += cost
            total_value += mv

        except BDShareError as e:
            print(f"{symbol}: {e}")

    pct = (total_value / total_cost - 1) * 100
    print(f"\nTotal P&L: {total_value - total_cost:+.2f}  ({pct:+.2f}%)")