🏦 FinanceGY

FinanceGY is an unofficial Python library for accessing financial data from the Guyana Stock Exchange (GSE). It provides a simple and consistent interface for retrieving information on traded securities, recent trade data, and session details, all programmatically.

Installation

pip install financegy

Quick Start

import financegy

# --------------------------
# Core Data Retrieval
# --------------------------

# Get a list of all traded securities
securities = financegy.get_securities()

# Get active market securities (symbol + company name) from the most recent session page
active_securities = financegy.get_active_securities()

# Get the most recent trading session number
recent_session = financegy.get_recent_session()

# Get all sessions for a selected trading year
year_sessions = get_year_sessions("2020")

# Get trade snapshots for all sessions in a selected year
year_sessions_snapshot = get_year_sessions_snapshot("2020")

# Get the full name of a security by its ticker symbol
security_name = financegy.get_security_by_symbol("DDL")

# Get the most recent trade data for a security
recent_trade = financegy.get_recent_trade("DDL")

# Get the most recent closing/last trade price (same most-recent session)
previous_close = financegy.get_previous_close("DDL")

# Get absolute price change vs previous session close
price_change = financegy.get_price_change("DDL")

# Get percent price change vs previous session close
price_change_percent = financegy.get_price_change_percent("DDL")

# Get all trade data for the most recent year (for the security)
recent_year_trades = financegy.get_security_recent_year("DDL")

# Get all trade years for a selected security
traded_years = financegy.get_traded_years("DDL")

# Get the earliest financial year available for the security
earliest_year = financegy.get_security_earliest_year("DDL")

# Get the latest financial year available for the security
latest_year = financegy.get_security_latest_year("DDL")

# Get the full trade history for a security (all years combined)
full_history = financegy.get_security_full_history("DDL")

# Get trade data for a specific trading session (all securities)
session_trades = financegy.get_session_trades("1136")

# Get the date for a specified trading session.
session_date = financegy.get_session_date("1136")

# Get security's trailing 52-week low and high
low_and_high = financegy.get_52_week_range("DDL")

# Get trade data for a specific security in a session
security_session_trade = financegy.get_security_session_trade("DDL", "1136")

# Search for securities by name or symbol
search_results = financegy.search_securities("DDL")

# Get all trades for a specific year
year_trades = financegy.get_trades_for_year("DDL", "2019")

# Get historical trades within a date range - supports: yyyy / mm/yyyy / dd/mm/yyyy
historical_trades = financegy.get_historical_trades(
    symbol="DDL",
    start_date="01/06/2020",
    end_date="01/2022"
)

# --------------------------
# Analytics / Calculations
# --------------------------

# Get the latest session info (dict returned from most recent trade)
latest_session = financegy.get_latest_session_for_symbol("DDL")

# Average last traded price over a session range (inclusive)
avg_price_range = financegy.get_sessions_average_price("DDL", "1100", "1136")

# Average last traded price over the last N sessions or 1M, 3M, 6M 1Y (ending at latest session)
avg_price_latest = financegy.get_average_price("DDL", "1M")

# Volatility over the last N sessions (weekly log-return volatility + annualized)
volatility = financegy.get_sessions_volatility("DDL", 30)

# Year-to-date high and low traded prices
ytd_high_low = financegy.get_ytd_high_low("DDL")

# Get top market gainers and losers (based on % price change)
movers = financegy.get_movers()

# Get overall market snapshot (Symbol | Name | LTP | Prev Close | Price Change | PC% | YTD High | YTD Low)
market_snapshot = financegy.get_market_snapshot()

# --------------------------
# Portfolio / Position Calculations
# --------------------------

# Calculate the current market value of a position
position_value = financegy.calculate_position_value("DDL", shares=50)

# Calculate unrealized gain or loss for a position
position_return = financegy.calculate_position_return(
    symbol="DDL",
    shares=50,
    purchase_price=250
)

# Calculate percentage return for a position
position_return_percent = financegy.calculate_position_return_percent(
    symbol="DDL",
    shares=50,
    purchase_price=250
)

# Portfolio-level summary
portfolio = [
    {"symbol": "DTC", "shares": 100, "purchase_price": 300},
    {"symbol": "DDL", "shares": 50, "purchase_price": 250},
]

portfolio_summary = financegy.calculate_portfolio_summary(portfolio)

# --------------------------
# Utilities
# --------------------------

# Convert results to a DataFrame
df = financegy.to_dataframe(securities)

# Export to CSV / Excel
financegy.save_to_csv(securities, filename="securities.csv", silent=True)
financegy.save_to_excel(securities, filename="securities.xlsx", silent=True)

# Purge invalid cache files (not from the current week)
financegy.purge_old_cache_files()

# Clear FinanceGY cache directory
financegy.clear_cache(silent=True)

API Reference

Core Data Retrieval

Analytics / Calculation Functions

Portfolio / Position Functions

Utilities

Caching System

FinanceGY includes a lightweight local caching system designed to speed up repeated requests and reduce unnecessary API calls.

Whenever you call a data retrieval function (such as get_securities() or get_recent_trade()), FinanceGY automatically checks whether a cached response already exists for that specific query:

If a valid cache file from the current week (Monday-Sunday) is found, the result is returned instantly from the cache.

If the cache is missing, corrupted, or belongs to a previous week, it is automatically deleted, and fresh data is fetched from the GSE and stored.

Cache validity is determined based on a weekly cycle. At Monday 00:00, all previously stored cache entries are considered expired. Stale cache files are removed automatically when accessed, ensuring the cache remains clean and up to date without requiring manual intervention.

All cache files are stored in a local cache/ directory as small JSON files containing the retrieved data and a timestamp.

You can manually clear all cached data at any time:

import financegy

financegy.clear_cache()

This will delete all cached files and force the next data request to fetch fresh data directly from the source.

You can also choose to only clear invalid cache files (not from the current week).:

import financegy

financegy.purge_old_cache_files()

Note: This will be done automatically if the system ever tries to access a cache file and finds it is stale.*

If you prefer to bypass the cache for a specific call, simply pass use_cache=False to any function. For example:

# Force a fresh fetch from the GSE, ignoring cached data
recent_trade = financegy.get_recent_trade("DDL", use_cache=False)

By default, caching is enabled for all supported functions unless explicitly turned off.

Example Use Case

import financegy

ddl_recent = financegy.get_security_recent("DDL")
print(ddl_recent)