otaqq / admin-divisions
Administrative divisions from official sources (Japan's prefectures and municipalities from the Digital Agency's Address Base Registry), with a diff to keep your own tables up to date. One spec, many languages; this is the PHP package.
Requires
- php: ^8.3
- ext-zip: *
Requires (Dev)
- phpunit/phpunit: ^11.5|^12.5
Suggests
None
Provides
None
Conflicts
None
Replaces
None
README
Administrative divisions — prefectures, states, municipalities — straight from official sources, and a diff to keep your own tables up to date.
Most apps keep a table of regions for address forms and search filters. They are usually seeded once from a copied list, and then nobody notices when towns merge or are renamed. This library reads the official master of each country and tells you, by code, what is new, renamed or gone in your own rows.
- Official and current. The data is downloaded from the official source when you ask for it. Nothing is bundled, so nothing goes stale in
vendor/. - A diff, not a sync. It tells you what differs; your application decides how to apply it (insert, rename, disable, restore a soft-deleted row). No framework, no database layer.
- One spec, many languages. Each country has its rules in
countries/<code>/spec.md, checked by shared data incountries/<code>/conformance/. PHP comes first; Node.js, Ruby, Python, Go and Rust can follow the same specs.
Countries
| Country | Source | Spec |
|---|---|---|
Japan (jp) |
Address Base Registry, city master (Digital Agency, CC BY 4.0): prefectures (todofuken) and municipalities (shikuchoson) | countries/jp/spec.md |
| Others | later |
Status: pre-release (v0.1 in progress). See docs/roadmap.md.
Layout
| Path | What | Package |
|---|---|---|
| countries/jp | Japan: what every implementation does (spec.md) and the shared fixture and expected results (conformance/) |
— |
| lang/php | PHP implementation, one namespace per country (Otaqq\AdminDivisions\Jp) |
Composer otaqq/admin-divisions |
lang/node, lang/ruby, lang/python, lang/go, lang/rust |
Other languages | later |
Install (PHP)
composer require otaqq/admin-divisions
Japan (PHP)
Requires PHP 8.3 and ext-zip.
use Otaqq\AdminDivisions\Jp\Diff; use Otaqq\AdminDivisions\Jp\Master; $master = Master::download(); // or Master::fromFile('mt_city_all.csv.zip') foreach ($master->prefectures() as $prefecture) { echo $prefecture->code, ' ', $prefecture->name, PHP_EOL; // 01 北海道 } foreach ($master->municipalities('01') as $municipality) { echo $municipality->code(), ' ', $municipality->name(), PHP_EOL; // 01101 札幌市中央区 } $master->municipality('01303')?->name(); // 石狩郡当別町 (five- or six-digit code)
Keep your table up to date
Give Diff::compare() your rows as code => name:
$current = DB::table('cities')->pluck('name', 'code')->all(); // ['01101' => '札幌市中央区', …] $diff = Diff::compare($current, $master->municipalities()); foreach ($diff->added as $municipality) { /* insert */ } foreach ($diff->renamed as ['item' => $municipality, 'from' => $oldName]) { /* rename */ } foreach ($diff->removed as $code) { /* disable: users may still point at it */ }
Codes that PHP turned into integer array keys (13 for '13') are padded back.
Data
| What | Rule |
|---|---|
| Prefectures | Taken from the municipality rows (the master has no rows of its own for them) |
| Municipalities | Rows in use. Abolished codes are left out |
| Designated cities with wards | municipalities() lists the wards (札幌市中央区, …) and leaves out the city itself (札幌市), so a pull-down does not offer both. Pass withWardedCities: true to include it. municipality('01100') still finds it |
| Names | name() joins county, city and ward; kana() and roma() likewise |
The city master is published by the Digital Agency of Japan under CC BY 4.0. If you show or redistribute the data, credit the source, for example: 「出典:デジタル庁 アドレス・ベース・レジストリ(市区町村マスター)」.
Develop
Tools come from mise; PHP runs in Docker, so the host needs nothing else.
mise run setup # composer install mise run test # tests of every language (PHPUnit on the lowest supported PHP for now) A new language goes under `lang/<name>/`, follows each `countries/<code>/spec.md`, and reads `countries/<code>/conformance/` in its tests. A new country goes under `countries/<code>/` with its spec and conformance data, then into each language.
License
MIT. See LICENSE.