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