The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
Geo-Postcodes-JP-0.007
/ Geo::Postcodes::JP

NAME

Geo::Postcodes::JP - handle the Japan Post Office postal code data

SYNOPSIS

    my $gpj = Geo::Postcodes::JP->new (
        db_file => '/path/to/database/file',
    );
    my $address = $gpj->postcode_to_address ('3050053');
    # Now $address contains the address as a hash reference.

DESCRIPTION

This package contains a series of modules for handling the files of postcodes supplied by Japan Post. Geo::Postcodes::JP::Update downloads the data files. Geo::Postcodes::JP::Process parses the data files, and can improve the data. Geo::Postcodes::JP::DB inserts the postcode data read by the processing module into an SQLite database. The main module provides a way to access the postcodes in an existing SQLite database.

METHODS

new

    my $gpj = Geo::Postcodes::JP->new (
        db_file => '/path/to/database/file',
    );

"New" creates a new postcode-lookup object. The parameter is the path to the database file, which is the file created in the stage "Building the database" above.

postcode_to_address

    my $address = $gpj->postcode_to_address ('9012204');

Given a postcode, get the corresponding address details. If the postcode is found, the return value is an array reference containing one or more hash references with the following keys. If the postcode is not found, the return value is the undefined value.

postcode

The seven-digit postcode itself, for example 0708033.

ken_kanji

The kanji form of the prefecture name, for example 北海道.

ken_kana

The kana form of the prefecture name, for example ホッカイドウ.

city_kanji

The kanji form of the city name, for example 旭川市. In some instances this data will consist of "gun" and "machi" or "shi" and "ku" information rather than just a city name, depending on the information in the Japan Post Office file itself.

city_kana

The kana form of the city name, for example アサヒカワシ.

address_kanji

The final part of the address in kanji, for example 神居町雨紛.

address_kana

The final part of the address in kana, for example カムイチョウウブン.

If the postcode is a jigyosyo postcode, the result also contains

jigyosyo_kanji

The kanji name of the place of business.

jigyosyo_kana

The kana name of the place of business. This, unfortunately, is with small versions of kana all converted into large ones, because this is the format supplied by the post office.

street_number

This is the specific address of the place of business.

Building the database

The module comes with abbreviated versions of the input CSV files and generates short versions of the database for its testing.

To build the full version of the database, it is necessary to download and process the post office's files. These files are not included in the distribution because they are very large files and change monthly.

The scripts required are in the xt directory of the distribution. These files must be edited to point to the location of the input files and the database files on the user's system.

The script update.pl uses the Geo::Postcodes::JP::Update module to update the CSV files on the user's local storage from the Japan Post Office web site. It downloads two files, ken_all.zip and jigyosyo.zip. The user then needs to unzip these files.

The script insert-all.pl inserts the file KEN_ALL.CSV into a database specified in the helper module PostCodeFiles.pm found in the xt directory. The user needs to edit the helper module to point to whereever the database files should be created. The script insert-jigyosyo.pl inserts the JIGYOSYO.CSV into the database specified. Again, the user needs to edit the PostCodeFiles.pm module to specify where things should go.

SEE ALSO

http://www.post.japanpost.jp/zipcode/download.html: This is the main page for Japan Post's data downloads. Unfortunately the download page is not available in English. (If you want to find the download URLs but cannot read Japanese, the accompanying module Geo::Postcodes::JP::Update contains the URLs needed to download the data without having to search through this page for the correct address.)

Number::ZipCode::JP - validate Japanese zip-codes. This is a huge regular expression made from the same data file which this module reads, which can be used to validate a Japanese postal code.

http://www.lemoda.net/japan/postcodes/index.html: This is the module author's "scrapbook" page containing information from the internet about the postcode file. It includes links to relevant blog posts and links to software systems for handling the data.

TERMINOLOGY

Postcode

In this module, "postcode" is the translation used for the Japanese term "yuubin bangou" (郵便番号). They might be called "postal codes" or even "zip codes" by some.

This module only deals with the seven-digit modern postcodes introduced in 1998. It does not handle the three and five digit postcodes which were used until 1998.

Ken

In this module, "ken" in a variable name means the Japanese system of prefectures, which includes the "ken" divisions as well as the "do/fu/to" divisions, with "do" used for Hokkaido, "fu" for Osaka and Kyoto, and "to" for the Tokyo metropolis. These are got from the module using the word "ken".

See also the sci.lang.japan FAQ on Japanese addresses.

City

In this module, "city" is the term used to point to the second field in the postcode data file. Some of these are actually cities, like "Mito-shi" (水戸市), the city of Mito in Ibaraki prefecture. However, some of them are not really cities but other geographical subdivisions, such as gun/machi or shi/ku combinations.

address

In this module, "address" is the term used to point to the third field in the postcode data file. This is called 町域 (chouiki) by the Post Office.

For example, in the following data file entry, "3100004" is the postcode, "茨城県" (Ibaraki-ken) is the "ken", "水戸市" (Mito-shi) is the "city", and "青柳町" (Aoyagicho) is the "address".

    08201,"310  ","3100004","ｲﾊﾞﾗｷｹﾝ","ﾐﾄｼ","ｱｵﾔｷﾞﾁｮｳ","茨城県","水戸市","青柳町",0,0,0,0,0,0
Jigyosyo

In this module, "jigyosyo" is the term used to point to places of business. Some places of business have their own postcodes.

The term "jigyosyo" is used because it is the post office's own romanization, but this is actually an error and should be either jigyōsho or zigyôsyo in standard romanizations of Japanese, or jigyosho in simplified Hepburn. See the Sci.Lang.Japan FAQ page on Japanese romanization.

Street number

In this module "street number" is an arbitrary way of describing the final part of the address, which may actually specify a variety of things, such as the ban-chi, or even what floor of a building the postcode refers to.

The street number field is mostly relevant for the jigyosyo postcodes, but also crops up in some of the addresses, especially for rural areas.

AUTHOR

Ben Bullock, <bkb@cpan.org>

COPYRIGHT AND LICENSE

Geo::Postcodes::JP and associated files are copyright (c) 2012 Ben Bullock.

You may use, copy, modify and distribute Geo::Postcodes::JP under the same terms as the Perl programming language itself.

1 POD Error

The following errors were encountered while parsing the POD:

Around line 115:

Expected text after =item, not a bullet