madebyclowd / laravel-nusantara

v1.4.0 2026-09-02 01:27 UTC

Requires

• php: ^8.2
• illuminate/contracts: ^11.0|^12.0|^13.0
• illuminate/database: ^11.0|^12.0|^13.0
• illuminate/support: ^11.0|^12.0|^13.0
• nesbot/carbon: ^2.71|^3.0

Requires (Dev)

• brick/geo: ^0.13
• guzzlehttp/guzzle: ^7.8
• larastan/larastan: ^3.10
• laravel/pint: ^1.13
• orchestra/testbench: ^9.0|^10.0|^11.0
• phpunit/phpunit: ^10.0|^11.0|^12.0|^13.0

Suggests

• brick/geo: Required to decode native spatial boundary columns (config('nusantara.boundaries.type', 'spatial')) into GeoJSON via toGeoJson().
• laravel/boost: Auto-discovers this package's AI guidelines and agent skill from resources/boost/ — no extra setup needed.

MIT

• I Gede Widiantara

• database
• laravel
• seeder
• indonesia
• regions
• provinces
• administrative
• districts
• regencies
• villages
• wilayah

Published on Packagist.org on 2026-09-02 01:27 UTC

README

This package gives your Laravel app Indonesia's full administrative region data: provinces, regencies, districts, and villages. Real database tables, real Eloquent models, ready to query out of the box.

Data compiled according to Kepmendagri No 300.2.2-2138 Year 2025.

Quick Start

Step 1: Install the package

composer require madebyclowd/laravel-nusantara

Step 2: Run the setup wizard

It asks a few yes/no questions. Press Enter each time to pick the normal answer. It publishes the config, runs the migrations, and seeds the region data.

php artisan nusantara:install

Step 3: Query it

use MadeByClowd\Nusantara\Facades\Nusantara;

$province = Nusantara::findProvince('11');
$regencies = Nusantara::regenciesOf('11');

Done. All 38 provinces, every regency, district, and village are already in your database.

Features

• Works on any database. SQLite, PostgreSQL, MySQL, SQL Server, or your own custom connection.
• Rename anything. Any table or column name can match your own schema.
• Turn off what you don't need. Skip columns like elevation, timezone, or population to save space.
• Your own attribute names. Call $province->name even if the real column is named nama_provinsi.
• Caching built in. Repeat queries don't hit the database twice.
• Ready-made relationships. Province to regency to district to village, all wired up.
• Optional JSON API. Drop-in endpoints for checkout or registration dropdowns.
• Low-memory seeder. Seeds the entire dataset using under 3MB of memory.
• Map shapes on demand. Download high-resolution boundary polygons only when you need them.
• Reverse geocoding. Find which region a coordinate falls in, or export any region as GeoJSON.
• NIK & postal code tools. Parse and validate Indonesian national ID numbers and postal codes.
• AI-agent ready. Ships a Laravel Boost guideline so AI coding assistants query this package correctly out of the box.

Requirements

• PHP: ^8.2
• Laravel: ^11.0, ^12.0, or ^13.0

Documentation

The docs/ folder covers every feature step by step:

• Facade & Queries
• Models & Relations
• Configuration
• Geographic Boundaries & Maps
• REST API
• AI Agent Integration
• Troubleshooting / FAQ

Testing

composer install
vendor/bin/pint --test     # code style
vendor/bin/phpstan analyse # static analysis
vendor/bin/phpunit         # test suite

See CONTRIBUTING.md for the full contribution workflow.

Credits

• Special thanks to cahyadsn for curating and providing the raw Indonesia administrative data used as the source for this package's dataset.

License

The MIT License (MIT). Please see LICENSE for more information.