The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Geo-Postcodes-JP-0.014
++
/ Geo::Postcodes::JP::DB

NAME

Geo::Postcodes::JP::DB - database of Japanese postal codes

SYNOPSIS

    my $o = Geo::Postcodes::JP::DB->new (
        db_file => '/path/to/sqlite/database',
    );
    my $address = $o->lookup_postcode ('3050054');
    print $address->{ken};
    # Prints 茨城県

DESCRIPTION

This module offers methods to create and access an SQLite database of Japanese postcodes.

METHODS

All of these methods make use of an SQLite database file. All of the fields suffixed with _id are identification numbers of the SQLite database itself.

search_placename

    $placename_id = $o->search_placename ($type, $kanji, $kana);

Generic search for a placename of type $type by kanji name $kanji and kana name $kana. This is only used for the "ken" and the "jigyosyo" tables, because city and address names are ambiguous.

    $city_id = $o->city_search ($kanji, $ken_id);

Search for a city named $kanji in prefecture identified by $ken_id. There are some examples of cities with the same names in different prefectures. For example there is a 府中市 (Fuchuu-shi) in Tokyo and one in Hiroshima prefecture. Thus a "city_search" routine rather than the "search_placename" generic search is needed for cities.

    $address_id = $o->address_search ($kanji, $kana, $city_id);

Search for an "address" in a particular city, specified by $city_id.

search_placename_kanji

    my $place_id = $o->search_placename_kanji ($type, $kanji);

Like "search_placename", but search for a place name using only the kanji for the name.

insert_postcode

    $o->insert_postcode ($postcode, $address_id);

Insert a postcode $postcode into the table of postcodes with corresponding address $address_id. The address identification number, $address_id, is usually got from "address_insert" or "address_search". This method is for addresses which are not jigyosyo (places of business). Addresses for places of business should use "jigyosyo_insert_postcode".

jigyosyo_insert_postcode

    $o->jigyosyo_insert_postcode ($postcode, $address_id, $jigyosyo_id);

Insert a postcode for a "jigyosyo" identified by $jigyosyo_id into the table. $Jigyosyo_id is usually got from "jigyosyo_insert". $Address_id is as described in the documentation of "insert_postcode".

jigyosyo_insert

    my $jigyosyo_id = $o->jigyosyo_insert ($kanji, $kana, $street_number);

Insert a "jigyosyo" into the table of them with kanji $kanji, kana $kana, street number $street_number, and return the ID number of the entry.

ken_insert

    my $ken_id = $o->ken_insert ($kanji, $kana);

Insert a prefecture into the table of prefectures with the name $kanji in kanji and $kana in kana.

city_insert

    my $city_id = $o->city_insert ($kanji, $kana, $ken_id);

Insert a city into the table of cities with kanji name $kanji, kana name $kana, which is in the prefecture specified by $ken_id.

$Ken_id specifies the prefecture to which the city belongs.

address_insert

    my $address_id = $o->address_insert ($kanji, $kana, $city_id);

Insert an address into the table of addresses with kanji name $kanji, kana name $kana, and city ID $city_id. This is an internal routine used in the construction of the database from the data file.

db_connect

    $o->db_connect ('/path/to/database/file');

Connect to the database specified.

insert_postcodes

    $o->insert_postcodes ($postcodes);

Insert the postcodes in the array reference $postcodes into the database specified by "new".

insert_postcode_file

    insert_postcode_file (
        db_file => '/path/to/database/file',
        postcode_file => '/path/to/postcode/file',
    );

Insert the postcodes in the file specified by postcode_file into the database specified by db_file.

This uses the read_ken_all method of Geo::Postcodes::JP::Process to read the data, and the improve_postcodes function of the same module to improve the data.

lookup_address

    my $address_id = $o->lookup_address (
        ken => '沖縄県',
        city => '宜野湾市',
        address => '上原',
    );

Look up an address id number from the kanji versions of the prefecture name, the city name, and the address name.

add_jigyosyo

    $o->add_jigyosyo (
        db_file => '/path/to/database/file',
        jigyosyo_file => '/path/to/jigyosyo.csv',
    );

Add the list of place-of-business postcodes from jigyosyo_file to the database specified by db_file.

lookup_jigyosyo

    my $jigyosyo = lookup_jigyosyo ($jigyosyo_id);

Given a jigyosyo id number, return its kanji and kana names and its street number in a hash reference.

lookup_postcode

    my $addresses = $o->lookup_postcode ('3108610');
    print $address->[0]->{ken}->{kanji}, "\n";
    # Prints 茨城県

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.

new

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

Create a new database-handling object. See also "create_database" to create a database file without data, and "make_database" to create the database file and insert its data.

FUNCTIONS

create_database

    my $o = create_database (
        db_file => '/path/to/file',
    );

Create the SQLite database specified by db_file.

The return value is a database handling object as returned by "new".

make_database

    my $o = make_database (
        db_file => '/path/to/database/file',
        postcode_file => '/path/to/postcode/file',
    );

Make the database specified by db_file from the data in postcode_file. The schema is supplied in the lib/Geo/Postcodes/JP/DB/ subdirectory of the distribution in the file schema.sql. This uses "create_database" to create the database and "insert_postcode_file" to insert the data into the database.

The return value is the database handling object, as returned by "new".

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.