Search by

d1msky / nusantara-shipping

D1msky

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.

Package info

github.com/D1msky/nusantara-shipping

pkg:composer/d1msky/nusantara-shipping

Statistics

Installs: 6

Dependents: 0

Suggesters: 0

Stars: 1

Open Issues: 0

v2.0.1 2026-10-19 08:33 UTC

This package is auto-updated.

Last update: 2026-10-19 08:35:44 UTC


README

Tests 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?

Feature Nusantara Others
Data Kepmendagri 2025 (updateable via command) Often 2018–2022
Storage File (zero DB) or Database Usually DB-only or file-only
Shipping Address formatter, postal lookup, coordinates Rare or basic
Search Fuzzy + Indonesian aliases (Jkt, Jaksel, SBY, …) Exact or simple like
DX PHP 8.1+ enums, typed API, caching Varies

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)
  • OPcache recommended for the file driver: the data files are then shared across requests at no per-request cost.

Upgrading from 1.x? Region codes changed to the official Kepmendagri codes — see UPGRADE.md.

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:

Option Default Description
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 formats

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.

The migration is only registered when NUSANTARA_DRIVER=database, so apps using the file driver don't get these tables. Set the driver before running migrate (or nusantara:install --migrate, which refuses to run with another driver).

Artisan commands

Command Description
nusantara:install Publish config; optional --migrate (runs only the Nusantara migration; database driver only) and --seed
nusantara:seed Seed DB from data files (`--only=provinces
nusantara:update-data Show data source info; use --source=<path_or_url> to fetch and transform
nusantara:stats Print counts (provinces, regencies, districts, villages, postal codes)
nusantara:clear-cache Clear Nusantara cache (works on every cache store, tags not required)

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

The package ships the full Kepmendagri No 300.2.2-2138 Tahun 2025 dataset (Indonesian Ministry of Home Affairs):

Level Rows Extra
Provinces 38 coordinates
Regencies (kabupaten/kota) 514 coordinates
Districts (kecamatan) 7,285 coordinates for 5,619; the rest fall back to the regency in coordinates()
Villages (kelurahan/desa) 83,762 postal code for every village

Codes and names come from cahyadsn/wilayah, postal codes from cahyadsn/wilayah_kodepos (both MIT); see data/NOTICE.md. To load a newer dataset, use the nusantara:update-data command.

Villages are stored as one line per village in data/villages.php (about 2.5 MB on disk, 5 MB in memory), so even without OPcache a lookup by district, code or postal code and a name search across all villages take a few milliseconds.

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

Type Example Description
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

File Required Description
provinces.json Yes Array of province objects.
regencies.json No Array of regency/kabupaten/kota objects.
districts.json No Array of district/kecamatan objects.
villages.json No Array 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

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

php artisan nusantara:update-data --source=https://example.com/wilayah/json

The base URL must serve provinces.json (required) and optionally regencies.json, districts.json, and villages.json.

Use Kepmendagri codes, not BPS codes. BPS uses 7-digit district codes (e.g. 3273100 Rancasari, 3273101 Gedebage) that cannot be mapped to the 32.73.10 format, so several districts end up with the same code and overwrite each other when seeding. The command prints a warning when codes collide after normalization; if you see it, switch to a Kepmendagri-coded source.

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

The command flushes the Nusantara cache and invalidates OPcache for the rewritten files, so the new data is served immediately.

By default the files are written to the package's data/ folder inside vendor/, which composer install / composer update will overwrite. Set NUSANTARA_DATA_PATH to a directory you control (e.g. storage_path('nusantara')) to keep updated data across deploys.

  • 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

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.