kusaasira/uganda-geo-data

Uganda's geo data i.e districts, counties, subcounties, parishes & villages.

Uganda Geo Data

This is a PHP package that retrieves Uganda's districts with their respective counties, sub counties, parishes and villages in Uganda. This data has been scrapped off Uganda's passport's official portal.

Description

This package gives you the leverage to access all sub levels ranging from districts, counties, subcounties, parishes to villages in Uganda. You can also access the different mentioned areas independently.

Table of Contents

• Requirements
• Installation
• Usage
  • Retrieve Districts data
  • Retrieve Individual geo units data.
• Credits
• Contributions
• License

Requirements

In order to run this project, ensure that you have installed;

• PHP 7.4 or later
• Composer

Installation

This project using composer.

$ composer require kusaasira/uganda-geo

Usage

The examples below show examples of usage of the package and their resulting outputs

Retrieve Districts data.

use Uganda\Uganda;

$uganda = new Uganda();

# Retrieve all districts
$districts = $uganda->districts();

# Retrieve all counties in a particular district
$counties = $uganda
    ->district('Mukono')
    ->counties();

# Retrieve all sub counties in a particular district
$subCounties = $uganda
    ->district('Mukono')
    ->subCounties();


# Retrieve all parishes in a particular district
$parishes = $uganda
    ->district('Mukono')
    ->parishes();

# Retrieve all villages in a particular district
$villages = $uganda
    ->district('Mukono')
    ->villages();

Retrieve County data.

use Uganda\Uganda;

$uganda = new Uganda();

# Retrieve all counties
$counties = $uganda->counties();

# Retrieve specific county
$county = $uganda->county('Adjumani West County');

# Retrieve all sub counties in a particular county
$subCounties = $uganda
    ->county('Adjumani West County')
    ->subCounties();

# Retrieve all parishes in a particular county
$parishes = $uganda
    ->county('Adjumani West County')
    ->parishes();

# Retrieve all villages in a particular county
$villages = $uganda
    ->county('Adjumani West County')
    ->villages();

Retrieve Sub County data.

use Uganda\Uganda;

$uganda = new Uganda();

# Retrieve all sub counties
$subCounties = $uganda->subCounties();

# Retrieve specific sub county
$subCounty = $uganda->subCounty('Namasale Town Council');

# Retrieve all parishes in a particular sub county
$parishes = $uganda
    ->county('Namasale Town Council')
    ->parishes();

# Retrieve all villages in a particular sub county
$villages = $uganda
    ->county('Namasale Town Council')
    ->villages();

Retrieve Parish data.

use Uganda\Uganda;

$uganda = new Uganda();

# Retrieve all parishes
$parishes = $uganda->parishes();

# Retrieve specific parish
$parish = $uganda->parish('Bunamwamba');

# Retrieve all villages in a particular parish
$villages = $uganda
    ->county('Bunamwamba')
    ->villages();

Retrieve Village data.

use Uganda\Uganda;

$uganda = new Uganda();

# Retrieve all villages
$villages = $uganda->villages();

# Retrieve specific village
$subCounty = $uganda->village('Ayeye');

Credits

The data used in this package has been scrapped off This data has been scrapped off Uganda's passport's official portal as there is no updated geo data source since 2018 published anywhere.

Collaborators ✨

Tim3k

Joshua Kusaasira

Marshud

Contributors ✨

Joshua Kusaasira

Zack

License

This package is free software distributed under the terms of the MIT license.

uganda-geo-data's Issues

Adding Laravel Package support to the Library

Since a lot of applications are built using Laravel these days, do we want to look into adding support for Laravel in this package. That way people can just start using the Ugandan geo information within their applications.

This is just the start of a discussion post around what would be required if we wanted to support this going forward?

Information regarding packages within Laravel:
https://laravel.com/docs/9.x/packages

Remove chaining dependability on the all method.

Currently all requests end methods end with the all() method. This is decoupling the code. Refactor this to increase maintainability and reduce dependability on the all() method.

Follow PSR-12 coding standards and guidelines.

Fetch all subcounties in a particular district

Create a method that fetches only sub counties from a particular parsed district.

Follow Appblocks Standards and Guidelines.

At the moment, one has to go through a chain to fetch subcounties i.e. see code block below.

$geo = new Geo();
$data = $geo
        ->districts('Mukono')
        ->counties('Mukono Municipality')
        ->sub_counties->all();

Refactor this to accept fetching subcounties as indicated below;

$geo = new Geo();
$data = $geo
        ->districts('Mukono')
        ->sub_counties->all();

For more information on the structure, checkout the repo wiki.

Follow PSR-12 coding standards and guidelines.

Look into dropping support for PHP 7.4

Since PHP 7.4 will no longer get any security updates. Do we want to look into dropping support for this and only allowing the package to be used on PHP 8.0?

Obviously this package can still be downloaded using the older tags but all new tags move across to a newer version of PHP?

Refactor codebase

Refactor codebase to follow DRY / SOLID and reduce coupling.

Follow PSR-12 coding standards and guidelines.