Skip to main content

Changelog

All notable changes to the Ghana API documentation and implementation will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

📈 [0.4.0] - 2025-09-24 - Stock Market Data Integration

Added​

  • Real-time Ghana Stock Exchange (GSE) Data Integration

    • Live data integration with external GSE API (https://dev.kwayisi.org/apis/gse)
    • 7 comprehensive REST endpoints for stock market operations
    • Real-time stock prices, market data, and trading information
    • All 30+ GSE-listed companies with detailed company profiles
    • Sector performance analysis across 13+ sectors (Financials, Basic Materials, Industrial, etc.)
    • Market summary with GSE Composite index and market statistics
    • Advanced search and filtering capabilities (price range, sector, volume, market cap)
    • Company information including address, contact details, financial metrics
    • Performance-optimized caching with 5-minute TTL during market hours
    • Scheduled cache updates every 5 minutes during GSE trading hours
    • Market hours detection (Monday-Friday, 10:00 AM - 3:00 PM Ghana Time)
    • Comprehensive error handling with retry logic and exponential backoff
    • HTTP client integration with timeout and connection management

  • GSE API Provider Architecture

    • Robust external API integration with automatic retries (3 attempts)
    • Rate limiting protection and 429 error handling
    • Data transformation and mapping from external GSE format
    • Market status calculation and timezone handling for Africa/Accra
    • Estimated financial metrics (PE ratio, dividend yield) when not available
    • Company profile enrichment with detailed business information
    • Stock status determination (OPEN/CLOSED based on trading volume)

  • Enhanced Testing & Documentation

    • Complete unit test coverage for service and controller layers (19 tests)
    • Integration tests for real GSE API connectivity
    • Mock provider implementation for reliable testing
    • Comprehensive API documentation with 400+ line stock-market.md guide
    • Swagger/OpenAPI integration with detailed endpoint documentation
    • Real-world examples with actual GSE stock symbols (ACCESS, GCB, etc.)
    • Performance testing and error scenario coverage

  • API Endpoints Added

    • GET /stock-market/search - Advanced stock search with filtering
    • GET /stock-market/stock/{symbol} - Individual stock details
    • GET /stock-market/market-summary - Market overview and indices
    • GET /stock-market/sectors - Available sector list
    • GET /stock-market/sectors/{sector} - Stocks by sector
    • GET /stock-market/sector-performance - Sector analytics
    • GET /stock-market/all - Complete stock listing

Changed​

  • Documentation Updates

    • Homepage now showcases 30+ API endpoints across 6 core services
    • Updated intro.md with stock market examples and real-time data features
    • Enhanced API overview with live GSE data source attribution
    • Added stock market section to quick start guide
    • Updated sidebars navigation with stock market documentation

  • Architecture Improvements

    • HttpModule integration for external API calls
    • Enhanced caching strategy with separate cache keys for different data types
    • Improved error handling with service-specific exception handling
    • TypeScript interface updates for market indices and status

Fixed​

  • Interface compatibility issues between mock and real API providers
  • Market status calculation for Ghana timezone
  • Data type handling for null/undefined financial metrics
  • Test suite compatibility with new provider architecture
🏦 [0.3.0] - 2025-09-24 - Banking & ATM Locator

Added​

  • Banking & ATM Locator Services

    • Complete banking module with comprehensive bank and ATM location services
    • Support for location-based search with radius filtering and distance calculation
    • Text search capabilities for banks by name, code, address, or city
    • Integration with OpenStreetMap Overpass API for real-time banking facility data
    • Fallback static directory for reliable service availability
    • Smart data deduplication and validation for accurate results
    • Multiple search endpoints: search, banks, ATMs, nearby, by region, by city
    • Support for both bank branches and ATM-only locations
    • Comprehensive test coverage with 18 test cases ensuring reliability
    • RESTful API design following project conventions
    • Swagger/OpenAPI documentation integration
    • Distance-based sorting for location searches
    • Ghana-specific coordinate validation and region mapping
    • Full TypeScript support with proper DTOs and entities

  • Enhanced API Documentation

    • Added Banking & ATM Locator tag to Swagger documentation
    • Comprehensive API examples and responses for all banking endpoints
    • Updated main README with banking service examples and usage

  • Version Updates

    • Updated backend version to 0.3.0
    • Updated frontend version to 0.3.0
    • Updated docs version to 0.3.0
    • Updated version badges across all documentation

Technical Implementation​

  • Banking Module Architecture

    • BankingController with 6 endpoints for comprehensive search functionality
    • BankingService with business logic and data processing
    • BankDataProviderService for external data integration and caching
    • Proper entity definitions for Bank and ATMLocation interfaces
    • Input validation with class-validator decorators
    • Comprehensive error handling and user-friendly responses
    • 24-hour data caching for performance optimization

  • Testing & Quality Assurance

    • Complete test coverage for banking controller and service
    • All 137 tests passing including new banking functionality
    • ESLint compliance across all new code
    • TypeScript strict mode compatibility
🧪 [0.2.3] - 2025-09-23 - Comprehensive Test Suite & Bug Fixes

Added​

  • Comprehensive Test Coverage

    • Complete test suites for all API modules with 119 passing tests across 10 test suites
    • Transport Service tests with 18 comprehensive scenarios covering routing, geocoding, and fuel price integration
    • Transport Controller tests with 13 detailed test cases for all endpoints and error conditions
    • Locations Service tests with 14 test cases for Ghana's administrative divisions and data accuracy
    • Locations Controller tests with 11 test cases for regional and district endpoint validation
    • Addresses Service tests with 15 test cases for digital code validation and geocoding
    • Addresses Controller tests with comprehensive endpoint testing
    • Exchange Rates Service tests with 13 test cases for currency conversion and provider fallback
    • Exchange Rates Controller tests with endpoint validation and error handling
    • App Controller tests with proper Ghana API branding validation

  • Enhanced Test Infrastructure

    • Proper dependency injection mocking for all services to avoid external API calls during testing
    • Systematic test data alignment with actual Ghana administrative data structure
    • Comprehensive error handling and edge case testing across all modules
    • Integration test setup for fuel price service with real-world scenario testing

  • Data Accuracy Improvements

    • Fixed Ghana region code mappings (ASH → ASR for Ashanti Region)
    • Corrected district naming conventions to match actual administrative data
    • Updated test expectations to align with real Ghana geographical data
    • Enhanced digital code extraction for Ghana postal addresses

Fixed​

  • Critical Exchange Rates Caching Bug

    • Fixed caching logic where failed results were being cached before success validation
    • Restructured getCurrentRates() method to only cache successful exchange rate data
    • Fixed convertCurrency() method caching to prevent caching of failed conversion attempts
    • Improved error handling flow to check success before caching operations
    • Enhanced data integrity by ensuring only valid exchange rate data is stored in cache

  • Test Suite Stability Issues

    • Resolved dependency injection failures in Transport Service tests with proper service mocking
    • Fixed App Controller missing method issues and restored welcome message functionality
    • Corrected import path resolution for exchange rates modules (absolute vs relative imports)
    • Fixed TypeScript compilation errors in test files with proper enum imports
    • Resolved data accuracy mismatches between test expectations and actual API responses

  • Build and Compilation Issues

    • Fixed missing RouteProfile imports in transport controller test files
    • Corrected string literals to use proper enum values for route profiles
    • Resolved module resolution issues across test files
    • Fixed TypeScript strict typing issues in test implementations

Enhanced​

  • Test Quality & Coverage

    • Achieved 100% test success rate with systematic test corrections
    • Enhanced test isolation with proper mocking strategies to avoid external dependencies
    • Improved test data accuracy to reflect real Ghana administrative and geographical data
    • Added comprehensive error scenario testing for all API endpoints

  • Code Quality & Reliability

    • Improved error handling patterns across exchange rates service
    • Enhanced caching logic to ensure data integrity and prevent corruption
    • Better separation of concerns in test architecture with proper dependency injection
    • Systematic code review and bug fixing across all modules

Technical Implementation​

  • Test Architecture Improvements

    • Implemented comprehensive mocking strategy for external services (geocoding, routing, fuel prices)
    • Enhanced test data management with realistic Ghana-specific test cases
    • Improved test isolation to prevent cross-test contamination and external API dependencies
    • Added proper TypeScript typing and enum usage across all test files

  • Bug Resolution Process

    • Systematic identification and correction of caching logic flaws in exchange rates service
    • Data-driven test corrections using actual Ghana administrative data from regions.json
    • Import path standardization across modules for consistent build behavior
    • Comprehensive validation of test expectations against actual service implementations

  • Performance & Reliability

    • Optimized test execution time by eliminating external API calls during testing
    • Enhanced cache integrity in exchange rates service to prevent data corruption
    • Improved error propagation and handling across all service layers
    • Better resource management in test environment with proper cleanup procedures
⛽ [0.2.2] - 2025-09-23 - Enhanced Fuel Price API with Multiple Sources

Added​

  • Multiple Fuel Price Data Sources

    • Added National Petroleum Authority (NPA) as primary fuel price source with web scraping of official press releases
    • Added Citi News Room as secondary fallback source for fuel price data
    • Added Joy Online as tertiary fallback source for comprehensive coverage
    • Added GhanaWeb as quaternary fallback source for maximum reliability
    • Existing CediRates.com integration moved to secondary priority position

  • Improved Fuel Price Accuracy & Reliability

    • Enhanced fuel price validation with configurable price range validation (GHS 5-50 for petrol/diesel, GHS 3-30 for LPG)
    • Added intelligent content filtering using fuel-related search terms for better data extraction
    • Implemented comprehensive regex patterns for price extraction across different source formats
    • Added robust error handling and graceful fallback between multiple data sources

  • Smart Caching & Performance

    • Enhanced cache TTL calculation to expire fuel prices at 11:59 PM daily for fresh morning data
    • Implemented shorter cache TTL (1 hour) for failed requests to allow retry without overwhelming sources
    • Added detailed logging for fuel price source success/failure tracking and debugging

Enhanced​

  • Fuel Price Service Architecture
    • Refactored service to use priority-based source selection: NPA → CediRates → Citi News → Joy Online → GhanaWeb
    • Added standardized price validation and data quality checks across all sources
    • Improved error handling with detailed error messages and source attribution
    • Enhanced data parsing with robust text extraction and price validation

Technical Implementation​

  • Source Integration

    • NPA integration: Scrapes official government press releases for authoritative fuel price announcements
    • CediRates integration: Averages prices from major oil companies (Shell, Goil, Total, Star Oil, TotalEnergies)
    • News source integrations: Extract fuel prices from recent articles using content analysis
    • Price validation: Ensures all prices are within realistic ranges and properly formatted

  • Data Quality & Validation

    • Added isValidPrice() method for individual fuel type validation
    • Enhanced isValidFuelPriceData() method for comprehensive data validation
    • Added containsFuelPriceTerms() for intelligent content filtering
    • Implemented consistent price rounding to 2 decimal places across all sources
📋 [0.2.1] - 2025-09-06 - Validation Workflows & Release Management

Added​

  • Comprehensive Validation Workflows Documentation

    • Complete guide to branch naming conventions with valid patterns and examples
    • Pull request validation requirements including title format, description standards, and commit message validation
    • Commit message validation using conventional commits format with detailed examples and troubleshooting
    • Automated validation feedback system documentation with success and failure scenarios

  • Release Management Documentation

    • Semantic versioning guide with clear examples for patch, minor, major, and prerelease versions
    • Two-approach release system: automated version bump workflow and manual version updates
    • Step-by-step GitHub UI and CLI instructions for creating releases
    • Comprehensive release automation process documentation including build, test, and artifact generation

  • Quick Reference Guide for Contributors

    • Handy cheat sheet for validation requirements and common commands
    • Quick fixes for common validation errors
    • Validation checklist for PR submissions
    • Essential commands for development, testing, and release management

  • Enhanced Contributing Documentation

    • Updated project structure to include GitHub workflows
    • Added quality standards section highlighting validation workflows
    • Integrated validation and release management into contribution workflow
    • Added proper cross-references between documentation sections

Technical Implementation​

  • GitHub Actions Workflow Fixes

    • Fixed branch name detection for pull request events using github.head_ref instead of github.ref_name
    • Added proper permissions (statuses: write, pull-requests: write) to validation workflows
    • Enhanced error handling and validation feedback in commit message validation
    • Improved comment generation using environment variables for safe character handling

  • Documentation Infrastructure

    • Updated Docusaurus sidebar configuration to include new documentation pages
    • Added proper anchor links and cross-references throughout documentation
    • Implemented consistent documentation structure following existing patterns
    • Validated documentation build process and fixed broken links

Fixed​

  • Workflow Issues

    • Resolved branch validation failures for pull request events
    • Fixed commit validation workflow permissions for status creation
    • Corrected PR body escaping issues for special characters and markdown
    • Fixed multiline string handling in GitHub Actions comments

  • Documentation Issues

    • Fixed broken anchor links in contributing documentation
    • Corrected table formatting inconsistencies across documentation pages
    • Resolved Docusaurus build warnings and validation errors

Documentation Structure​

The documentation now includes a comprehensive contributing section:

Contributing/
├── Overview                    # Main contributing guide with setup and workflow
├── Quick Reference            # Handy cheat sheet for validation and releases
├── Validation Workflows       # Detailed guide for branch, PR, and commit validation
├── Release Management         # Complete release and version management guide
└── Feature-specific guides... # Existing feature contribution documentation
🚀 [0.2.0] - 2025-08-28 - Transport & Logistics API

Added​

  • Transport & Logistics API

    • Transport stops lookup (GET /transport/stops) - Get bus stops, stations, and transport hubs by city
    • Nearby transport services (GET /transport/nearby-stops) - Find transport stops within specified radius
    • Route calculation (GET /transport/route-calculation) - Optimal routing between locations with multiple transport modes
    • Route directions (GET /transport/directions) - Detailed turn-by-turn navigation with geocoding support
    • Travel cost estimation (GET /transport/travel-cost) - Fuel costs and fare calculations for different transport modes
    • Fuel prices (GET /transport/fuel-prices) - Current petrol, diesel, and LPG prices from official Ghana sources

  • Enhanced Geographic Coverage

    • Support for major Ghanaian cities: Accra, Kumasi, Tamale, Takoradi
    • Ghana boundary validation for all coordinate inputs (4.5°N to 11.5°N, 3.5°W to 1.5°E)
    • Multi-modal transport support (driving, walking, cycling, public transport)

  • Advanced Routing Features

    • Multiple provider support with automatic failover (OpenRouteService, HERE Maps, GraphHopper)
    • Geocoding services integration (Nominatim, Overpass API)
    • Real-time fuel price integration from National Petroleum Authority
    • Intelligent caching for performance optimization

  • Comprehensive Documentation

    • Complete transport API documentation with examples
    • Contributing guide for transport features
    • Technical architecture documentation
    • Performance requirements and best practices

Technical Implementation​

  • Multi-Provider Architecture

    • Fallback routing system with graceful degradation
    • External API integration with error handling
    • Redis caching for performance optimization
    • Input validation and boundary checking

  • Data Sources Integration

    • OpenStreetMap and Overpass API for transport stops
    • GTFS feeds for public transport data
    • National Petroleum Authority for fuel prices
    • Multiple routing engines for reliability

Documentation Enhancements​

  • Updated API overview with transport features
  • Enhanced quick start guide with transport examples
  • Updated implementation status tracking
  • Comprehensive contributing guidelines for transport module
🎉 [0.1.0] - 2025-08-18 - Initial Release - Core API Services

Added​

  • Address Services API

    • Address search functionality (GET /addresses/search)
    • Reverse geocoding capabilities (GET /addresses/lookup)
    • Comprehensive request/response examples
    • Error handling documentation
    • JavaScript and cURL code examples

  • Exchange Rates API

    • Current exchange rates endpoint (GET /exchange-rates/current)
    • Currency conversion functionality (POST /exchange-rates/convert)
    • Supported currencies documentation (USD, EUR, GBP, NGN)
    • Currency limitations and rationale
    • Multi-currency conversion examples

  • Location Data API

    • Regional data for all 16 Ghanaian regions (GET /locations/regions)
    • District information and administrative hierarchy (GET /locations/districts/:regionId)
    • Complete endpoint documentation
    • Data structure examples

  • API Documentation Platform

    • Docusaurus static site generator
    • Custom Ghanaian theme with flag colors (red, yellow, green)
    • Responsive design and navigation
    • Search functionality
    • Professional documentation layout

  • Implementation Status Documentation

    • Clear status indicators for all API endpoints
    • Implementation status table in overview
    • Status badges (✅ Live, ⏳ Coming Soon) throughout documentation
    • Comprehensive implementation status tracking

Technical Implementation​

  • Backend API Structure

    • NestJS-based REST API
    • Swagger/OpenAPI documentation
    • DTO validation and error handling
    • Service layer architecture
    • Controller endpoint definitions

  • Documentation Features

    • Base URL and endpoint structure documentation
    • HTTP methods and status codes
    • Response format standardization
    • Error handling patterns
    • Usage examples and best practices

Design & Branding​

  • Visual Identity

    • Ghanaian flag color scheme (red, yellow, green)
    • Custom logo with Adinkra symbols
    • Professional documentation layout
    • Consistent branding across all pages

  • User Experience

    • Intuitive navigation structure
    • Clear section organization
    • Mobile-responsive design
    • Fast loading times
    • Accessibility considerations
📊 Version Information

Current Version: 0.2.1​

  • Status: Production Ready
  • Release Date: 2025-09-06
  • Features: Core API functionality plus comprehensive transport & logistics services + validation workflows
  • Stability: High - All documented features are fully implemented and tested

Available Features in 0.2.1​

Address Services​

  • ✅ Address search by keyword
  • ✅ Reverse geocoding from coordinates

Exchange Rates​

  • ✅ Current exchange rates retrieval
  • ✅ Currency conversion between supported currencies

Location Data​

  • ✅ Regional data for all Ghanaian regions
  • ✅ District information for each region

Transport & Logistics​

  • ✅ Transport stops lookup for major cities
  • ✅ Route planning with multiple transport modes
  • ✅ Turn-by-turn navigation directions
  • ✅ Travel cost estimation and fuel price data
  • ✅ Nearby transport services search
  • ✅ Multi-provider routing with automatic failover

Documentation & Development​

  • ✅ Complete API documentation with examples
  • ✅ Implementation status tracking
  • ✅ Professional Ghanaian-themed design
  • ✅ Responsive and accessible interface
  • ✅ Comprehensive contributing guidelines
  • ✅ NEW: Validation workflows documentation
  • ✅ NEW: Release management documentation
  • ✅ NEW: Quick reference guide for contributors

Quality Assurance (NEW)​

  • ✅ Automated branch name validation
  • ✅ Pull request validation workflows
  • ✅ Commit message validation (conventional commits)
  • ✅ Automated release management
  • ✅ Version bump workflows
🤝 Contributing

When contributing to this project, please:

  1. Update this changelog with your changes
  2. Follow the existing format and structure
  3. Include both technical and user-facing changes
  4. Add appropriate version numbers for releases
  5. Document breaking changes clearly
🆘 Support

For questions about changes or to report issues:

  • Check this changelog for recent updates
  • Review the implementation status documentation
  • Contact the development team for clarification