NAME

Geo::postcodes::NO - Norwegian postal codes with names

SYNOPSIS

This module can be used object oriented, or as procedures. Take your pick.

OBJECT ORIENTED

use Geo::postcodes::NO qw(valid);

my $pnr = '1178'; # My postal code.

if (valid($pnr)) # A valid postal code? { my $P = Geo::postcodes::NO->new($pnr);

print "Postcode"        '" . $P->$pnr              . "'.\n";
print "Postal location: '" . $P->location_of       . "'.\n";
print "Borough number:  '" . $P->borough_number_of . "'.\n";
print "Borough:         '" . $P->borough_of        . "'.\n";
print "County:          '" . $P->county            . "'.\n";
print "Postcode type:   '" . $P->type              . "'.\n"; 
}

The test for a valid postal code can also be expressed this way:

my $P = Geo::postcodes::NO->new($pnr);

if ($P) { ... }

PROCEDURES

use Geo::postcodes::NO ':all';

my $postcode = "1178";

if (valid($postcode)) { print "Postcode" '" . $postcode . "'.\n"; print "Postal location: '" . location_of($postcode). "'.\n"; print "Borough number: '" . borough_number_of($postcode). "'.\n"; print "Borough: '" . borough_of($postcode). "'.\n"; print "County: '" . county_of($postcode). "'.\n"; print "Postcode type: '" . type_of($postcode). "'.\n"; }

ABSTRACT

Geo::postcodes::NO - Perl extension for the mapping between norwegian postal codes, postal names, and the local administrative entities of boroughs (kommuner) and counties (fylker).

DESCRIPTION

Tired og entering the postal name all the time? This is not necessary, as it is uniquely defined from the postal code. Request the postal code only, and use this library to get the postal name.

The library can also tell you in which borough (kommune) by name or number and county (fylke) by name the postal code is located. The borough number can be handy, as it is used when reporting wages and tax to the Norwegian Tax Administration

EXPORT

None by default.

The procedures can be imported individually, or en block with use Geo::postcodes::NO ':all';.

DEPENDENCIES

This module is a subclass of Geo::Postcodes, which must be installed separately.

PROCEDURES

Note that the xxx_of procedures return undef when passed an illegal argument.

legal

my $boolean = Geo::postcodes::NO::legal($number);

Do we have a legal postal code; a code that follows the syntax rules?

valid

my $boolean = Geo::postcodes::NO::valid($number);

Do we have a valid postal code; a code in actual use?

location_of

my $poststed = Geo::postcodes::NO::location_of($number);

The postal location associated with the specified postal code.

borough_number_of

my $kommunenr = Geo::postcodes::NO::borough_number_of($number);

The number of the borough (kommune) where the postal code is located.

kommunenr2kommune

my $kommune = Geo::postcodes::NO::kommunenr2kommune($number);

The name of the borough (kommune), given the borough number.

borough_of

my $kommune = Geo::postcodes::NO::borough_of($number);

The name of the borough (kommune) where the postal code is located.

county_of

my $fylke = Geo::postcodes::NO::county_of($number);

The name of the county (fylke) where the postal code is located.

kommunenr2fylke

my $fylke = Geo::postcodes::NO::kommunenr2fylke($number);

The name of the county (fylke) where the specified borough number (kommune nummer) is located.

type_of

my $kategori = Geo::postcodes::NO::type_of($number);

What kind of postal code is this. Possible values are: "Både gateadresser og postbokser", "Flere bruksområder (felles)", "Gateadresser", "Kunde med eget postnummer", "Postbokser", and "Serviceboks".

This information is not especially useful.

METHODS

new

my $P = Geo::postcodes::NO->new($number);

Create a new postal code object.

The constructor will return undef when passed an illegal postal code. Legal postal codes consist of four digits, and must also be in use.

Either check the postal code with legal before this call, or test it afterwards; if ($P) { ... }.

postcode

my $postcode = $P->postcode;

The postal code.

location

my $location = $P->location;

The postal place associated with the specified postal code.

borough_no

my $borough_number = $P->borough_no;

The number of the borough (kommune) where the postal code is located.

borough

my $borough = $P->borough;

The name of the borough (kommune) where the postal code is located.

county

my $county = $P->county;

The name of the county (fylke) where the postal code is located.

type

my $postal_type = $P->type;

See the description of the procedure type_of above.

CAVEAT

This module uses "inside out objects".

POSTCODES

Norwegain postcodes are four digit numbers, in the interval "0000" to "9999" (and this means that "0010" is legal, while "10" is not).

Use legal to check for legal postcodes, and valid to check if the postcode is actually in use. Geo::postcodes::NO-new($postcode)> will return undef if passed an illegal or invalif postcode.

Attempts to access the methods of a non-existent postal code object will result in a runtime error. This can be avoided by checking if the postal code is legal, before creating the object; valid($postcode) returns true or false.

LEGAL BOROUGH NUMBERS

Borough (Kommune) numbers are also four digit numbers, in the interval "0101" to "2399". The two first digits identifies the county (fylke).

CHARACTER SET

The library was written using the ISO-8859-1 (iso-latin1) character set, and the special norwegian letters 'Æ', 'Ø' and 'Å' occur regularly in the postal places and borough and county names. Usage of other character set may cause havoc. Unicode is not tested.

Note that all names are given in UPPER CASE. This is courtesy of the norwegian postal services.

SEE ALSO

The latest version of this library should always be available on CPAN, but see also the library home page; http://bbop.org/perl/GeoPostcodes.

AUTHOR

Arne Sommer, <arne@cpan.org>

COPYRIGHT AND LICENSE

Copyright (C) 2006 by Arne Sommer

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

cpanm Geo::Postcodes::NO

perl -MCPAN -e shell
install Geo::Postcodes::NO