README

PHP library for Indonesian administrative regions (province, regency/city, district, village) based on SIG BPS.

Data is shipped as static PHP files per period — no API call at runtime.

Library PHP untuk data wilayah Indonesia (provinsi, kabupaten/kota, kecamatan, desa/kelurahan). Data sudah di-bundle; aplikasi hanya membaca file lokal.

Features

Cascade lookup: province → regency → district → village
BPS + Kemendagri (DAGRI) codes and names on every record
Period-aware dataset (default: latest available period)
Zero runtime dependency on BPS network for consumers
CLI tools for maintainers to sync/update data from BPS

Requirements

PHP ^8.2

Installation

composer require siibnu/wilayah-indonesia-bps

Packagist: siibnu/wilayah-indonesia-bps

Quick start

use Siibnu\WilayahIndonesiaBps\Wilayah;

$wilayah = new Wilayah();                 // latest period
// $wilayah = new Wilayah('2025_2.2025'); // specific period

$provinces = $wilayah->provinces();
$regencies = $wilayah->regencies('11');       // Aceh
$districts = $wilayah->districts('1101');     // Simeulue
$villages  = $wilayah->villages('1101010');   // Teupah Selatan

$village = $wilayah->village('1101010001');
echo $village?->bpsName;   // LATIUNG
echo $village?->dagriCode; // 11.09.07.2008

// Auto-detect level by BPS code length (2 / 4 / 7 / 10)
$item = $wilayah->find('1101010001');

Available methods

Method	Returns
`periods()`	`list<Period>`
`period()`	active `Period`
`provinces()` / `province($code)`	list / single
`regencies($provinceCode)` / `regency($code)`	list / single
`districts($regencyCode)` / `district($code)`	list / single
`villages($districtCode)` / `village($code)`	list / single
`find($bpsCode)`	`Region\|null`
`syncStatuses()`	sync checklist per period
`withPeriod($code)`	new instance for another period

DTO fields

Province, Regency, District, and Village extend Region:

Property	API field
`bpsCode`	`kode_bps`
`bpsName`	`nama_bps`
`dagriCode`	`kode_dagri`
`dagriName`	`nama_dagri`

Use $item->toArray() when you need a plain array (e.g. JSON API).

Available data (sync status)

Period	Province	Regency	District	Village	Complete
`2025_2.2025`	✅	✅	✅	✅	✅
`2025_1.2025`	❌	❌	❌	❌	❌
`2024_1.2025`	❌	❌	❌	❌	❌
`2024_1.2022`	❌	❌	❌	❌	❌
`2023_1.2022`	❌	❌	❌	❌	❌
`2020_1.2020`	❌	❌	❌	❌	❌
`2019_1.2019`	❌	❌	❌	❌	❌

Check locally after updates:

vendor/bin/status
# or
composer run-script status

TODO sync

2025_2.2025 — complete (province → village)
2025_1.2025
2024_1.2025
2024_1.2022
2023_1.2022
2020_1.2020
2019_1.2019

Data layout

resources/data/
├── periods.php
└── 2025_2_2025/
    ├── provinces.php
    ├── regencies/{provinceCode}.php
    ├── districts/{regencyCode}.php
    └── villages/{districtCode}.php

Maintainer: sync from BPS

These CLI tools fetch from SIG BPS and rewrite static files. Not needed in production apps — only for package maintainers (or forks updating data).

# Refresh period list
php bin/update-periods --force

# Full pipeline for one period
php bin/update-all --period=2025_2.2025 --concurrency=8

# Per level
php bin/update-provinces --period=2025_2.2025
php bin/update-regencies --period=2025_2.2025 --concurrency=8
php bin/update-districts --period=2025_2.2025 --concurrency=8
php bin/update-villages --period=2025_2.2025 --concurrency=8

# Single parent
php bin/update-regencies --period=2025_2.2025 --parent=11

# Force overwrite local cache files
php bin/update-all --period=2025_2.2025 --force --concurrency=8

Default behavior skips existing files (resume-friendly). Use --force to refresh.

Notes

Consumers use the Wilayah class to read data.
Compilers / bin/update-* are for generating data from BPS, not for app runtime.
Regional data originates from BPS / Kemendagri; this package only provides structured access.
This project is not affiliated with BPS.

Changelog

See CHANGELOG.md.

License

MIT — see LICENSE.

siibnu / wilayah-indonesia-bps

Maintainers

Package info

Statistics

Security