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.

Building the database

To build the database, use the scripts in the xt directory of the distribution. You need to edit these scripts to point to the files you want to use.

The script update.pl uses the Geo::Postcodes::JP::Update module to update the CSV files on your hard disk 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 module PostCodeFiles.pm found in the xt directory. The user needs to edit this file 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.

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. The return value is a hash reference with the following keys.

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.

#line 86 "Main.pm.tmpl"

SEE ALSO

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.

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.