NAME

Geo::Postcodes::NO - Norwegian postcodes with associated information

SYNOPSIS

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

OBJECTS

use Geo::Postcodes::NO;

my $postcode = '1178'; # My postcode.

if (Geo::Postcodes::NO::valid($postcode)) # A valid postcode?
{
  my $P = Geo::Postcodes::NO->new($postcode);

  printf "Postcode         '%s'.\n", $P->postcode();
  printf "Postal location: '%s'.\n", $P->location();
  printf "Borough number:  '%s'.\n", $P->borough_number();
  printf "Borough:         '%s'.\n", $P->borough();
  printf "County:          '%s'.\n", $P->county();
  printf "Postcode type:   '%s'.\n", $P->type(); 
  printf "- in norwegian:  '%s'.\n", $P->type_verbose(); 
  printf "- in english:    '%s'.\n", $P->Geo::Postcodes::type_verbose(); 
}

The test for a valid postcode can also be done on the object itself, as it will be undef when passed an illegal postcode (and thus no object at all.)

my $P = Geo::Postcodes::NO->new($postcode);

if ($P) { ... }

A more compact solution:

if ($P = Geo::Postcodes::NO->new($postcode))
{
  foreach my $method (Geo::Postcodes::NOmethods())
  {
    printf("%-20s %s\n", ucfirst($method), $P->$method())
  }
}

This will not show the neglish description of the type.

PROCEDURES

use Geo::Postcodes::NO;

my $postcode = "1178";

if (Geo::Postcodes::NO::valid($postcode))
{
  printf "Postcode"        '%s'.\n", $postcode;
  printf "Postal location: '%s'.\n", location_of($postcode);
  printf "Borough number:  '%s'.\n", borough_number_of($postcode);
  printf "Borough:         '%s'.\n", borough_of($postcode);
  printf "County:          '%s'.\n", county_of($postcode);
  printf "Postcode type:   '%s'.\n", type_of($postcode); 
  printf "Postcode type:   '%s'.\n", type_of($postcode); 
  printf "- in norwegian:  '%s'.\n", type_of_verbose($postcode); 
  printf "- in english:    '%s'.\n", Geo::Postcodes::type_of_verbose($postcode); 
}

ABSTRACT

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

DESCRIPTION

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

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

EXPORT

None.

METHODS

The module supports the following methods: 'postcode', 'location', 'borough_number', 'borough', 'county', 'type', and -type_verbose'. This list can also be obtained with the call Geo::Postcodes::NO::methods().

DEPENDENCIES

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

PROCEDURES and METHODS

These functions can be used as methods or procedures.

is_method

my $boolean = Geo::postcodes::NO::is_method($method);
my $boolean = $postcode_object->is_method($method);

Does the specified method exist.

methods

my @methods = Geo::postcodes::NO::methods();
my @methods = $postcode_object->methods();

A list of legal methods.

selection

See the Geo::Postcodes manual for a description of this powerfull feature.

PROCEDURES

Note that the xxx_of procedures return undef when passed an illegal argument. They are used internally by the object constructor (new).

legal

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

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

valid

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

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

location_of

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

The postal location associated with the specified postcode.

borough_number_of

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

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

kommunenr2kommune

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

The name of the borough (kommune) with the specified borough number.

borough_of

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

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

county_of

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

The name of the county (fylke) where the postcode 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 $type = Geo::Postcodes::NO::type_of($number);

type_verbose_of

my $danish_description  = Geo::postcodes::NO::type_verbose_of($postcode);
my $english_description = Geo::postcodes::type_verbose_of($postcode);

A norwegian text describing the type. Use the base class for the english description.

See the 'TYPE' section for a description of the types.

type2verbose

Get the description of the specified type.

my $norwegian_description = Geo::Postcodes::NO::type2verbose($type);
my $english_description   = Geo::Postcodes::type2verbose($type);

METHODS

new

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

Create a new postcode object. Internally this will call the xxx_of procedures for the fields supported by this class.

The constructor will return undef when passed an invalid or illegal postcode. Do not try method calls on it, as it is not an object. See the description of the legal and valid procedures above.

postcode

my $postcode = $P->postcode();

The postcode, as given to the constructor (new).

location

my $location = $P->location();

The postal location associated with the specified postcode.

borough_number

my $borough_number = $P->borough_number();

The number of the borough (kommune) where the postcode is located. This is an official norwegian identifier.

borough

my $borough = $P->borough();

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

county

my $county = $P->county();

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

type

my $type = $P->type();

See the description of the procedure type_of above.

type_verbose

See the description of the procedure type_verbose_of above.

my $type_norwegian = $P->type_verbose();
my $type_english   = $P->Geo::Postcodes::type_verbose();

Use this to get the description.

See the 'TYPE' section for a description of the types.

TYPE

This class supports the following types for the postal locatuons:

BX: Postbokser (Post Office box)
ST: Gateadresser (Street address)
SX: Serviceboks (Service box )
IO: Kunde med eget postnummer (Individual owner)
STBX: Både gateadresser og postbokser (Either a Street address or a Post Office box)
MU: Flere bruksområder (felles) (Multiple usage)

CAVEAT

POSTCODES

The 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 invalid postcode.

An attempt to access the methods of a non-existent postcode 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 (not to be confused with the postcodes), 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 locations and borough and county names. Usage of other character sets may cause havoc. Unicode is not tested.

Note that the case insensitive search (in the 'selection' method/procedure) doesn't recognize an 'Æ' as an 'æ' (and so on). use locale in the application program should fix this, if the current locale supports these characters.

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

AUTHOR

Arne Sommer, <perl@bbop.org>

COPYRIGHT AND LICENSE

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

2 POD Errors

The following errors were encountered while parsing the POD:

Around line 5563:: Non-ASCII character seen before =encoding in 'Både'. Assuming CP1252
Around line 5573:: You forgot a '=back' before '=head1'

To install Geo::Postcodes::NO, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Geo::Postcodes::NO

CPAN shell

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

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

OBJECTS

PROCEDURES

ABSTRACT

DESCRIPTION

EXPORT

METHODS

DEPENDENCIES

PROCEDURES and METHODS

is_method

methods

selection

PROCEDURES

legal

valid

location_of

borough_number_of

kommunenr2kommune

borough_of

county_of

kommunenr2fylke

type_of

type_verbose_of

type2verbose

METHODS

new

postcode

location

borough_number

borough

county

type

type_verbose

TYPE

CAVEAT

POSTCODES

LEGAL BOROUGH NUMBERS

CHARACTER SET

SEE ALSO

AUTHOR

COPYRIGHT AND LICENSE

Module Install Instructions