wilayah ships Indonesian administrative codes as SQL you can load today

Administrative codes change, and the old ones keep circulating

Every form that asks for a city in Indonesia has the same problem. The hierarchy of province, regency and city, district, subdistrict and village is fixed by a ministerial decree, and the decree is rewritten. A system that stored a hand-maintained list of codes is then wrong, quietly, in a way that only shows up as a rejected address or a wrong tax region. wilayah is a response to that: a repository whose primary content is the codes and the data attached to them, aligned with Kepmendagri No 300.2.2-2430 Tahun 2025, the regulation behind the current release. The primary language of the repository is SQL, and the main artefact is db/wilayah.sql. The demo at wilayah.cahyadsn.com, described as the apps version 3.2.0, shows the intended usage, a cascading selector driven by PHP, MySQL and AJAX. This is a dataset with a web front end attached, not a framework, and the dataset is the part worth taking.

Six SQL dumps, each with a different enrichment

The db/ directory is where the work is, and the files are not duplicates of one another. The main file is:

db/wilayah.sql
db/wilayah_level_1_2.sql
db/wilayah_pulau.sql
db/wilayah_penduduk.sql
db/wilayah_luas.sql

wilayah.sql carries the administrative codes and names under the 2025 decree. wilayah_level_1_2.sql is the enriched version for province and regency or city level, adding coordinates, elevation, timezone, area, population and boundaries. wilayah_pulau.sql holds the island data with latitude and longitude, island status marked as BP or TBP, area and notes. wilayah_penduduk.sql is population per province and per regency or city, and wilayah_luas.sql is the area figures. The enrichment comes from different sources than the codes. The area data is attributed both to Kepmendagri No 300.2.2-2430 Tahun 2025 and to Badan Informasi Geospasial, specifically a deputy director letter on area calculation for all of Indonesia, number B-16.10/DIGD-BIG/IGD.04.04/12/2024, dated 16 December 2024. So the coordinates, the area and the codes are not guaranteed to share a vintage.

The archive keeps the regulation history queryable

A large part of the value here is that the repository does not overwrite the past, it files it. The db/archive/ directory holds wilayah_2023.sql under Kepmendagri No 100.1.1-6117 Tahun 2022, wilayah_2022.sql under Permendagri No 58 Tahun 2021 revised by Kepmendagri No 050-145 Tahun 2022, wilayah_2020.sql under Permendagri No 72 Tahun 2019 revised by Kepmendagri No 146.1-4717 Tahun 2020, and wilayah_2018.sql and wilayah_2016.sql under Permendagri No 137 of 2017 and Permendagri No 56 of 2015. The island data has its own archive, pulau_2025.sql, pulau_2023.sql and pulau_2022.sql, and the enriched level_1_2 data exists in both a MySQL and a PostgreSQL variant, the latter named wilayah_level_1_2_postgresql.sql. The practical reason this matters is migration. When a regulation lands, an application with a stored province id cannot simply change its lookup table, because historical records point at the old codes. Having the old dumps in the same repository turns a migration into a lookup across two known datasets rather than a search through archived ministry documents.

The surrounding problems live in sibling repositories

The project has split its concerns across related repositories, and the README links each one. wilayah_kodepos holds postal codes against the administrative codes, which is the pairing that every checkout form eventually needs. wilayah_ref is a reference dataset for the codes and the island data. wilayah_boundaries provides boundary polygons keyed by administrative code. wilayah_logo provides logos or emblems keyed by the province and regency or city codes. wilayah_api is an implementation of an API over the region code data. That last one matters for a decision you have to make early. If your application is a web app with its own backend, loading the SQL into your own database is straightforward. If it is a mobile app or a service that should not carry a database, the API implementation is the piece to evaluate, and it lives in a different repository with its own release cycle. The boundary and logo datasets are also the ones with the highest storage cost, since polygons are heavy compared with a code list.

The PHP, MySQL and AJAX demo shows the intended integration

The demo application is the part of the repository that shows how the data is meant to be consumed, and the stack is deliberately old fashioned: PHP, MySQL and AJAX, with the apps/ directory in the tree, an index.php at the root, a css/ directory, a cache/ directory, composer.json and a package.json. The JavaScript side is minimal, and the package.json shows just one runtime dependency and one development dependency:

{
  "dependencies": {
    "jsdom": "^29.1.1"
  },
  "devDependencies": {
    "jest": "^30.5.1"
  }
}

The jest and jsdom pairing says the JavaScript in this project is tested with a simulated DOM, which is what you would expect from a front end whose job is to repopulate a cascading selector. The PHP side has phpunit.xml at the root and a tests/ directory, so the repository carries tests for both halves. There is also a docs/ directory, a change_log.md at the root and a .Jules/ directory, which is a marker that an automated agent has worked on the repository at some point. The demo is worth reading before you write your own, because the awkward parts of cascading Indonesian administrative selectors are all in it.

Versions follow the regulation, and the licence is permissive

The release tags are dated by month rather than by semver, with v2025.6 on 2025-06-27, v2025.7 on 2025-07-04 and v2026.7 on 2026-07-02, and the last push was on 2026-10-19. The pattern suggests a yearly refresh of the data, published when the regulation changes, with the tag marking the data vintage rather than a software release. That is the right way to version a dataset, and it also means a consumer should treat the tag as the compatibility key: a new tag can change codes underneath you, since the codes are the whole point of the file. The licence is MIT, with a LICENSE file at the root, so the dumps can be loaded into a commercial database, redistributed, and shipped inside a product without the copyleft obligations that a data licence would impose. The population figures carry an asterisk in the README, which is worth chasing down in the source data if your use of them is anything more than a display.

Where this dataset stops being enough

Three limits are worth naming. The first is scope: wilayah covers government administrative codes, and it is not a postal code database, not a geographic boundary service, and not a general gazetteer, so a system that needs addresses as well as regions has to combine this with wilayah_kodepos and possibly wilayah_boundaries. The second is vintage: the codes, the areas, the elevations, the timezones and the populations are drawn from different official documents, and where they disagree, wilayah does not reconcile them, it publishes them side by side. A distance calculation based on the area column and a population figure used for a funding formula may not refer to the same year. The third is that the data is a point-in-time snapshot of a regulation that will be replaced. The archive shows the replacement rate, with five archive dumps back to 2016 for the main codes, so any integration that stores a code has to decide, explicitly, how it will handle the next decree. A reasonable alternative for a smaller application is to keep only the levels you actually use, province and regency, and to treat the lower levels as a lookup service rather than as stored reference data, which reduces the cost of the next migration.

Editorial conclusion

wilayah is the pragmatic source for Indonesian administrative codes, because it ships the current regulation as a loadable dump instead of leaving you to transcribe it, and it keeps the previous regulations side by side so a system pinned to older codes does not break. It is not a general purpose geographical database, it does not attempt postal codes, and its area and population figures come from separate official sources that are not always the same vintage as the codes. Before adopting it, check the change_log.md for what moved between the version you use today and the current one, decide whether you need the enriched level_1_2 data or only the code hierarchy, and test the demo application against a MySQL instance before wiring it into a form.

Frequently asked questions

Official sources

1. cahyadsn/wilayah on GitHub
2. License: MIT
3. Project website
4. README
5. Releases