README

A Laravel package for Afghanistan provinces, districts, and villages.

This package includes a full village database — 8,892 villages across all 34 provinces, each with a name, GPS coordinates, and links to its province and district. No database migrations or seeding required; villages ship as JSON and load at runtime.

Built by Barialay.

What's included

Features

• List all 8,892 villages or filter by province / district
• Province → district → village cascade — ideal for 3-level dropdowns
• Villages include latitude, longitude, and area data when available
• Find a village by ID or name
• Multilingual province and district names (English, Dari, Pashto)
• Laravel auto-discovery (Service Provider + Afghanistan Facade)
• Publishable config and JSON data files
• Typed objects: Province, District, Village

Requirements

• PHP: ^7.3 or ^8.0
• Laravel: ^8.0 through ^12.0

PHP 7.3/7.4 only works with Laravel 8. Laravel 9 and above require PHP 8.0+.

Installation

composer require barialay/afghanistan-province-district-village:^1.4

The package auto-registers. No manual setup needed.

If Composer blocks installation (security advisories)

If you see errors about security advisories on laravel/framework, update your Laravel app first — this is not a package issue:

composer update
composer require barialay/afghanistan-province-district-village:^1.4

Publish config (optional)

php artisan vendor:publish --tag=afghanistan-province-district-village-config

Publish data files (optional)

php artisan vendor:publish --tag=afghanistan-province-district-village-data

Villages

The package lists villages. Use any of the methods below depending on your UI or API.

List all villages

use Barialay\AfghanistanProvinceDistrictVillage\Facades\Afghanistan;

$allVillages = Afghanistan::villages();       // Collection of 8,892 Village objects
$total       = Afghanistan::countVillages();    // 8892

List villages by province

$kabul = Afghanistan::provinceByName('Kabul');

$villages = Afghanistan::villagesByProvince($kabul->id);
// Every village in Kabul province

List villages by district (recommended for dropdowns)

$kabul = Afghanistan::provinceByName('Kabul');
$districts = Afghanistan::districts($kabul->id);
$kabulDistrict = $districts->firstWhere('name', 'Kabul');

$villages = Afghanistan::villagesByDistrict($kabulDistrict->id);
// Every village in Kabul district — works for all 34 provinces

List villages by province + district name

$villages = Afghanistan::villages('Kabul', 'Kabul');
$villages = Afghanistan::villages('Herat', 'Herat');
$villages = Afghanistan::villages('Badakhshan', 'Wakhan');

Find a single village

$village = Afghanistan::village(4183);
$village = Afghanistan::villageByName('Ab Bala');

echo $village->name;       // Ab Bala
echo $village->province;   // Bamyan
echo $village->district;   // ...
echo $village->latitude;
echo $village->longitude;

Verify villages in Tinker

php artisan tinker

Afghanistan::countVillages();   // 8892
Afghanistan::villages()->count(); // 8892

// Villages exist in every province
Afghanistan::villagesByProvince(Afghanistan::provinceByName('Herat')->id)->count();
Afghanistan::villagesByProvince(Afghanistan::provinceByName('Ghazni')->id)->count();

Province → District → Village cascade

Full 3-level flow for forms and APIs:

use Barialay\AfghanistanProvinceDistrictVillage\Facades\Afghanistan;

// 1. List provinces
$provinces = Afghanistan::provinces();

// 2. User picks a province → list its districts
$herat = Afghanistan::provinceByName('Herat');
$districts = Afghanistan::districts($herat->id);

// 3. User picks a district → list its villages
$heratDistrict = $districts->firstWhere('name', 'Herat');
$villages = Afghanistan::villagesByDistrict($heratDistrict->id);

foreach ($villages as $village) {
    echo $village->id;
    echo $village->name;
    echo $village->latitude;
    echo $village->longitude;
}

Blade — 3 dropdowns (province, district, village)

{{-- Province --}}
<select name="province_id" id="province">
    @foreach (Afghanistan::provinces() as $province)
        <option value="{{ $province->id }}">{{ $province->nameFor('fa') }}</option>
    @endforeach
</select>

{{-- District (load via AJAX when province changes) --}}
<select name="district_id" id="district"></select>

{{-- Village (load via AJAX when district changes) --}}
<select name="village_id" id="village"></select>

Load districts and villages from your controller:

// GET /districts/{provinceId}
return Afghanistan::districts($provinceId)->map->toArray();

// GET /villages/{districtId}
return Afghanistan::villagesByDistrict($districtId)->map->toArray();

API routes example

use Barialay\AfghanistanProvinceDistrictVillage\Facades\Afghanistan;
use Illuminate\Http\Request;

// GET /api/provinces
public function provinces()
{
    return Afghanistan::provinces()->map->toArray();
}

// GET /api/districts/{provinceId}
public function districts(int $provinceId)
{
    return Afghanistan::districts($provinceId)->map->toArray();
}

// GET /api/villages?district_id=129
public function villages(Request $request)
{
    if ($request->filled('district_id')) {
        return Afghanistan::villagesByDistrict((int) $request->query('district_id'))->map->toArray();
    }

    if ($request->filled('province_id')) {
        return Afghanistan::villagesByProvince((int) $request->query('province_id'))->map->toArray();
    }

    return Afghanistan::villages()->map->toArray();
}

API Reference

Facade

use Barialay\AfghanistanProvinceDistrictVillage\Facades\Afghanistan;

// Provinces
Afghanistan::provinces();
Afghanistan::province(32);
Afghanistan::provinceByName('Kabul');
Afghanistan::provinceByName('کابل');

// Districts
Afghanistan::districts();
Afghanistan::districts($provinceId);

// Villages — list, filter, find
Afghanistan::villages();                              // all 8,892 villages
Afghanistan::villagesByProvince($provinceId);         // villages in one province
Afghanistan::villagesByDistrict($districtId);         // villages in one district
Afghanistan::villages('Badakhshan', 'Wakhan');        // by province + district name
Afghanistan::village(4183);                           // by ID
Afghanistan::villageByName('Ab Bala');                // by name

// Counts
Afghanistan::countProvinces();   // 34
Afghanistan::countDistricts();
Afghanistan::countVillages();    // 8892

Dependency injection

use Barialay\AfghanistanProvinceDistrictVillage\Afghanistan;

class LocationController
{
    protected $afghanistan;

    public function __construct(Afghanistan $afghanistan)
    {
        $this->afghanistan = $afghanistan;
    }

    public function villagesByDistrict(int $districtId)
    {
        return $this->afghanistan
            ->villagesByDistrict($districtId)
            ->map->toArray();
    }
}

Configuration

// config/afghanistan-province-district-village.php

return [
    'villages_file' => resource_path('afghanistan-province-district-village/villages.json'),
    'provinces_file' => resource_path('afghanistan-province-district-village/provinces-and-districts.json'),
    'default_locale' => 'en', // en, fa, pa
];

Data Structure

Village

Each of the 8,892 villages has:

Province / District

Testing

composer test

Data Disclaimer

Geographic data is compiled from public sources. Some village entries may be incomplete or inaccurate. Always verify critical location data independently.

Contributing

See CONTRIBUTING.md.

Contributions are welcome via Pull Request on GitHub.

License

This package is open-source software licensed under the MIT License.

Copyright (c) 2026 Barialay.