Geo::Address::Mail - A Mailing Address on Earth


Geo::Address::Mail provides a generic object representation of a mailing address that may be subclassed to provide more specific typing of attributes. The core class, Geo::Address::Mail provides common, loosely typed attributes and methods.

    use Geo::Address::Mail::US;

    my $add = Geo::Address::Mail::US->new(
        name => 'Cory G Watson',
        street => '123 Main St',
        city => 'Testville',
        postal_code => '12345'


The real reason for Geo::Address::Mail is to provide a common class that can be used to build mailing address objects for other countries.

Subclasses are expected additional type refinement and attributes. For example, Geo::Address::Mail::US uses a more specific type for validation USPS ZIP codes and adds a street2 attribute for an optional additional line of addressing.


Subclasses should be named with Geo::Address::Mail and the two-letter ISO-3166 country codes.


Using a common address object enables a family of distributions that provide interesting address functionality such as Geo::Address::Mail::Standardizer.



The city/town/village/municipality in which this address resides.


The name of the company that is to receive the mail piece.


The country in which this address resides. This is likely not necessary unless the address is in a different country.


The name of the person that is to receive the mail piece.


The postal code of the address. Called the ZIP code in the US.


The number and name of the street that is to receive the mail piece.

  2020 Main St



Close this Geo::Address::Mail instance, replacing any of the attributes specified in the new instance.

new_for_country ($code, ...)

Attempts to load and instantiate a subclass of Geo::Address::Mail based on the provided two-letter code (upper or lower case). Any remaining arguments are passed to the constructor of the specified class. Note: you will have to have the class for the specified country accessible.

  # Instantiate a US address
  my $usaddr = Geo::Address::Mail->new_for_country('US', { ... });

standardize ($partial_name_of_standardizer_class, ...)

Shortcut to use a Geo::Address::Mail::Standardizer. You can provide either the partial name (the bits after Standardizer, e.g. 'USPS::AMS' for Geo::Address::Mail::Standardizer::USPS::AMS) or a full class name (prefixed with a +, e.g. '+My::Standardizer'). Returns whatever is returned by the standardize method of the requested Standardizer implementation.

Note: Any argument passed after the name of the class will be passed on to the constructer of the loaded standardizer.


Cory G Watson, <gphat at>



Copyright 2010 Cory G Watson.

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See for more information.