1package Net::WhitePages; 2 3use strict; 4use vars qw($VERSION); 5 6$VERSION = '1.04'; 7 8use LWP::Simple qw($ua get); 9use Params::Validate qw(validate); 10use URI; 11 12use constant API_BASE => 'http://api.whitepages.com'; 13 14# Constructor -- simply stores everything given to it 15sub new { 16 my $class = shift; 17 my $args = @_ && ref($_[0]) eq 'HASH' ? shift : { @_ }; 18 19 $ua->agent("$class/$VERSION (" . $ua->agent . ")"); 20 21 bless { 22 TOKEN => $ENV{'WHITEPAGES_TOKEN'}, 23 API_VERSION => '1.0', 24 %$args, 25 } => $class; 26} 27 28# ---------------------------------------------------------------------- 29# find_person() 30# 31# http://developer.whitepages.com/docs/Methods/find_person 32# ---------------------------------------------------------------------- 33sub find_person { 34 my $self = shift; 35 return $self->_request( 36 validate(@_, { 37 'firstname' => 0, 38 'lastname' => 1, 39 'house' => 0, 40 'street' => 0, 41 'city' => 0, 42 'state' => 0, 43 'zip' => 0, 44 'areacode' => 0, 45 'metro' => 0, 46 }) 47 ); 48} 49 50# ---------------------------------------------------------------------- 51# reverse_phone 52# 53# http://developer.whitepages.com/docs/Methods/reverse_phone 54# ---------------------------------------------------------------------- 55sub reverse_phone { 56 my $self = shift; 57 return $self->_request( 58 validate(@_, { 59 'phone' => 1, 60 'state' => 0, 61 }), 62 ); 63} 64 65# ---------------------------------------------------------------------- 66# reverse_address 67# 68# http://developer.whitepages.com/docs/Methods/reverse_address 69# ---------------------------------------------------------------------- 70sub reverse_address { 71 my $self = shift; 72 return $self->_request( 73 validate(@_, { 74 'house' => 0, 75 'apt' => 0, 76 'street' => 1, 77 'city' => 0, 78 'state' => 0, 79 'zip' => 0, 80 'areacode' => 0, 81 }), 82 ); 83} 84 85# Make the URI 86# Takes API_BASE, $self->{ API_VERSION }, and caller 87sub _uri { 88 my $self = shift; 89 my $meth = shift; 90 my %p = @_; 91 my $uri = URI->new(API_BASE . '/' . $meth . '/' . $self->{ API_VERSION }); 92 93 my $t = $self->{ TOKEN } || 94 die "No token defined; can't make a request without a token!\n"; 95 96 $p{'api_key'} = $t; 97 $p{'outputtype'} = 'Perl'; 98 $uri->query_form(%p); 99 100 return $uri; 101} 102 103# Do the actual request against the whitepages.com server 104sub _request { 105 my $self = shift; 106 my @meth = caller(1); 107 (my $meth = $meth[3]) =~ s/.*:://; 108 my $uri = $self->_uri($meth, @_); 109 110 my $data = get($uri->canonical); 111 112 return eval($data); 113} 114 1151; 116 117__END__ 118 119=head1 NAME 120 121Net::WhitePages - A Perl interface to the WhitePages.com API 122 123=head1 SYNOPSIS 124 125 use Net::WhitePages; 126 127 my $wp = Net::WhitePages->new(TOKEN => "12345"); 128 my $res = $wp->find_person(lastname => "Wall", firstname => "Larry"); 129 130=head1 DESCRIPTION 131 132C<Net::WhitePages> provides a simple perl wrapper for the whitepages.com 133API (see http://developer.whitepages.com/ for details). The interface 134matches the API exactly; see http://developer.whitepages.com/docs for a 135description of it. 136 137You'll need to have a whitepages.com API token to function; see 138http://developer.whitepages.com/ for a sign-up link and terms of service. 139 140WhitePages.com places strict usage limitations, which this module does 141not attempt to enforce. 142 143=head1 METHODS 144 145=over 4 146 147=item find_person 148 149Search by a person's name and location to find the person's complete 150address and phone number. See 151http://developer.whitepages.com/docs/Methods/find_person for more 152details. 153 154=item reverse_phone 155 156Search by phone number to find the related name and address. See 157http://developer.whitepages.com/docs/Methods/reverse_phone for 158details. 159 160=item reverse_address 161 162Search by street address to find the related name and phone number. 163See http://developer.whitepages.com/docs/Methods/reverse_address for 164details. 165 166=back 167 168Each method returns a serialized version of the results data; see 169http://developer.whitepages.com/docs/docs/Responses/Results_Response 170for details on it looks like. 171 172=head1 BUGS 173 174Please report bugs via the RT queue at https://rt.cpan.org/. 175 176=head1 VERSION 177 1781.02 179 180=head1 AUTHOR 181 182Darren Chamberlain <darren@cpan.org> 183