README

English | 日本語

Prefecture provides structured data about all Japanese prefectures, including their names in various scripts (Kanji, Hiragana, Katakana, English), region information, and identifier numbers. It is useful for applications that need to handle Japanese geographic data in a consistent and normalized way.

Installation

composer require bvp/prefecture

Usage

<?php

require __DIR__ . '/vendor/autoload.php';

use BVP\Prefecture\Prefecture;

Available Methods

Each method also supports List variants like byNameList() or byRegionNameList() for multiple inputs.

Retrieve All Prefectures

/**
 * @return array
 */
$prefectures = Prefecture::all();

print_r($prefectures);

// Output:
Array
(
    [1] => Array
        (
            [number] => 1
            [name] => 北海道
            [short_name] => 北海道
            [hiragana_name] => ほっかいどう
            [katakana_name] => ホッカイドウ
            [english_name] => hokkaido
            [region_number] => 1
            [region_name] => 北海道地方
            [region_short_name] => 北海道
        )
    [2] => Array(...) // Aomori
    [3] => Array(...) // Iwate
    ...
    [46] => Array(...) // Kagoshima
    [47] => Array(...) // Okinawa
)

Filter by Prefecture Number

/**
 * @return ?array
 */
$prefecture = Prefecture::byNumber(13);
// or $prefecture = Prefecture::byNumber([13]);

print_r($prefecture);

// Output:
Array
(
    [number] => 13
    [name] => 東京都
    [short_name] => 東京
    [hiragana_name] => とうきょうと
    [katakana_name] => トウキョウト
    [english_name] => tokyo
    [region_number] => 3
    [region_name] => 関東地方
    [region_short_name] => 関東
)

Filter by Prefecture Name

/**
 * @return ?array
 */
$prefecture = Prefecture::byName('東京都');
// or $prefecture = Prefecture::byName(['東京都']);

Filter by Prefecture Short Name

/**
 * @return ?array
 */
$prefecture = Prefecture::byShortName('東京');
// or $prefecture = Prefecture::byShortName(['東京']);

Filter by Prefecture Hiragana Name

/**
 * @return ?array
 */
$prefecture = Prefecture::byHiraganaName('とうきょうと');
// or $prefecture = Prefecture::byHiraganaName(['とうきょうと']);

Filter by Prefecture Katakana Name

/**
 * @return ?array
 */
$prefecture = Prefecture::byKatakanaName('トウキョウト');
// or $prefecture = Prefecture::byKatakanaName(['トウキョウト']);

Filter by Prefecture English Name

/**
 * @return ?array
 */
$prefecture = Prefecture::byEnglishName('tokyo');
// or $prefecture = Prefecture::byEnglishName(['tokyo']);

Filter by Region Number

/**
 * @deprecated It returns only a single result even if multiple prefectures match. Use Prefecture::byRegionNumberList() instead.
 * @return ?array
 */
$prefecture = Prefecture::byRegionNumber(3);
// or $prefecture = Prefecture::byRegionNumber([3]);

Filter by Region Name

/**
 * @deprecated It returns only a single result even if multiple prefectures match. Use Prefecture::byRegionNameList() instead.
 * @return ?array
 */
$prefecture = Prefecture::byRegionName('関東地方');
// or $prefecture = Prefecture::byRegionName(['関東地方']);

Filter by Region Short Name

/**
 * @deprecated It returns only a single result even if multiple prefectures match. Use Prefecture::byRegionShortNameList() instead.
 * @return ?array
 */
$prefecture = Prefecture::byRegionShortName('関東');
// or $prefecture = Prefecture::byRegionShortName(['関東']);

Filter by Multiple Criteria (Lists)

/**
 * @return ?array
 */
$prefectures = Prefecture::byNumberList(13, 34);
// or Prefecture::byNumberList([13, 34]);

/**
 * @return ?array
 */
$prefectures = Prefecture::byNameList('東京都', '広島県');
// or Prefecture::byNameList(['東京都', '広島県']);

/**
 * @return ?array
 */
$prefectures = Prefecture::byRegionNumberList(3, 6);
// or Prefecture::byRegionNumberList([3, 6]);

/**
 * @return ?array
 */
$prefectures = Prefecture::byRegionNameList('関東地方', '中国地方');
// or Prefecture::byRegionNameList(['関東地方', '中国地方']);

Data Format

The prefecture codes used in this library are based on JIS X 0401 (Japanese Prefecture Codes), with leading zeros removed and represented as integers.

Why use this?

Consistent and normalized prefecture data for Japanese apps
Multiple name formats supported (Kanji, Hiragana, Katakana, English)
Easy to filter by region or name

License

Prefecture is open source software licensed under the MIT license.

bvp / prefecture

Maintainers

Details