brvmpy 0.1.0

Scrape financial data from BRVM (Bourse Régionale des Valeurs Mobilières)

BRVMpy 🇨🇮📈

Scrape financial data from BRVM (Bourse Régionale des Valeurs Mobilières) with ease!

BRVMpy is a Python package that scrapes real-time financial data from the BRVM website and returns clean Pandas DataFrames ready for analysis.

---

🌍 About BRVM

The BRVM (Bourse Régionale des Valeurs Mobilières) is the regional stock exchange serving 8 West African countries:

• 🇧🇯 Benin
• 🇧🇫 Burkina Faso
• 🇨🇮 Côte d'Ivoire
• 🇬🇼 Guinea-Bissau
• 🇲🇱 Mali
• 🇳🇪 Niger
• 🇸🇳 Senegal
• 🇹🇬 Togo

Website: https://www.brvm.org

---

✨ Features

• 📊 Actions (Stocks): Get real-time stock prices, volumes, and changes
• 💰 Obligations (Bonds): Scrape bond market data
• 📈 Indices: Fetch market indices (BRVM 10, BRVM Composite, etc.)
• 📉 Volumes: Get trading volume data
• 🐼 Pandas Ready: All data returned as clean DataFrames
• 🚀 Easy to Use: Simple, intuitive API
• 🔄 Auto-Updated: Always scrapes the latest data from BRVM website
• 🤖 Selenium Powered: Reliable web scraping with headless Chrome

---

📦 Installation

pip install brvmpy

Requirements:

• Python 3.8+
• Chrome browser (for Selenium)

---

🚀 Quick Start

Get Stock Market Data

import brvmpy

# Get all stocks (actions)
stocks = brvmpy.get('actions')
print(stocks.head())

Output:

  SYMBOL                NAME  VOLUME  PREVIOUS_PRICE  OPENING_PRICE  CLOSING_PRICE  CHANGE_PERCENT UPDATE_DATE              ID
0   BOAB   Bank of Africa      5420           6750           6800           6850            1.48  2025-12-04  BOAB-2025-12-04
1   SGBC   Société Générale    2130           8500           8500           8600            1.18  2025-12-04  SGBC-2025-12-04
...

Get Market Indices

# Get market indices
indices = brvmpy.get('indices')
print(indices)

Output:

      INDEX_NAME     VALUE  CHANGE  CHANGE_PERCENT UPDATE_DATE                     ID
0  BRVM Composite  210.45    2.34            1.12  2025-12-04  BRVM_Composite-2025-12-04
1       BRVM 10   165.78    1.89            1.15  2025-12-04       BRVM_10-2025-12-04
...

Get All Data at Once

# Get everything in one call
all_data = brvmpy.get_all()

print(f"Stocks: {len(all_data['actions'])}")
print(f"Bonds: {len(all_data['obligations'])}")
print(f"Indices: {len(all_data['indices'])}")
print(f"Volumes: {len(all_data['volumes'])}")

---

📖 API Reference

get(data_type)

Main entry point for scraping BRVM data.

Parameters:

• data_type (str): Type of data to scrape
  • 'actions': Stock market data
  • 'obligations': Bonds data
  • 'indices': Market indices
  • 'volumes': Trading volumes

Returns:

• pandas.DataFrame: Scraped and cleaned data

Example:

import brvmpy

# Get stocks
stocks = brvmpy.get('actions')

# Get bonds
bonds = brvmpy.get('obligations')

# Get indices
indices = brvmpy.get('indices')

# Get volumes
volumes = brvmpy.get('volumes')

---

get_all()

Get all data types in a single call.

Returns:

• dict: Dictionary with keys 'actions', 'obligations', 'indices', 'volumes'

Example:

data = brvmpy.get_all()
stocks_df = data['actions']
indices_df = data['indices']

---

Direct Functions

You can also import and use the scraping functions directly:

from brvmpy import get_actions, get_obligations, get_indices, get_volumes

# Same as brvmpy.get('actions')
stocks = get_actions()

# Same as brvmpy.get('indices')
indices = get_indices()

---

📊 Data Structure

Actions (Stocks)

Column	Type	Description
SYMBOL	str	Stock ticker symbol
NAME	str	Company name
VOLUME	float	Trading volume
PREVIOUS_PRICE	float	Previous closing price (FCFA)
OPENING_PRICE	float	Opening price (FCFA)
CLOSING_PRICE	float	Current/closing price (FCFA)
CHANGE_PERCENT	float	Percentage change
UPDATE_DATE	str	Date of data extraction (YYYY-MM-DD)
ID	str	Unique identifier (SYMBOL-DATE)

