PHPackages d1msky/nusantara-shipping - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Utility & Helpers](/categories/utility) 4. / 5. d1msky/nusantara-shipping ActiveLibrary[Utility & Helpers](/categories/utility) d1msky/nusantara-shipping ========================= Indonesia region data (Kepmendagri 2025) for Laravel — shipping address formatting, postal code lookup, fuzzy search, dual-mode storage (file/database). Usable worldwide in Laravel apps. v1.0.2(4mo ago)10MITPHPPHP ^8.1CI passing Since Feb 23Pushed 4mo agoCompare [ Source](https://github.com/D1msky/nusantara-shipping)[ Packagist](https://packagist.org/packages/d1msky/nusantara-shipping)[ RSS](/packages/d1msky-nusantara-shipping/feed)WikiDiscussions main Synced today READMEChangelogDependencies (4)Versions (4)Used By (0) Nusantara — Indonesia Region Data for Laravel ============================================= [](#nusantara--indonesia-region-data-for-laravel) [![Tests](https://github.com/D1msky/nusantara-shipping/actions/workflows/tests.yml/badge.svg)](https://github.com/D1msky/nusantara-shipping/actions/workflows/tests.yml)[![License](https://camo.githubusercontent.com/7013272bd27ece47364536a221edb554cd69683b68a46fc0ee96881174c4214c/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d626c75652e737667)](LICENSE) **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? ----------------- [](#why-this-package) FeatureNusantaraOthers**Data**Kepmendagri 2025 (updateable via command)Often 2018–2022**Storage**File (zero DB) or DatabaseUsually DB-only or file-only**Shipping**Address formatter, postal lookup, coordinatesRare or basic**Search**Fuzzy + Indonesian aliases (Jkt, Jaksel, SBY, …)Exact or simple like**DX**PHP 8.1+ enums, typed API, cachingVariesUse it for: dropdowns (provinces → regencies → districts → villages), address validation, shipping labels, postal code checks, and search that understands “Jaksel”, “Surabaya”, “Jogja”, etc. --- Requirements ------------ [](#requirements) - **PHP** 8.1+ - **Laravel** 10, 11, or 12 - **illuminate/support** & **illuminate/database** (no extra deps) --- Installation ------------ [](#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 ----------- [](#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 ------------- [](#configuration) Publish and edit `config/nusantara.php`: OptionDefaultDescription`driver``file``file` (no DB) or `database``table_prefix``nusantara_`Table prefix in database mode`cache_ttl``86400`Cache TTL (seconds); `0` = no cache`cache_store``null`Cache store (null = default)`data_path`package `data/`Path to PHP data files (file driver)`search.fuzzy_threshold``70`Min similarity (0–100) for fuzzy match`search.max_results``20`Max search results`aliases``[]`Custom alias → region name for search`shipping_styles``[]`Custom courier formatsEnv example: ``` NUSANTARA_DRIVER=file NUSANTARA_CACHE_TTL=86400 NUSANTARA_DATA_PATH= ``` --- Database mode ------------- [](#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 ---------------- [](#artisan-commands) CommandDescription`nusantara:install`Publish config; optional `--migrate` and `--seed``nusantara:seed`Seed DB from data files (`--only=provinces`nusantara:update-data`Show data source info; use `--source=` to fetch and transform`nusantara:stats`Print counts (provinces, regencies, districts, villages, postal codes)`nusantara:clear-cache`Clear Nusantara cache--- Extending --------- [](#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 ----------------------- [](#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 [](#command) ``` php artisan nusantara:update-data --source= ``` - **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 [](#input-path-or-url) TypeExampleDescription**Local folder**`--source=/path/to/data`Folder must contain at least `provinces.json`. Optional: `regencies.json`, `districts.json`, `villages.json`.**Base URL**`--source=https://example.com/data`Command will request `{url}/provinces.json`, `{url}/regencies.json`, etc. Each must return a JSON array.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 [](#required-and-optional-files) FileRequiredDescription`provinces.json`**Yes**Array of province objects.`regencies.json`NoArray of regency/kabupaten/kota objects.`districts.json`NoArray of district/kecamatan objects.`villages.json`NoArray of village/kelurahan/desa objects.If a file is missing, that level is skipped; existing PHP data for that level is not overwritten. ### Expected JSON structure [](#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) [](#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 [](#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 [](#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 [](#recommended-public-sources) - [yusufsyaifudin/wilayah-indonesia](https://github.com/yusufsyaifudin/wilayah-indonesia) — JSON in `data/list_of_area/` (provinces, regencies, districts, villages). - [cahyadsn/wilayah](https://github.com/cahyadsn/wilayah) — Kepmendagri; provides SQL; for JSON you need to export or use a repo that exposes JSON. - [hanifabd/wilayah-indonesia-area](https://github.com/hanifabd/wilayah-indonesia-area) — data in other formats (e.g. zip); use a source that exposes `.json` files if you want to use `--source=` directly. --- Testing ------- [](#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 ------------ [](#contributing) Contributions are welcome. Please open an issue or PR on GitHub. --- License ------- [](#license) MIT. See [LICENSE](LICENSE). ### Health Score 34 — LowBetter than 75% of packages Maintenance76 Regular maintenance activity Popularity2 Limited adoption so far Community8 Small or concentrated contributor base Maturity45 Maturing project, gaining track record Bus Factor1 Top contributor holds 90% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~0 days Total 3 Last Release 131d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/dd3416dc52e3fb7518ad4c6a512c693e908e00052776148732684cf77a5a0e12?d=identicon)[D1msky](/maintainers/D1msky) --- Top Contributors [![D1msky](https://avatars.githubusercontent.com/u/22637444?v=4)](https://github.com/D1msky "D1msky (9 commits)")[![claude](https://avatars.githubusercontent.com/u/81847?v=4)](https://github.com/claude "claude (1 commits)") --- Tags laraveladdressshippingregionindonesiapostal-codeprovinsikabupatenkecamatankelurahanwilayahfuzzy-searchnusantarakode-posaddress-formatter ### Code Quality TestsPHPUnit ### Embed Badge ![Health badge](/badges/d1msky-nusantara-shipping/health.svg) ``` [![Health](https://phpackages.com/badges/d1msky-nusantara-shipping/health.svg)](https://phpackages.com/packages/d1msky-nusantara-shipping) ``` ### Alternatives [psalm/plugin-laravel Psalm plugin for Laravel 3355.3M346](/packages/psalm-plugin-laravel)[laravolt/indonesia Package Laravel yang berisi data Provinsi, Kabupaten/Kota, Kecamatan, dan Keluarahan/Desa di seluruh Indonesia. 668212.3k1](/packages/laravolt-indonesia)[api-platform/laravel API Platform support for Laravel 58171.6k14](/packages/api-platform-laravel)[creasi/laravel-nusa A Laravel package that aim to provide Indonesia' Administrative Data 997.9k3](/packages/creasi-laravel-nusa)[wearepixel/laravel-cart A cart implementation for Laravel 1374.8k](/packages/wearepixel-laravel-cart) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)