File Coverage

blib/lib/Business/US/USPS/WebTools/AddressStandardization.pm
Criterion Covered Total %
statement 20 42 47.6
branch n/a
condition 0 2 0.0
subroutine 7 14 50.0
pod 1 1 100.0
total 28 59 47.4


line stmt bran cond sub pod time code
1 1     1   970 use v5.10;
  1         4  
2 1     1   5 use utf8;
  1         1  
  1         5  
3              
4             package Business::US::USPS::WebTools::AddressStandardization;
5 1     1   27 use strict;
  1         2  
  1         21  
6 1     1   4 no warnings 'uninitialized';
  1         2  
  1         49  
7              
8 1     1   446 use parent qw(Business::US::USPS::WebTools);
  1         254  
  1         4  
9              
10 1     1   52 use subs qw();
  1         3  
  1         15  
11 1     1   4 use vars qw($VERSION);
  1         2  
  1         343  
12              
13             $VERSION = '1.125';
14              
15             =encoding utf8
16              
17             =head1 NAME
18              
19             Business::US::USPS::WebTools::AddressStandardization - canonicalize a US address
20              
21             =head1 SYNOPSIS
22              
23             use Business::US::USPS::WebTools::AddressStandardization;
24              
25             my $verifier = Business::US::USPS::WebTools::AddressStandardization->new( {
26             UserID => $ENV{USPS_WEBTOOLS_USERID},
27             Password => $ENV{USPS_WEBTOOLS_PASSWORD},
28             Testing => 1,
29             } );
30              
31             my $hash = $verifier->verify_address(
32             FirmName => '',
33             Address1 => '',
34             Address2 => '6406 Ivy Lane',
35             City => 'Greenbelt',
36             State => 'MD',
37             Zip5 => '',
38             Zip4 => '',
39             );
40              
41             if( $verifier->is_error )
42             {
43             warn "Oh No! $verifier->{error}{description}\n";
44             }
45             else
46             {
47             print join "\n", map { "$_: $hash->{$_}" }
48             qw(FirmName Address1 Address2 City State Zip5 Zip4 DeliveryPoint CarrierRoute ReturnText);
49             }
50              
51              
52             =head1 DESCRIPTION
53              
54             *** THIS IS ALPHA SOFTWARE ***
55              
56             This module implements the Address Standardization web service from the
57             US Postal Service. It is a subclass of Business::US::USPS::WebTools.
58              
59             =cut
60              
61             =over 4
62              
63             =cut
64              
65 0     0     sub _fields { qw( FirmName Address1 Address2 City State Zip5 Zip4 ) }
66 0     0     sub _required { qw( Address2 City State ) }
67 0     0     sub _response { (_fields(), qw( DeliveryPoint CarrierRoute ReturnText )) }
68              
69             =item verify_address( KEY, VALUE, ... )
70              
71             The C method takes the following keys, which come
72             directly from the USPS web service interface:
73              
74             FirmName The name of the company
75             Address1 The suite or apartment
76             Address2 The street address
77             City The name of the city
78             State The two letter state abbreviation
79             Zip5 The 5 digit ZIP code
80             Zip4 The 4 digit extension to the ZIP code
81              
82             It returns an anonymous hash with the same keys, but the values are
83             the USPS's canonicalized address, plus three additional keys:
84              
85             DeliveryPoint The 2 digit extension to the ZIP+4 code
86             CarrierRoute The 4 character postal carrier route
87             ReturnText An error message when multiple addresses are found
88              
89             If there is an error, the hash values will be the empty string, and
90             the error flag is set. Check is with C:
91              
92             $verifier->is_error;
93              
94             See the C documentation in Business::US::USPS::WebTools for more
95             details on error information.
96              
97             =cut
98              
99             sub verify_address {
100 0     0 1   my( $self, %hash ) = @_;
101              
102 0           $self->_make_url( \%hash );
103              
104 0           $self->_make_request;
105              
106 0           $self->_parse_response;
107             }
108              
109              
110 0     0     sub _api_name { "Verify" }
111              
112             sub _make_query_xml {
113 0     0     my( $self, $hash ) = @_;
114              
115 0           my $user = $self->userid;
116 0           my $pass = $self->password;
117              
118 0           my $xml =
119             qq|| .
120             qq|true| .
121             qq|true| .
122             qq|
|;
123              
124 0           foreach my $field ( $self->_fields ) {
125 0           $xml .= "<$field>$$hash{$field}";
126             }
127              
128 0           $xml .= qq||;
129              
130 0           return $xml;
131             }
132              
133             sub _parse_response {
134 0     0     my( $self ) = @_;
135             #require 'Hash::AsObject';
136              
137 0           my %hash = ();
138 0           foreach my $field ( $self->_response ) {
139 0           my( $value ) = $self->response =~ m|<$field>(.*?)|g;
140              
141 0   0       $hash{$field} = $value || '';
142             }
143              
144 0           bless \%hash, ref $self; # 'Hash::AsObject';
145             }
146              
147             =back
148              
149             =head1 TO DO
150              
151             =head1 SEE ALSO
152              
153             L
154              
155             The WebTools API is documented on the US Postal Service's website:
156              
157             https://www.usps.com/business/web-tools-apis/address-information-api.pdf
158              
159             =head1 SOURCE AVAILABILITY
160              
161             This source is in GitHub:
162              
163             https://github.com/ssimms/business-us-usps-webtools
164              
165             =head1 AUTHOR
166              
167             brian d foy
168              
169             =head1 MAINTAINER
170              
171             Steve Simms
172              
173             =head1 COPYRIGHT AND LICENSE
174              
175             Copyright © Steve Simms. All rights reserved.
176              
177             This program is free software; you can redistribute it and/or modify
178             it under the terms of the Artistic License 2.0.
179              
180             =cut
181              
182             1;