Indices

Column	Type	Description
INDEX_NAME	str	Name of the index
VALUE	float	Current index value
CHANGE	float	Point change
CHANGE_PERCENT	float	Percentage change
UPDATE_DATE	str	Date of extraction
ID	str	Unique identifier

Volumes

Column	Type	Description
SYMBOL	str	Stock symbol
NAME	str	Company name
VOLUME	float	Trading volume
VALUE	float	Total value traded (FCFA)
TRANSACTIONS	float	Number of transactions
UPDATE_DATE	str	Date of extraction
ID	str	Unique identifier

---

🎯 Use Cases

Financial Analysis

import brvmpy
import pandas as pd

# Get stocks
stocks = brvmpy.get('actions')

# Find top gainers
top_gainers = stocks.nlargest(5, 'CHANGE_PERCENT')
print("📈 Top 5 Gainers:")
print(top_gainers[['SYMBOL', 'NAME', 'CHANGE_PERCENT']])

# Find most traded
most_traded = stocks.nlargest(5, 'VOLUME')
print("\n💹 Most Traded:")
print(most_traded[['SYMBOL', 'NAME', 'VOLUME']])

Data Export

import brvmpy

# Scrape data
stocks = brvmpy.get('actions')

# Export to CSV
stocks.to_csv('brvm_stocks.csv', index=False)

# Export to Excel
stocks.to_excel('brvm_stocks.xlsx', index=False)

# Export to JSON
stocks.to_json('brvm_stocks.json', orient='records')

Database Integration

import brvmpy
from sqlalchemy import create_engine

# Get data
stocks = brvmpy.get('actions')

# Save to database
engine = create_engine('postgresql://user:pass@localhost:5432/finance')
stocks.to_sql('brvm_stocks', engine, if_exists='append', index=False)

Automated Monitoring

import brvmpy
import schedule
import time

def monitor_brvm():
    """Monitor BRVM stocks every hour"""
    stocks = brvmpy.get('actions')
    
    # Check for significant changes
    big_movers = stocks[abs(stocks['CHANGE_PERCENT']) > 5]
    
    if not big_movers.empty:
        print(f"🚨 Alert: {len(big_movers)} stocks moved >5%")
        print(big_movers[['SYMBOL', 'NAME', 'CHANGE_PERCENT']])

# Schedule monitoring
schedule.every().hour.do(monitor_brvm)

while True:
    schedule.run_pending()
    time.sleep(60)

---

🛠️ Advanced Usage

Custom Scraping

If you need more control, use the BRVMScraper class directly:

from brvmpy.scraper import BRVMScraper

with BRVMScraper() as scraper:
    # Load custom page
    scraper.load_page("https://www.brvm.org/custom-page")
    
    # Extract table with custom selector
    data = scraper.extract_table("div.custom-table tbody tr")
    
    # Process data
    print(f"Found {len(data)} rows")

---

🔧 Requirements

• Python: 3.8 or higher
• Chrome: Latest version (auto-downloaded by webdriver-manager)
• Dependencies:
  • selenium>=4.15.0
  • pandas>=2.0.0
  • webdriver-manager>=4.0.0

---

🐛 Troubleshooting

Chrome/ChromeDriver Issues

If you encounter Chrome driver issues:

# The package automatically manages ChromeDriver
# If issues persist, update Chrome browser to latest version

Timeout Errors

If scraping times out:

# The scraper waits 5 seconds by default
# For slow connections, modify load_page timeout in custom scraping

No Data Returned

If empty DataFrames are returned:

• Check your internet connection
• Verify BRVM website is accessible: https://www.brvm.org
• The website structure may have changed (open an issue on GitHub)

---

📝 Notes

• Data Source: All data is scraped from https://www.brvm.org
• Real-time: Data is as current as the BRVM website
• No Official API: BRVM doesn't provide an official API, so web scraping is used
• Rate Limiting: Be respectful - don't spam requests
• Disclaimer: This is an unofficial package. Use at your own risk.

---

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

👨‍💻 Author

Idriss Badolivier

• Email: [e-mail]
• GitHub: @idrissbado

---

🙏 Acknowledgments

• BRVM for providing financial data
• The Selenium project for web scraping capabilities
• The Pandas project for data manipulation

---

📈 Package Status

• Version: 0.1.0
• Status: Beta
• PyPI: https://pypi.org/project/brvmpy/
• GitHub: https://github.com/idrissbado/BRVMpy

---

🌟 Star History

If you find this package useful, please consider giving it a star on GitHub! ⭐

---

Happy Scraping! 🚀📊