File: CityStateLookup.pm

package info (click to toggle)
libbusiness-us-usps-webtools-perl 1.11-2
  • links: PTS, VCS
  • area: main
  • in suites: jessie, jessie-kfreebsd, stretch
  • size: 204 kB
  • ctags: 37
  • sloc: perl: 1,057; makefile: 2
file content (159 lines) | stat: -rw-r--r-- 3,495 bytes parent folder | download | duplicates (2)
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;