line |
stmt |
bran |
cond |
sub |
pod |
time |
code |
1
|
|
|
|
|
|
|
package WebService::TWFY::API; |
2
|
|
|
|
|
|
|
|
3
|
2
|
|
|
2
|
|
55685
|
use strict; |
|
2
|
|
|
|
|
5
|
|
|
2
|
|
|
|
|
71
|
|
4
|
2
|
|
|
2
|
|
11
|
use warnings ; |
|
2
|
|
|
|
|
3
|
|
|
2
|
|
|
|
|
54
|
|
5
|
|
|
|
|
|
|
|
6
|
2
|
|
|
2
|
|
1146
|
use WebService::TWFY::Request ; |
|
2
|
|
|
|
|
6
|
|
|
2
|
|
|
|
|
60
|
|
7
|
2
|
|
|
2
|
|
1219
|
use WebService::TWFY::Response ; |
|
2
|
|
|
|
|
7
|
|
|
2
|
|
|
|
|
63
|
|
8
|
|
|
|
|
|
|
|
9
|
2
|
|
|
2
|
|
2359
|
use LWP::UserAgent ; |
|
2
|
|
|
|
|
36366
|
|
|
2
|
|
|
|
|
860
|
|
10
|
|
|
|
|
|
|
|
11
|
|
|
|
|
|
|
our @ISA = qw( LWP::UserAgent ) ; |
12
|
|
|
|
|
|
|
our $VERSION = 0.07 ; |
13
|
|
|
|
|
|
|
|
14
|
|
|
|
|
|
|
=head1 NAME |
15
|
|
|
|
|
|
|
|
16
|
|
|
|
|
|
|
WebService::TWFY::API - API interface for TheyWorkForYou.com |
17
|
|
|
|
|
|
|
|
18
|
|
|
|
|
|
|
=head1 VERSION |
19
|
|
|
|
|
|
|
|
20
|
|
|
|
|
|
|
Version 0.07 |
21
|
|
|
|
|
|
|
|
22
|
|
|
|
|
|
|
=cut |
23
|
|
|
|
|
|
|
|
24
|
|
|
|
|
|
|
=head1 SYNOPSIS |
25
|
|
|
|
|
|
|
|
26
|
|
|
|
|
|
|
use WebService::TWFY::API ; |
27
|
|
|
|
|
|
|
|
28
|
|
|
|
|
|
|
my $rh = { key => 'ABC123' }; |
29
|
|
|
|
|
|
|
my $api = WebService::TWFY::API->new( $rh ) ; |
30
|
|
|
|
|
|
|
|
31
|
|
|
|
|
|
|
my $rv = $api->query ( 'getConstituency', { 'postcode' => 'W128JL' |
32
|
|
|
|
|
|
|
'output' => 'xml', |
33
|
|
|
|
|
|
|
} ) ; |
34
|
|
|
|
|
|
|
|
35
|
|
|
|
|
|
|
if ($rv->{is_success}) { |
36
|
|
|
|
|
|
|
|
37
|
|
|
|
|
|
|
my $results = $rv->{results} ; |
38
|
|
|
|
|
|
|
### do whatever with results |
39
|
|
|
|
|
|
|
|
40
|
|
|
|
|
|
|
} |
41
|
|
|
|
|
|
|
|
42
|
|
|
|
|
|
|
=head1 DESCRIPTION |
43
|
|
|
|
|
|
|
|
44
|
|
|
|
|
|
|
This module provides a simple interface to the API of TheyWorkForYou.com. |
45
|
|
|
|
|
|
|
|
46
|
|
|
|
|
|
|
The actual core class, C is a subsclass of C so you |
47
|
|
|
|
|
|
|
are able to tweak all the normal options such as timeout etc. The UserAgent identifier however |
48
|
|
|
|
|
|
|
is hardcoded to "WebService::TWFY::API module". This does not provide any personal information to |
49
|
|
|
|
|
|
|
the API. However, it helps them track and monitor usage of the API service from this module. |
50
|
|
|
|
|
|
|
|
51
|
|
|
|
|
|
|
=head1 METHODS |
52
|
|
|
|
|
|
|
|
53
|
|
|
|
|
|
|
=over 4 |
54
|
|
|
|
|
|
|
|
55
|
|
|
|
|
|
|
=item C |
56
|
|
|
|
|
|
|
|
57
|
|
|
|
|
|
|
The following constructor method creates C object and returns it. |
58
|
|
|
|
|
|
|
|
59
|
|
|
|
|
|
|
my $rh = { key => 'ABC123' }; |
60
|
|
|
|
|
|
|
|
61
|
|
|
|
|
|
|
my $api = WebService::TWFY::API->new( $rh ) ; |
62
|
|
|
|
|
|
|
|
63
|
|
|
|
|
|
|
The API now requires a key, you can obtain one at L. |
64
|
|
|
|
|
|
|
The key above will not work, its only used as an example. |
65
|
|
|
|
|
|
|
|
66
|
|
|
|
|
|
|
In future versions, if needed, it will support specifying the version of the API you wish to use. |
67
|
|
|
|
|
|
|
|
68
|
|
|
|
|
|
|
=item C |
69
|
|
|
|
|
|
|
|
70
|
|
|
|
|
|
|
Internal function which executes a request and blesses the response |
71
|
|
|
|
|
|
|
into a C object. |
72
|
|
|
|
|
|
|
|
73
|
|
|
|
|
|
|
=item C |
74
|
|
|
|
|
|
|
|
75
|
|
|
|
|
|
|
Creates a new C request object and executes it with the parameters specified. |
76
|
|
|
|
|
|
|
|
77
|
|
|
|
|
|
|
my $rv = $api->query ( 'getConstituency', { 'postcode' => 'W128JL' |
78
|
|
|
|
|
|
|
'output' => 'xml', |
79
|
|
|
|
|
|
|
} ) ; |
80
|
|
|
|
|
|
|
|
81
|
|
|
|
|
|
|
or |
82
|
|
|
|
|
|
|
|
83
|
|
|
|
|
|
|
my $rv = $api->query ( 'getMP', { 'postcode' => 'W128JL' |
84
|
|
|
|
|
|
|
'output' => 'js', |
85
|
|
|
|
|
|
|
} ) ; |
86
|
|
|
|
|
|
|
|
87
|
|
|
|
|
|
|
|
88
|
|
|
|
|
|
|
abstract : |
89
|
|
|
|
|
|
|
|
90
|
|
|
|
|
|
|
my $rv = $api->query ( function, { parameter1 => value, |
91
|
|
|
|
|
|
|
parameter2 => value, |
92
|
|
|
|
|
|
|
... |
93
|
|
|
|
|
|
|
} ) ; |
94
|
|
|
|
|
|
|
|
95
|
|
|
|
|
|
|
For a complete list of functions supported by the API, visit L. |
96
|
|
|
|
|
|
|
Current output methods supported at the moment are B (xml), B (js), B (php) and B (rabx). |
97
|
|
|
|
|
|
|
This essentially returns a C object, which is a C subclass |
98
|
|
|
|
|
|
|
with some additional keys in place: |
99
|
|
|
|
|
|
|
|
100
|
|
|
|
|
|
|
=over |
101
|
|
|
|
|
|
|
|
102
|
|
|
|
|
|
|
=item * |
103
|
|
|
|
|
|
|
I : 0 or 1 |
104
|
|
|
|
|
|
|
|
105
|
|
|
|
|
|
|
=item * |
106
|
|
|
|
|
|
|
I : results returned from the API |
107
|
|
|
|
|
|
|
|
108
|
|
|
|
|
|
|
=item * |
109
|
|
|
|
|
|
|
I : the error code (if any) |
110
|
|
|
|
|
|
|
|
111
|
|
|
|
|
|
|
=item * |
112
|
|
|
|
|
|
|
I : the error message (if any) |
113
|
|
|
|
|
|
|
|
114
|
|
|
|
|
|
|
=back |
115
|
|
|
|
|
|
|
|
116
|
|
|
|
|
|
|
=back |
117
|
|
|
|
|
|
|
|
118
|
|
|
|
|
|
|
=head1 SUPPORT |
119
|
|
|
|
|
|
|
|
120
|
|
|
|
|
|
|
Please feel free to send any bug reports and suggestions to my email listed below. |
121
|
|
|
|
|
|
|
|
122
|
|
|
|
|
|
|
For more information and useless facts on my life, you can also check my blog: |
123
|
|
|
|
|
|
|
|
124
|
|
|
|
|
|
|
http://ffffruit.com/ |
125
|
|
|
|
|
|
|
|
126
|
|
|
|
|
|
|
=head1 AUTHOR |
127
|
|
|
|
|
|
|
|
128
|
|
|
|
|
|
|
Spiros Denaxas |
129
|
|
|
|
|
|
|
CPAN ID: SDEN |
130
|
|
|
|
|
|
|
s [dot] denaxas [@] gmail [dot]com |
131
|
|
|
|
|
|
|
http://ffffruit.com |
132
|
|
|
|
|
|
|
|
133
|
|
|
|
|
|
|
=head1 SOURCE CODE |
134
|
|
|
|
|
|
|
|
135
|
|
|
|
|
|
|
The source code for his module is now on github L |
136
|
|
|
|
|
|
|
|
137
|
|
|
|
|
|
|
=head1 COPYRIGHT |
138
|
|
|
|
|
|
|
|
139
|
|
|
|
|
|
|
This program is free software; you can redistribute |
140
|
|
|
|
|
|
|
it and/or modify it under the same terms as Perl itself. |
141
|
|
|
|
|
|
|
|
142
|
|
|
|
|
|
|
The full text of the license can be found in the |
143
|
|
|
|
|
|
|
LICENSE file included with this module. |
144
|
|
|
|
|
|
|
|
145
|
|
|
|
|
|
|
|
146
|
|
|
|
|
|
|
=head1 SEE ALSO |
147
|
|
|
|
|
|
|
|
148
|
|
|
|
|
|
|
C, C, L, L |
149
|
|
|
|
|
|
|
|
150
|
|
|
|
|
|
|
=cut |
151
|
|
|
|
|
|
|
|
152
|
|
|
|
|
|
|
sub new { |
153
|
2
|
|
|
2
|
1
|
349
|
my $class = shift ; |
154
|
2
|
|
|
|
|
7
|
my $rh = shift; |
155
|
|
|
|
|
|
|
|
156
|
2
|
50
|
|
|
|
10
|
unless ( defined $rh->{key} ) { |
157
|
0
|
|
|
|
|
0
|
die "The API requires a key. You can obtain one at http://www.theyworkforyou.com/api/key"; |
158
|
|
|
|
|
|
|
} |
159
|
|
|
|
|
|
|
|
160
|
|
|
|
|
|
|
# Please do not change the following user agent parameter. |
161
|
|
|
|
|
|
|
# It does not provide TheyWorkForYou.com with any personal information |
162
|
|
|
|
|
|
|
# but however helps them track usage of this CPAN module. |
163
|
|
|
|
|
|
|
|
164
|
2
|
|
|
|
|
11
|
my %options = ( 'agent' => 'WebService::TWFY::API module' ) ; |
165
|
|
|
|
|
|
|
|
166
|
2
|
|
|
|
|
22
|
my $self = new LWP::UserAgent( %options ) ; |
167
|
|
|
|
|
|
|
|
168
|
2
|
|
|
|
|
14863
|
bless $self, $class ; |
169
|
|
|
|
|
|
|
|
170
|
2
|
|
|
|
|
23
|
$self->{'_api_key'} = $rh->{'key'}; |
171
|
|
|
|
|
|
|
|
172
|
2
|
|
|
|
|
10
|
return $self ; |
173
|
|
|
|
|
|
|
} |
174
|
|
|
|
|
|
|
|
175
|
|
|
|
|
|
|
|
176
|
|
|
|
|
|
|
sub query { |
177
|
2
|
|
|
2
|
1
|
971
|
my ( $self, $function, $rh_args ) = (@_) ; |
178
|
|
|
|
|
|
|
|
179
|
2
|
50
|
33
|
|
|
17
|
return unless ( (defined $function) and (defined $rh_args) ) ; |
180
|
2
|
50
|
|
|
|
33
|
return unless ref $rh_args eq 'HASH' ; |
181
|
|
|
|
|
|
|
|
182
|
2
|
|
|
|
|
7
|
$rh_args->{key} = $self->{_api_key}; |
183
|
|
|
|
|
|
|
|
184
|
2
|
|
|
|
|
13
|
my $query = new WebService::TWFY::Request ( $function, $rh_args ) ; |
185
|
|
|
|
|
|
|
|
186
|
1
|
50
|
|
|
|
4
|
if ( defined $query ) { |
187
|
1
|
|
|
|
|
4
|
$self->execute_query($query) ; |
188
|
|
|
|
|
|
|
} else { |
189
|
0
|
|
|
|
|
0
|
return ; |
190
|
|
|
|
|
|
|
} |
191
|
|
|
|
|
|
|
|
192
|
|
|
|
|
|
|
} |
193
|
|
|
|
|
|
|
|
194
|
|
|
|
|
|
|
sub execute_query { |
195
|
1
|
|
|
1
|
1
|
2
|
my ($self, $query) = (@_) ; |
196
|
|
|
|
|
|
|
|
197
|
1
|
|
|
|
|
5
|
my $url = $query->encode_arguments() ; |
198
|
0
|
|
|
|
|
|
my $response = $self->get($url) ; |
199
|
|
|
|
|
|
|
|
200
|
0
|
|
|
|
|
|
bless $response, 'WebService::TWFY::Response' ; |
201
|
|
|
|
|
|
|
|
202
|
0
|
0
|
|
|
|
|
unless ($response->{_rc} = 200) { |
203
|
0
|
|
|
|
|
|
$response->set_fail(0, "API returned a non-200 status code: ($response->{_rc})") ; |
204
|
0
|
|
|
|
|
|
return $response ; |
205
|
|
|
|
|
|
|
} ; |
206
|
|
|
|
|
|
|
|
207
|
0
|
0
|
|
|
|
|
unless ($response->{_msg} eq 'OK') { |
208
|
0
|
|
|
|
|
|
$response->set_fail(0, "An API error has occured: $response->{_msg}") ; |
209
|
0
|
|
|
|
|
|
return $response ; |
210
|
|
|
|
|
|
|
} |
211
|
|
|
|
|
|
|
|
212
|
0
|
|
|
|
|
|
my $results = $response->{_content} ; |
213
|
0
|
|
|
|
|
|
$response->set_success($results) ; |
214
|
|
|
|
|
|
|
|
215
|
0
|
|
|
|
|
|
return $response ; |
216
|
|
|
|
|
|
|
|
217
|
|
|
|
|
|
|
} |
218
|
|
|
|
|
|
|
|
219
|
|
|
|
|
|
|
1; |
220
|
|
|
|
|
|
|
|