view release on metacpan or  search on metacpan

lib/Geo/Address/Mail/Standardizer/USPS/AMS/Results.pm  view on Meta::CPAN

use Message::Stack;
use Message::Stack::Message;
use MooseX::Storage;
with qw(MooseX::Storage::Deferred);

=head1 NAME

Geo::Address::Mail::Standardizer::USPS::AMS::Results - results object from the USPS Address Matching System

=head1 SYNOPSIS

 my $address = new Geo::Address::Mail::US;
 my $ms      = new Geo::Address::Mail::Standardizer::USPS::AMS;
 my $result  = $ms->standardize($addr);

 $result->address;    # new standardized Geo::Address::Mail::US object
 $result->multiple;   # boolean indicating whether multiple addresses are returned.
 $result->single;     # boolean indicating whether a single address was returned.
 $result->found;      # integer indicating the number of candidates
 $result->error;      # string with an error message
 $result->default;    # boolean indicating a Z4_DEFAULT return code, which means:
                      #  "An address was found, but a more specific address could be
                      #  found with more information"
 $result->candidates; # reference to an array of Geo::Address::Mail::US objects, all
                      #  of which are possible matches
 $result->changed;    # A hashref whose values are key => 1 pairs indicating which
                      #  fields were changed during standardization

 $result->standardized_address; # The standardized address, in the case of a single
                                # matching address

=head1 DESCRIPTION

The results of a call to Geo::Address::Mail::Standardizer::USPS::AMS's standardize method.

=cut

extends 'Geo::Address::Mail::Standardizer::Results';

use Geo::Address::Mail::US;
use Moose::Util::TypeConstraints;

our $VERSION = '0.05';

subtype 'Address'		=> as 'Geo::Address::Mail::US';
subtype 'AddressList'	=> as 'ArrayRef[Address]';

coerce 'Address'
	=> from 'HashRef'
	=> via { new Geo::Address::Mail::US $_ };

coerce 'AddressList'
	=> from 'ArrayRef[HashRef]'
	=> via { [ map { new Geo::Address::Mail::US $_ } @$_ ] };

has error		=> (is => 'ro', isa => 'Str|Undef', predicate => 'has_error');
has found		=> (is => 'ro', isa => 'Int', predicate => 'has_found');
has default		=> (is => 'ro', isa => 'Bool', predicate => 'has_default');
has single		=> (is => 'ro', isa => 'Bool', predicate => 'has_single');
has multiple	=> (is => 'ro', isa => 'Bool', predicate => 'has_multiple');
has changed		=> (is => 'ro', isa => 'HashRef', predicate => 'has_changed');
has footnotes	=> (is => 'ro', isa => 'HashRef', predicate => 'has_footnotes');
has messages	=> ( is => 'ro', isa => 'Message::Stack', lazy_build => 1);

has candidates =>
	is		=> 'ro',
	isa		=> 'AddressList',
	coerce	=> 1,
	traits	=> [ 'Array' ],
	handles	=>
	{
		has_candidates	=> 'count',
		num_candidates	=> 'count',
		get_candidate	=> 'get',
	};

has '+standardized_address' =>
	isa		=> 'Address',
	coerce	=> 1;


sub _build_messages {
    my $self = shift;

    # These are the footnotes direct from the USPS AMS API docs
    my $codes = {

		# The address was found to have a different 5-digit ZIP Code than given in the
		# submitted list. The correct ZIP Code is shown in the output address.
        'A' => Message::Stack::Message->new(
			id => 'zip_code_corrected',
			level => 'info',
			scope => 'standardization',
			subject => 'zip',
			text => 'ZIP Code Corrected',
		),

		# The spelling of the city name and/or state abbreviation in the submitted address
		# was found to be different than the standard spelling. The standard spelling of the
		# city name and state abbreviation are shown in the output address.
        'B' => Message::Stack::Message->new(
			id => 'city_state_corrected',
			level => 'info',
			scope => 'standardization',
			subject => 'address',
			text => 'City/State Corrected',
		),

		# The ZIP Code in the submitted address could not be found because neither a
		# valid city, state, nor valid 5-digit ZIP Code was present. It is also recommended
		# that the requestor check the submitted address for accuracy.
        'C' => Message::Stack::Message->new(
			id => 'invalid_city_state_zip',
			level => 'error',
			scope => 'standardization',
			subject => 'zip',
			text => 'Invalid City/State/ZIP',
		),

		# This is a record listed by the United States Postal Service on the national
		# ZIP+4 file as a non-deliverable location. It is recommended that the requestor
		# verify the accuracy of the submitted address.