Quickstart

Get started with the Uganda Securities Exchange API in minutes

Your first API call

This guide walks you through making your first request to retrieve market data from the Uganda Securities Exchange.

1. Set up your project

   Create a new PHP file and include the PortfolioManager class:

   index.php

   <?php
   require_once 'PortfolioManager.php';
   
   // Create an instance of PortfolioManager
   $portfolioManager = new PortfolioManager();
   ?>
   

   Make sure you’ve completed the installation steps before proceeding.

2. Fetch all listed companies

   Use the getAllPortfolioCompanies() method to retrieve all companies listed on the Uganda Securities Exchange:

   index.php

   <?php
   require_once 'PortfolioManager.php';
   
   $portfolioManager = new PortfolioManager();
   
   // Get all portfolio companies
   $allCompanies = $portfolioManager->getAllPortfolioCompanies();
   
   // Output the results
   echo $allCompanies;
   ?>
   

   This returns JSON data with company symbols, prices, and listing URLs.

3. Run your script

   Execute the script using PHP:

   php index.php
   

   You should see JSON output similar to:

   [
     [
       "BOBU",
       "1,250",
       "https://www.use.or.ug/listed/BOBU"
     ],
     [
       "UCL",
       "850",
       "https://www.use.or.ug/listed/UCL"
     ]
     // ... more companies
   ]
   

Working example

Here’s a complete example that demonstrates all four main API methods:

Complete example

<?php
require_once 'PortfolioManager.php';

// Create an instance
$portfolioManager = new PortfolioManager();

// 1. Get all portfolio companies
$allCompanies = $portfolioManager->getAllPortfolioCompanies();
echo "All Companies:\n";
echo $allCompanies . "\n\n";

// 2. Get details for a specific company (e.g., BOBU)
$companyDetails = $portfolioManager->getCompanyDetails('BOBU');
echo "Company Details for BOBU:\n";
echo $companyDetails . "\n\n";

// 3. Get historical data for a company
echo "Historical Data for BOBU:\n";
$portfolioManager->getPortfolioCompanyData('BOBU');
echo "\n\n";

// 4. Get current exchange rates
$exchangeRates = $portfolioManager->getExchangeRateDetails();
echo "Exchange Rates:\n";
echo $exchangeRates . "\n";
?>

Understanding the response

Each method returns JSON-formatted data. Here’s what to expect from each:

getAllPortfolioCompanies()

Returns an array of companies with:

• Company symbol (e.g., “BOBU”)
• Current price
• URL to company details page

getCompanyDetails($companyName)

Returns detailed company information:

{
  "companyName": "BOBU",
  "logoURL": "https://www.use.or.ug/...",
  "isin": "UG0001000201",
  "listingDate": "January 1, 2000",
  "sharesIssued": "1,000,000,000",
  "marketCap": "UGX 1,250,000,000,000",
  "address": "...",
  "phone": "...",
  "email": "...",
  "website": "..."
}

getPortfolioCompanyData($companyName)

Returns historical OHLC data:

{
  "stock": "BOBU",
  "latestSharePrice": "1250",
  "data": [
    {
      "date": "2024-01-15 00:00:00",
      "timestamp": 1705276800000,
      "open": "1250",
      "high": "1275",
      "low": "1240",
      "close": "1250",
      "adjusted_close": "1250",
      "volume": "50000"
    }
    // ... more data points
  ]
}

getExchangeRateDetails()

Returns current UGX exchange rates:

{
  "values": {
    "VALUE/US$": "3,750.00",
    "TODAY'S CHANGE": "+0.25%",
    "1 YEAR CHANGE": "-2.5%",
    "52 WEEK RANGE": "3,650 - 3,850"
  },
  "disclaimer": "...",
  "source": "https://africanfinancials.com/currency/ug-ugx/",
  "execution_time": 1.2345,
  "time in seconds": "1.2345 seconds"
}

Common use cases

Portfolio tracking

Build a portfolio tracker that monitors your holdings

Company lookup

Create a search interface for company information

Market analysis

Analyze historical price trends and patterns

Price alerts

Set up notifications for price movements

Best practices

Rate limiting: Implement delays between requests to avoid overloading the Uganda Securities Exchange servers. Consider caching results for frequently accessed data.

Error handling

Always wrap API calls in try-catch blocks:

try {
    $companies = $portfolioManager->getAllPortfolioCompanies();
    // Process data
} catch (Exception $e) {
    error_log("API Error: " . $e->getMessage());
    // Handle error gracefully
}

Caching results

Cache API responses to reduce load on the exchange website:

// Simple file-based cache example
$cacheFile = 'cache/companies.json';
$cacheTime = 3600; // 1 hour

if (file_exists($cacheFile) && (time() - filemtime($cacheFile) < $cacheTime)) {
    $companies = file_get_contents($cacheFile);
} else {
    $companies = $portfolioManager->getAllPortfolioCompanies();
    file_put_contents($cacheFile, $companies);
}

Input validation

Validate company symbols before making API calls:

function isValidCompanySymbol($symbol) {
    // Only allow alphanumeric characters
    return preg_match('/^[A-Z0-9]+$/', $symbol);
}

$symbol = 'BOBU';
if (isValidCompanySymbol($symbol)) {
    $details = $portfolioManager->getCompanyDetails($symbol);
}

Next steps

API reference

Explore all available methods and parameters

Examples

View more detailed code examples

Web scraping concepts

Learn how the library works under the hood

Legal compliance

Understand usage requirements and restrictions