README

Official Indonesian administrative region data (Kepmendagri 2025) for Laravel — with shipping address formatting, postal code lookup, fuzzy search, and dual-mode storage (file or database). Built for Laravel apps anywhere in the world that need to handle Indonesian addresses (e.g. e‑commerce, logistics, forms).

Why this package?

Use it for: dropdowns (provinces → regencies → districts → villages), address validation, shipping labels, postal code checks, and search that understands “Jaksel”, “Surabaya”, “Jogja”, etc.

Requirements

• PHP 8.1+
• Laravel 10, 11, or 12
• illuminate/support & illuminate/database (no extra deps)

Installation

composer require d1msky/nusantara-shipping

Publish config (optional):

php artisan nusantara:install

Or manually:

php artisan vendor:publish --tag=nusantara-config

For database mode (optional):

php artisan nusantara:install --migrate --seed

Quick start

use Nusantara\Facades\Nusantara;

// Hierarchical data (dropdowns)
$provinces = Nusantara::provinces();
$regencies = Nusantara::regencies('32');           // by province code
$regencies = Nusantara::regencies('JAWA BARAT');    // by province name
$districts = Nusantara::districts('32.73');
$villages  = Nusantara::villages('32.73.01');

// Find by code (any level)
$region = Nusantara::find('32.73.01.1001');

// Fuzzy search (handles typos and Indonesian abbreviations)
$results = Nusantara::search('jaksel');
$results = Nusantara::search('sby', level: 'regency');

// Postal code
$regions = Nusantara::postalCode('40132');
$valid   = Nusantara::validPostalCode('40132');
$codes   = Nusantara::postalCodes('32.73');

// Full hierarchy
$path = Nusantara::hierarchy('32.73.01.1001');
// ['province' => [...], 'regency' => [...], 'district' => [...], 'village' => [...]]

// Shipping address
$address = Nusantara::shippingAddress('32.73.01.1001');
$address = Nusantara::shippingAddress('32.73.01.1001', style: 'jne');

// Coordinates & nearest regency
$coords  = Nusantara::coordinates('32.73');
$nearest = Nusantara::nearestRegency(-6.2088, 106.8456);

Configuration

Publish and edit config/nusantara.php:

Env example:

NUSANTARA_DRIVER=file
NUSANTARA_CACHE_TTL=86400
NUSANTARA_DATA_PATH=

Database mode

1. Set NUSANTARA_DRIVER=database.
2. Run migrations:

   php artisan migrate

3. Seed from package data files:

   php artisan nusantara:seed
   php artisan nusantara:seed --only=provinces

Tables: nusantara_provinces, nusantara_regencies, nusantara_districts, nusantara_villages.

Artisan commands

Extending

Custom search aliases (config/nusantara.php):

'aliases' => [
    'mycity' => 'KOTA BANDUNG',
],

Custom shipping style:

'shipping_styles' => [
    'my_courier' => [
        'format' => ':village, :district, :regency, :province, :postal',
        'case' => 'upper',
        'separator' => ', ',
    ],
],

Then: Nusantara::shippingAddress($code, style: 'my_courier').

Data source and updates

Region data follows Kepmendagri (Indonesian Ministry of Home Affairs). The package ships with sample data so it works out of the box. For full or up-to-date datasets, use the nusantara:update-data command.

Command

php artisan nusantara:update-data --source=<path_or_base_url>

• Without --source: prints usage and recommended sources (no files changed).
• With --source: fetches or reads JSON from the given path/URL, converts it to the PHP format used by the package, and writes provinces.php, regencies.php, districts.php, and villages.php into the package data/ folder (or config('nusantara.data_path') if set).

Input: path or URL

For a local folder, the path must be absolute or relative to the current working directory. For a URL, use a base URL that serves the JSON files directly (e.g. raw GitHub or a CDN).

Required and optional files

If a file is missing, that level is skipped; existing PHP data for that level is not overwritten.

Expected JSON structure

Each file must be a JSON array of objects. The command normalizes common field names:

• Provinces: code / id / kode, name / nama; optional: latitude/lat, longitude/lng/lon.
• Regencies: code / id / kode, name / nama, province_code / provinceCode / kode_provinsi / province_id (or derived from code); optional: latitude, longitude.
• Districts: code / id / kode, name / nama, regency_code / regencyCode / kode_kabupaten (or derived from code); optional: latitude, longitude.
• Villages: code / id / kode, name / nama, district_code / districtCode / kode_kecamatan (or derived from code); optional: postal_code / postalCode / kode_pos / zip.

Codes can be dotted (e.g. 32.73) or plain (e.g. 3273); the command normalizes to dotted format where applicable.

Example: URL (raw GitHub)

php artisan nusantara:update-data --source=https://raw.githubusercontent.com/yusufsyaifudin/wilayah-indonesia/master/data/list_of_area

This URL serves provinces.json, regencies.json, districts.json, and villages.json directly.

Example: local folder

1. Clone a repo that contains JSON (e.g. in a data or data/list_of_area folder).
2. Run:

php artisan nusantara:update-data --source=/absolute/path/to/folder/with/provinces.json
# or, from project root:
php artisan nusantara:update-data --source=./vendor/some/repo/data

The folder must contain at least provinces.json.

After updating data

• File driver (NUSANTARA_DRIVER=file): Data is read from the updated PHP files; no further step.
• Database driver (NUSANTARA_DRIVER=database): Run the seeder to fill the database from the updated files:

php artisan nusantara:seed

Then check counts:

php artisan nusantara:stats

Recommended public sources

• yusufsyaifudin/wilayah-indonesia — JSON in data/list_of_area/ (provinces, regencies, districts, villages).
• cahyadsn/wilayah — Kepmendagri; provides SQL; for JSON you need to export or use a repo that exposes JSON.
• hanifabd/wilayah-indonesia-area — data in other formats (e.g. zip); use a source that exposes .json files if you want to use --source=<url> directly.

Testing

composer install
vendor/bin/phpunit

To generate a coverage report (requires PCOV or Xdebug):

vendor/bin/phpunit --coverage-text
# or
vendor/bin/phpunit --coverage-html build/coverage

Contributing

Contributions are welcome. Please open an issue or PR on GitHub.

License

MIT. See LICENSE.