File Coverage

blib/lib/WebService/Europeana.pm
Criterion Covered Total %
statement 69 84 82.1
branch 15 36 41.6
condition 7 30 23.3
subroutine 12 14 85.7
pod n/a
total 103 164 62.8


line stmt bran cond sub pod time code
1             package WebService::Europeana;
2              
3 2     2   159078 use warnings;
  2         6  
  2         85  
4 2     2   14 use strict;
  2         7  
  2         72  
5              
6 2     2   724 use version; our $VERSION = qv('0.0.3');
  2         4086  
  2         13  
7              
8 2     2   1177 use JSON;
  2         21601  
  2         13  
9 2     2   882 use Log::Any;
  2         13034  
  2         12  
10 2     2   1032 use LWP::UserAgent;
  2         74706  
  2         76  
11 2     2   1160 use Moo;
  2         17105  
  2         12  
12 2     2   3052 use Method::Signatures;
  2         114709  
  2         43  
13 2     2   959 use Try::Tiny;
  2         5  
  2         185  
14 2     2   838 use URL::Encode qw(url_encode);
  2         12382  
  2         315  
15              
16             has 'api_url' => ( is => 'ro', default => 'http://www.europeana.eu/api/v2/' );
17             has 'wskey' => ( is => 'ro', required => 1 );
18              
19             has log => (
20             is => 'ro',
21             default => sub { Log::Any->get_logger },
22             );
23              
24 2 50 33 2   257996 method search(Str :$query, Str :$profile = "standard", Int :$rows = 12, Int :$start = 1, Str :$reusability, Str|ArrayRef :$qf ) {
  1 50 33 1   1545  
  1 50 33     6  
  1 50 33     3  
  1 50 33     13  
  1 50 0     432482  
  1 50 33     5  
  1 50 0     3  
  1 50 33     86  
  1 50       4  
  1 50       9  
  1         159  
  1         4  
  1         3  
  1         61  
  1         16  
  1         4  
  1         2  
  1         2  
  1         3  
  1         2  
  1         3  
  1         4  
25              
26 1         8 my $ua = LWP::UserAgent->new();
27 1         2244 my $query_string = undef;
28 1         14 my $response = undef;
29 1         4 my $json_result = undef;
30 1         3 my $result_ref = undef;
31              
32 1         14 $query_string = sprintf( "%s%s?wskey=%s&rows=%s&query=%s&profile=%s",
33             $self->api_url, "search.json", $self->wskey, $rows, url_encode($query), $profile );
34              
35 1 50       29 $query_string .= "&reusability=".$reusability if ($reusability);
36              
37             # qf can be an ArrayRef
38 1 50       3 if (ref($qf) eq 'ARRAY'){
39 0         0 foreach my $f (@{$qf}){
  0         0  
40 0         0 $query_string .= "&qf=".$f;
41             }
42             }else{
43 1 50       3 $query_string .= "&qf=".$qf if ($qf);
44             }
45              
46 1         9 $self->log->infof( "Query String: %s", $query_string );
47              
48 1         6 $response = $ua->get($query_string);
49              
50 1 50       411433 if ($response->is_success) {
51 0         0 $json_result = $response->decoded_content; # or whatever
52             }
53             else {
54 1         64 $self->log->errorf("Problem accessing the API: %s!",
55             $response->status_line);
56 1         27 $result_ref->{success} = 0;
57 1         5 $result_ref->{error_msg} = $response->status_line;
58 1         115 return $result_ref;
59             }
60              
61             try {
62 0     0     $result_ref = decode_json($json_result);
63             }
64             catch {
65 0     0     $self->log->errorf( "Decoding of response '%s' failed: %s",
66             $json_result, $_ );
67 0           };
68              
69 0 0         if ($result_ref) {
70 0 0 0       if (( $result_ref->{success} )
71             && ( $result_ref->{success} == 1 )
72             ){
73 0           $self->log->info("Search was a success!");
74             }
75            
76 0 0         if ($result_ref->{itemsCount}){
77             $self->log->infof("%d item(s) of a total of %d results returned",
78             $result_ref->{itemsCount},
79             $result_ref->{totalResults}
80 0           );
81             }else{
82 0           $self->log->info("No results found");
83             # add zero count
84 0           $result_ref->{itemsCount} = 0;
85             }
86            
87 0           return $result_ref;
88             }
89             }
90              
91             1;
92              
93              
94             __END__
95              
96             =begin markdown
97              
98             [![Build Status](https://travis-ci.org/hatorikibble/webservice-europeana.svg?branch=master)](https://travis-ci.org/hatorikibble/webservice-europeana)
99              
100             =end markdown
101              
102             =head1 NAME
103              
104             WebService::Europeana - access the API of europeana.eu
105              
106             =head1 VERSION
107              
108             This document describes WebService::Europeana version 0.0.2
109              
110              
111             =head1 SYNOPSIS
112              
113             use WebService::Europeana;
114              
115             my $Europeana = WebService::Europeana->new(wskey => 'API_KEY');
116             my $result = $Europeana->search(query => "Europe",
117             reusability=> 'open',
118             rows => 3);
119              
120             foreach my $item (@{$result->{items}}){
121             print $item->{title}->[0]."\n";
122             }
123              
124             =head1 DESCRIPTION
125              
126             This module is a wrapper around the REST API of Europeana (cf. L<http://labs.europeana.eu/api/introduction>). At the moment only a basic search function is implemented.
127              
128              
129             =head1 CONSTRUCTOR
130              
131             $Europeana = WebService::Europeana->new(wskey=>'API_KEY')
132              
133             =over 4
134              
135             =item wskey
136              
137             API key, can be requested at <http://labs.europeana.eu/api/registration>
138              
139             =back
140              
141             =head1 METHODS
142              
143              
144             =head2 search
145              
146             for further explanation of the possible parameters please refer to
147             L<http://labs.europeana.eu/api/search>
148              
149             =over 4
150              
151             =item * query
152              
153             The search term(s).
154              
155             =item * profile
156              
157             Profile parameter controls the format and richness of the response. See the possible values of the profile parameter.
158              
159             =item * reusability
160              
161             Filter by copyright status. Possible values are open, restricted or permission.
162              
163              
164             =item * rows
165              
166             The number of records to return. Maximum is 100. Defaults to 12.
167              
168             =item * start
169              
170             The item in the search results to start with when using cursor-based pagination. The first item is 1. Defaults to 1.
171              
172             =item * qf
173              
174             Facet filtering query. This parameter can be a simple string e.g. C<< qf=>"TYPE:IMAGE" >> or an array reference, e.g. C<< qf=>["TYPE:IMAGE","LANGUAGE:de"] >>
175              
176             =back
177              
178             =head1 LOGGING
179              
180             This module uses the L<Log::Any>-Framework. To get logging output use L<Log::Any::Adapter> along with a destination-specific subclass.
181              
182             For example, to send output to a file via L<Log::Any::Adapter::File>, your application could do this:
183              
184             use WebService::Europeana
185             use Log::Any::Adapter ('File', '/path/to/file.log');
186              
187             my $Europeana = WebService::Europeana->new(wskey=>'API_KEY');
188             $results = $Europeana->search(query=>'Europe');
189              
190              
191             =head1 BUGS AND LIMITATIONS
192              
193             At the moment just a basic subset of the search parameters is implemented.
194              
195             No bugs have been reported.
196              
197             Please report any bugs or feature requests to
198             C<bug-www-europeana@rt.cpan.org>, or through the web interface at
199             L<http://rt.cpan.org>.
200              
201              
202             =head1 AUTHOR
203              
204             Peter Mayr C<< <pmayr@cpan.org> >>
205              
206              
207             =head1 LICENCE AND COPYRIGHT
208              
209             Copyright (c) 2015, Peter Mayr C<< <pmayr@cpan.org> >>. All rights reserved.
210              
211             This module is free software; you can redistribute it and/or
212             modify it under the same terms as Perl itself. See L<perlartistic>.
213              
214              
215             =head1 DISCLAIMER OF WARRANTY
216              
217             BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
218             FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
219             OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
220             PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER
221             EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
222             WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE
223             ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH
224             YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL
225             NECESSARY SERVICING, REPAIR, OR CORRECTION.
226              
227             IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
228             WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
229             REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE
230             LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL,
231             OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE
232             THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
233             RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
234             FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF
235             SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
236             SUCH DAMAGES.