1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159
|
# $Id: CityStateLookup.pm 2360 2007-11-03 04:48:52Z comdog $
package Business::US::USPS::WebTools::CityStateLookup;
use strict;
no warnings 'uninitialized';
use base qw(Business::US::USPS::WebTools);
use subs qw();
use vars qw($VERSION);
$VERSION = '1.11';
=head1 NAME
Business::US::USPS::WebTools::CityStateLookup - lookup a City and State by Zip Code
=head1 SYNOPSIS
use Business::US::USPS::WebTools::AddressStandardization;
my $looker_upper = Business::US::USPS::WebTools::CityStateLookup->new( {
UserID => $ENV{USPS_WEBTOOLS_USERID},
Password => $ENV{USPS_WEBTOOLS_PASSWORD},
Testing => 1,
} );
my $hash = $looker_upper->lookup_city_state(
);
if( $looker_upper->is_error )
{
warn "Oh No! $looker_upper->{error}{description}\n";
}
else
{
print join "\n", map { "$_: $hash->{$_}" }
qw(FirmName Address1 Address2 City State Zip5 Zip4);
}
=head1 DESCRIPTION
*** THIS IS ALPHA SOFTWARE ***
This module implements the Address Standardization web service from the
US Postal Service. It is a subclass of Business::US::USPS::WebTools.
=cut
=over 4
=cut
sub _fields { qw( FirmName Address1 Address2 City State Zip5 Zip4 ) }
sub _required { qw( Address2 City State ) }
=item lookup_city_state( KEY, VALUE, ... )
The C<verify_address> method takes the following keys, which come
directly from the USPS web service interface:
FirmName The name of the company
Address1 The suite or apartment
Address2 The street address
City The name of the city
State The two letter state abbreviation
Zip5 The 5 digit zip code
Zip4 The 4 digit extension to the zip code
It returns an anonymous hash with the same keys, but the values are
the USPS's canonicalized address. If there is an error, the hash values
will be the empty string, and the error flag is set. Check is with C<is_error>:
$verifier->is_error;
See the C<is_error> documentation in Business::US::USPS::WebTools for more
details on error information.
=cut
sub lookup_city_state
{
my( $self, $zip_code ) = @_;
$self->_make_url( { Zip5 => $zip_code } );
$self->_make_request;
$self->_parse_response;
}
sub _api_name { "CityStateLookup" }
sub _make_query_xml
{
my( $self, $hash ) = @_;
my $user = $self->userid;
my $pass = $self->password;
my $xml =
qq|<CityStateLookupRequest USERID="$user" PASSWORD="$pass">| .
qq|<ZipCode ID="0"><Zip5>$$hash{Zip5}</Zip5>| .
qq|</ZipCode></CityStateLookupRequest>|;
}
sub _parse_response
{
my( $self ) = @_;
#require 'Hash::AsObject';
my %hash = ();
foreach my $field ( $self->_fields )
{
my( $value ) = $self->response =~ m|<$field>(.*?)</$field>|g;
$hash{$field} = $value || '';
}
bless \%hash, ref $self; # 'Hash::AsObject';
}
=back
=head1 TO DO
=head1 SEE ALSO
L<Business::US::USPS::WebTools>
The WebTools API is documented on the US Postal Service's website:
http://www.usps.com/webtools/htm/Address-Information.htm
=head1 SOURCE AVAILABILITY
This source is part of a SourceForge project which always has the
latest sources in CVS, as well as all of the previous releases.
http://sourceforge.net/projects/brian-d-foy/
If, for some reason, I disappear from the world, one of the other
members of the project can shepherd this module appropriately.
=head1 AUTHOR
brian d foy, C<< <bdfoy@cpan.org> >>
=head1 COPYRIGHT AND LICENSE
Copyright (c) 2006-2007, brian d foy, All Rights Reserved.
You may redistribute this under the same terms as Perl itself.
=cut
1;
|