Search by

otaqq / admin-divisions

otaqq

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.

Package info

github.com/otaqq/admin-divisions

pkg:composer/otaqq/admin-divisions

Statistics

Installs: 17

Dependents: 0

Suggesters: 0

Stars: 0

Open Issues: 0

v0.1.0 2026-11-15 11:31 UTC

This package is auto-updated.

Last update: 2026-11-15 14:40:26 UTC


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 in countries/<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.