# Uganda Business Directory Scraper (`crawlerbros/uganda-business-directory-scraper`) Actor

Scrape business listings from yellowpages-uganda.com - Uganda's online business directory. Browse 48 categories (hotels, restaurants, banks, hospitals, IT, and more) or fetch specific profiles by URL, with phone, email, website, address, geo-coordinates and photos.

- **URL**: https://apify.com/crawlerbros/uganda-business-directory-scraper.md
- **Developed by:** [Crawler Bros](https://apify.com/crawlerbros) (community)
- **Categories:** Lead generation, E-commerce, Travel
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $3.00 / 1,000 results

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## Uganda Business Directory Scraper

Scrape **yellowpages-uganda.com** — Uganda's online business directory. Browse any of the site's 48 real categories (hotels, restaurants, banks, hospitals, IT companies, schools, law firms, and more), run a free-text keyword search across every category at once, or fetch specific business profiles by URL, with phone, email, website, social links, address, geo-coordinates, rating, and photos. HTTP-only, no login, no cookies, no proxy required.

### What this actor does

- **Three modes:** browse a category (`byCategory`), free-text search across every category (`search`), or fetch specific listings by URL (`byUrl`)
- **48 categories** — the full set of business categories the site publishes, from Accountants to Universities
- **7 sort orders** — newest, A-Z, Z-A, highest rated, most/fewest reviews, random
- **Rich contact data** — phone, email, website, Facebook/Twitter/Instagram/LinkedIn/YouTube/TikTok links
- **Location data** — full street address, country, and precise latitude/longitude
- **Filters** — minimum/maximum rating, require phone/email/website, keyword match on name or description
- **Empty fields are omitted** — a business record only ever contains the fields that business actually published

### Output per business

- `businessName` — business/listing name
- `businessType` — the business's schema.org type (e.g. `Hotel`, `Restaurant`, `Computer Store`, `Local Business`)
- `category` — primary category name (e.g. `Hotels`)
- `categorySlug` — primary category's URL slug
- `categories[]` — full list of category names, only present when a business is listed under more than one category
- `tags[]` — free-text listing tags the business owner added
- `description` — full business description
- `phone` — published phone number(s), verbatim as listed
- `email` — published email address (only available in `byCategory` / `search` modes — see FAQ)
- `rating` — average visitor rating (0-5), only present when the business has at least one review
- `reviewCount` — number of visitor reviews, when the business has at least one
- `reviews[]` — individual visitor reviews, when present: `author`, `rating`, `text`, `datePublished`
- `website` — business website URL
- `facebookUrl`, `twitterUrl`, `instagramUrl`, `linkedinUrl`, `youtubeUrl`, `tiktokUrl` — social profile links, when published
- `address` — full street address as entered by the business
- `postalCode` — postal/P.O. box code, when published
- `country` — always `Uganda`
- `latitude`, `longitude` — geo-coordinates, when the business has been geocoded
- `mainImageUrl` — primary photo
- `imageUrls[]` — all available photos
- `sourceUrl` — canonical yellowpages-uganda.com listing URL
- `recordType: "business"`, `scrapedAt`

### Input

| Field | Type | Default | Description |
|---|---|---|---|
| `mode` | string | `byCategory` | `byCategory` / `search` / `byUrl` |
| `category` | string | `hotels-uganda` | Category to browse (mode=byCategory) — one of 48 real site categories |
| `searchQuery` | string | – | Free-text keyword to search across every category (mode=search) |
| `sortBy` | string | `newest` | `newest` / `az` / `za` / `high_rating` / `high_review` / `low_review` / `random` — applies to `byCategory` and `search` |
| `startUrls` | array | – | Direct business listing URLs to fetch (mode=byUrl) |
| `maxItems` | int | `30` | Max businesses to return (1-300) |
| `minRating` | number | `0` | Minimum rating (0-5). Unrated businesses always pass |
| `maxRating` | number | `5` | Maximum rating (0-5). Unrated businesses always pass |
| `requirePhone` | boolean | `false` | Only include businesses with a published phone number |
| `requireEmail` | boolean | `false` | Only include businesses with a published email address |
| `requireWebsite` | boolean | `false` | Only include businesses with a published website |
| `containsKeyword` | string | – | Only include businesses whose name/description contains this text |

#### Example: browse hotels, newest first

```json
{
  "mode": "byCategory",
  "category": "hotels-uganda",
  "sortBy": "newest",
  "maxItems": 30
}
```

#### Example: banks with a phone number, A-Z

```json
{
  "mode": "byCategory",
  "category": "banks-uganda",
  "sortBy": "az",
  "maxItems": 50,
  "requirePhone": true
}
```

#### Example: top-rated restaurants only

```json
{
  "mode": "byCategory",
  "category": "restaurants-kampala-uganda",
  "sortBy": "high_rating",
  "minRating": 4,
  "maxItems": 30
}
```

#### Example: search for "hotel" across every category

```json
{
  "mode": "search",
  "searchQuery": "hotel",
  "sortBy": "high_rating",
  "maxItems": 30
}
```

#### Example: fetch specific business profiles by URL

```json
{
  "mode": "byUrl",
  "startUrls": [
    { "url": "https://www.yellowpages-uganda.com/listings/uganda/central-region/kampala/hotels-uganda/kampala-serena-hotel/" }
  ]
}
```

### Use cases

- **Lead generation** — build a contact list of Ugandan businesses by industry, complete with phone/email/website
- **Market research** — analyze the density and geographic spread of a given industry across Uganda
- **Travel & hospitality** — pull hotel and tourism listings with photos and ratings for a travel app or aggregator
- **Local SEO / directory aggregation** — enrich your own local-business directory with Uganda data
- **Due diligence** — verify a Ugandan business's public contact details and web presence before engaging

### FAQ

**What is the data source?**
This actor scrapes the public pages of yellowpages-uganda.com, a WordPress-based business directory for Uganda. It's not affiliated with that site — this is an independent, third-party scraper.

**Why does `email` only appear in `byCategory`/`search` modes?**
yellowpages-uganda.com only renders a business's email address on its category-listing/search-result card, not on the business's own detail page. `byCategory` and `search` modes visit both the listing card and the detail page and merge the data, so email is available there. `byUrl` mode only has the detail page to work with, so email is omitted for that mode — this is a genuine limitation of the source site's page templates, not a bug.

**Are `rating`/`reviewCount`/`reviews[]` available in `byUrl` mode too?**
Yes. `rating` and `reviewCount` are read from the listing card when one was fetched (`byCategory`/`search` modes); when there's no card (`byUrl` mode), the actor falls back to the business detail page's own aggregate rating, which is published whenever the business has at least one review. `reviews[]` (individual reviewer name, rating, text, and date) always comes from the detail page, so it's available in all modes.

**How does the free-text `search` mode differ from `containsKeyword`?**
`mode=search` sends your query to yellowpages-uganda.com's own site-wide search endpoint, so it returns matches across all 48 categories in one run — useful when you don't know (or don't want to restrict to) a business's category. `containsKeyword` is a client-side filter that narrows results *within* whichever mode you're already running (`byCategory`, `search`, or `byUrl`) by matching business name/description text. The two can be combined, e.g. `mode=search` with `searchQuery=hotel` plus `containsKeyword=Kampala` to further narrow site-wide hotel matches to ones mentioning Kampala.

**Why do some listings have very few fields?**
Only fields a business owner actually published are included — this actor never fills in placeholder or guessed values. A business with no website simply has no `website` field.

**Are `city`/`region` fields available?**
No — the site's own city/region taxonomy fields are a fixed site-wide default and don't reliably reflect each business's actual location (confirmed: businesses outside Kampala still carry the site's default "Kampala" taxonomy value). The `address` field (free text, as entered by the business) and `latitude`/`longitude` (individually geocoded per business) are accurate and are what this actor exposes instead.

**How fresh is the data?**
Every run scrapes the live site in real time — there is no caching layer.

**Can I combine multiple filters?**
Yes — `minRating`/`maxRating`, `requirePhone`, `requireEmail`, `requireWebsite`, and `containsKeyword` all compose together.

# Actor input Schema

## `mode` (type: `string`):

What to scrape: browse a business category, run a free-text search across every category, or fetch specific business profiles from direct yellowpages-uganda.com URLs.

## `searchQuery` (type: `string`):

Free-text keyword to search across every yellowpages-uganda.com category, e.g. "hotel" or "bank". Matches business names/listings site-wide (not limited to one category).

## `category` (type: `string`):

Business category to browse (mode=byCategory). This is the full list of categories yellowpages-uganda.com actually publishes.

## `sortBy` (type: `string`):

Sort order for results (mode=byCategory or mode=search). Maps to yellowpages-uganda.com's own listing sort options.

## `startUrls` (type: `array`):

Direct yellowpages-uganda.com business listing URLs to fetch (mode=byUrl), e.g. https://www.yellowpages-uganda.com/listings/uganda/central-region/kampala/hotels-uganda/kampala-serena-hotel/

## `maxItems` (type: `integer`):

Maximum number of business records to return.

## `minRating` (type: `number`):

Only include businesses whose visitor rating is at least this value (0-5 stars). Businesses with no rating yet are always included (the filter only excludes rated businesses below the threshold).

## `maxRating` (type: `number`):

Only include businesses whose visitor rating is at most this value (0-5 stars). Businesses with no rating yet are always included.

## `requirePhone` (type: `boolean`):

Only include businesses that have a published phone number.

## `requireEmail` (type: `boolean`):

Only include businesses that have a published email address.

## `requireWebsite` (type: `boolean`):

Only include businesses that have a published website.

## `containsKeyword` (type: `string`):

Only include businesses whose name or description contains this text (case-insensitive). Leave blank to disable.

## Actor input object example

```json
{
  "mode": "byCategory",
  "searchQuery": "hotel",
  "category": "hotels-uganda",
  "sortBy": "newest",
  "startUrls": [
    {
      "url": "https://www.yellowpages-uganda.com/listings/uganda/central-region/kampala/hotels-uganda/kampala-serena-hotel/"
    }
  ],
  "maxItems": 30,
  "minRating": 0,
  "maxRating": 5,
  "requirePhone": false,
  "requireEmail": false,
  "requireWebsite": false,
  "containsKeyword": ""
}
```

# Actor output Schema

## `businesses` (type: `string`):

Dataset containing all scraped Uganda business directory listings.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "mode": "byCategory",
    "searchQuery": "hotel",
    "category": "hotels-uganda",
    "sortBy": "newest",
    "startUrls": [
        {
            "url": "https://www.yellowpages-uganda.com/listings/uganda/central-region/kampala/hotels-uganda/kampala-serena-hotel/"
        }
    ],
    "maxItems": 30,
    "minRating": 0,
    "maxRating": 5,
    "requirePhone": false,
    "requireEmail": false,
    "requireWebsite": false,
    "containsKeyword": ""
};

// Run the Actor and wait for it to finish
const run = await client.actor("crawlerbros/uganda-business-directory-scraper").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "mode": "byCategory",
    "searchQuery": "hotel",
    "category": "hotels-uganda",
    "sortBy": "newest",
    "startUrls": [{ "url": "https://www.yellowpages-uganda.com/listings/uganda/central-region/kampala/hotels-uganda/kampala-serena-hotel/" }],
    "maxItems": 30,
    "minRating": 0,
    "maxRating": 5,
    "requirePhone": False,
    "requireEmail": False,
    "requireWebsite": False,
    "containsKeyword": "",
}

# Run the Actor and wait for it to finish
run = client.actor("crawlerbros/uganda-business-directory-scraper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "mode": "byCategory",
  "searchQuery": "hotel",
  "category": "hotels-uganda",
  "sortBy": "newest",
  "startUrls": [
    {
      "url": "https://www.yellowpages-uganda.com/listings/uganda/central-region/kampala/hotels-uganda/kampala-serena-hotel/"
    }
  ],
  "maxItems": 30,
  "minRating": 0,
  "maxRating": 5,
  "requirePhone": false,
  "requireEmail": false,
  "requireWebsite": false,
  "containsKeyword": ""
}' |
apify call crawlerbros/uganda-business-directory-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,crawlerbros/uganda-business-directory-scraper"
        }
    }
}

```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/MzRIv46h5zfY1giyy/builds/N7kO3zsJycfW0lHBb/openapi.json