blib/lib/Geo/Coder/CA.pm

filter: Statementstmt 66.3% 67 / 101 Branchbran 51.7% 30 / 58 Conditioncond 47.0% 8 / 17 MC/DCmcdc 36.3% 4 / 11 Subroutinesub 78.5% 11 / 14 Podpod 100% 5 / 5 totaltotal 60.6% 125 / 206 CC 35 SCAR 25.8
CC
35
Cov
60%
geocode
24.5
_could_be_a_location
19.1
_get_params
11.0
CRAP 13.2
↑ Summary
1 package Geo::Coder::CA;
2  
3 # See also https://geocoding.geo.census.gov/geocoder/Geocoding_Services_API.html for the US for the future
4  
5 7 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
6 7 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
7  
8 7 ▶use Carp;
Subroutine BEGIN: called CC=1 SCAR=0.0
9 7 ▶use Encode;
Subroutine BEGIN: called CC=1 SCAR=0.0
10 7 ▶use JSON::MaybeXS;
Subroutine BEGIN: called CC=1 SCAR=0.0
11 7 ▶use LWP::UserAgent;
Subroutine BEGIN: called CC=1 SCAR=0.0
12 7 ▶use URI;
Subroutine BEGIN: called CC=1 SCAR=0.0
13  
14 # One definition of what counts as a location: Geo::Location::Predicate holds
15 # the rule the facade and its backends apply, so what is refused here is refused
16 # there for the same reason. It is called by name rather than imported - an
17 # import copies the code reference into this package, and then a test could not
18 # swap the rule for a spy to prove that it is the rule being consulted.
19 #
20 # The rule is an optional dependency, not a prerequisite: it is a distribution of
21 # its own (Geo-Location-Predicate), declared in Makefile.PL under META_MERGE's
22 # recommends, so an installer fetches it by default and a standalone install that
23 # leaves it out still gets the one answer this module can give alone - a
24 # reference is refused. It is looked for when it is first needed rather than
25 # when this module is loaded, so importing this module reads no file it may not
26 # need, and a rule installed after this module is loaded is still found.
27 7 my $HAVE_RULE; # undef until the rule is first looked for
28  
29 =head1 NAME
30  
31 Geo::Coder::CA - Provides a Geo-Coding functionality using L<https://geocoder.ca> for both Canada and the US.
32  
33 =head1 VERSION
34  
35 Version 0.17
36  
37 =cut
38  
39 7 our $VERSION = '0.17';
40  
41 =head1 SYNOPSIS
42  
43 use Geo::Coder::CA;
44  
45 my $geo_coder = Geo::Coder::CA->new();
46 my $location = $geo_coder->geocode(location => '9235 Main St, Richibucto, New Brunswick, Canada');
47  
48 =head1 DESCRIPTION
49  
50 Geo::Coder::CA provides an interface to geocoder.ca.
51 L<Geo::Coder::Canada> no longer seems to work.
52  
53 =head1 METHODS
54  
55 =head2 new
56  
57 $geo_coder = Geo::Coder::CA->new();
58 my $ua = LWP::UserAgent->new();
59 $ua->env_proxy(1);
60 $geo_coder = Geo::Coder::CA->new(ua => $ua);
61  
62 =cut
63  
64 15 ▶sub new {
Subroutine new: called CC=5 SCAR=16.6
Pod documented
65 15 my($class, %args) = @_;
66  
67 15 ▶ if(!defined($class)) {
Branch: 2 branches
BranchTrueFalseTotal
if (not defined $class) { } 1 14 15
elsif (ref $class) { } 0 14 14
68 # Geo::Coder::CA::new() used rather than Geo::Coder::CA->new()
69 1 $class = __PACKAGE__;
70 } elsif(ref($class)) {
71 # clone the given object
72 0 return bless { %{$class}, %args }, ref($class);
73 }
74  
75 15 my $ua = $args{ua};
76 15 ▶ if(!defined($ua)) {
Branch: 1 branch
BranchTrueFalseTotal
unless (defined $ua) 3 12 15
77 3 $ua = LWP::UserAgent->new(agent => __PACKAGE__ . "/$VERSION");
78 3 $ua->default_header(accept_encoding => 'gzip,deflate');
79 }
80 15 ▶ my $host = $args{host} || 'geocoder.ca';
Condition50%1/2
$args{'host'} || 'geocoder.ca'
l!l
015
MC/DC0%0/1
$args{'host'} || 'geocoder.ca'
$args{'host'}
Truth table50%1/2
A
A= $args{'host'}
Aresult
11
00
81  
82 15 return bless { ua => $ua, host => $host }, $class;
83 }
84  
85 =head2 geocode
86  
87 $location = $geo_coder->geocode(location => $location);
88 # @location = $geo_coder->geocode(location => $location);
89  
90 print 'Latitude: ', $location->{'latt'}, "\n";
91 print 'Longitude: ', $location->{'longt'}, "\n";
92  
93 =cut
94  
95 # The rule when it is installed, and the one thing that can be said without it.
96 # A reference is not a location however it would print: when the rule is there it
97 # says so, and when it is not this refuses it - the hole this module used to have
98 # was testing the string a reference turns into. Whether a string of digits is a
99 # place is the rule's question, so without the rule it is not asked: the string
100 # is looked up, as it was before the rule existed.
101 11 ▶sub _could_be_a_location {
Subroutine _could_be_a_location: called CC=9 SCAR=29.5
102 11 my $location = shift;
103  
104 11 ▶ if(!defined($HAVE_RULE)) {
Branch: 1 branch
BranchTrueFalseTotal
unless (defined $HAVE_RULE) 1 10 11
105 1 ▶ $HAVE_RULE = eval {
Branch: 1 branch
BranchTrueFalseTotal
eval { do { require Geo::Location::Predicate; 'Geo::Location::Predicate'->can('_valid_location') ? 1 : 0 } } ? : 1 0 1
106 1 require Geo::Location::Predicate;
107 1 ▶ Geo::Location::Predicate->can('_valid_location') ? 1 : 0;
Branch: 1 branch
BranchTrueFalseTotal
'Geo::Location::Predicate'->can('_valid_location') ? : 1 0 1
108 } ? 1 : 0;
109 }
110  
111 # When the rule is installed it decides everything, references included, so
112 # that this module cannot be stricter or looser than the facade. Without it
113 # there are two answers this module can give on its own.
114 11 ▶ return Geo::Location::Predicate::_valid_location($location) ? 1 : 0 if $HAVE_RULE;
Branch: 2 branches
BranchTrueFalseTotal
if $HAVE_RULE 11 0 11
Geo::Location::Predicate::_valid_location($location) ? : 4 7 11
115  
116 0 ▶ return 0 if ref($location);
Branch: 1 branch
BranchTrueFalseTotal
if ref $location 0 0 0
117 0 ▶ return 0 unless defined($location) && length($location);
Branch: 1 branch
BranchTrueFalseTotal
unless defined $location and length $location 0 0 0
Condition0%0/3
defined $location and length $location
!ll&&!rl&&r
000
MC/DC0%0/2
defined $location and length $location
defined $location length $location
Truth table0%0/3
A and B
A= defined $locationB= length $location
ABresult
0X0
100
111
118 0 return 1;
119 }
120  
121 17 ▶sub geocode {
Subroutine geocode: called CC=12 SCAR=32.0
Pod documented
122 17 my $self = shift;
123 17 my $params = $self->_get_params('location', @_);
124  
125 17 my $location = $params->{location};
126 # A scalar reference is one way of passing the string it points at, and
127 # Params::Get dereferences it when it is the only argument. Do it here as
128 # well, in every calling form, so that it means the string however the
129 # method is called.
130 17 ▶ $location = ${$location} if ref($location) eq 'SCALAR';
Branch: 1 branch
BranchTrueFalseTotal
if ref $location eq "SCALAR" 2 15 17
131  
132 17 ▶ if((!defined($location)) || (length($location) == 0)) {
Branch: 1 branch
BranchTrueFalseTotal
if (not defined $location or length $location == 0) 6 11 17
Condition100%3/3
not defined $location or length $location == 0
l!l&&r!l&&!r
3311
MC/DC100%2/2
not defined $location or length $location == 0
not defined $location length $location == 0
Truth table100%3/3
not(A) or B
A= not defined $locationB= length $location == 0
ABresult
1X1
011
000
133 6 Carp::croak('Usage: geocode(location => $location)');
134 5 return;
135 }
136  
137 # What counts as a location is Geo::Location::Predicate's answer, not a
138 # second copy of it here: a reference is not a location however it would
139 # print, and a string of digits is what a numeric column holds when the wrong
140 # one has been read. The two messages above and here only choose the words;
141 # the rule itself decides.
142 11 ▶ if(!_could_be_a_location($location)) {
Branch: 1 branch
BranchTrueFalseTotal
unless (_could_be_a_location($location)) 7 4 11
143 7 ▶ Carp::croak('Usage: ', __PACKAGE__, ': invalid input to geocode(), ',
Branch: 1 branch
BranchTrueFalseTotal
ref $location ? : 6 1 7
144 ref($location) ? 'a reference is not a location' : $location);
145 0 return;
146 }
147  
148 4 ▶ if (Encode::is_utf8($location)) {
Branch: 1 branch
BranchTrueFalseTotal
if (&Encode::is_utf8($location)) 0 4 4
149 0 $location = Encode::encode_utf8($location);
150 }
151  
152 4 my $uri = URI->new("https://$self->{host}/some_location");
153 4 $location =~ s/\s/+/g;
154 4 my %query_parameters = ('locate' => $location, 'json' => 1, 'strictmode' => 1);
155 4 $uri->query_form(%query_parameters);
156 4 my $url = $uri->as_string();
157  
158 4 my $res = $self->{ua}->get($url);
159  
160 0 ▶ if($res->is_error()) {
Branch: 1 branch
BranchTrueFalseTotal
if ($res->is_error) 0 0 0
161 0 Carp::carp("$url API returned error: ", $res->status_line());
162 0 return;
163 }
164 # $res->content_type('text/plain'); # May be needed to decode correctly
165  
166 0 my $json = JSON::MaybeXS->new()->utf8();
167 0 ▶ if(my $rc = $json->decode($res->decoded_content())) {
Branch: 1 branch
BranchTrueFalseTotal
if (my $rc = $json->decode($res->decoded_content)) 0 0 0
168 0 ▶ if($rc->{'error'}) {
Branch: 1 branch
BranchTrueFalseTotal
if ($rc->{"error"}) 0 0 0
169 # Sorry - you lose the error code, but HTML::GoogleMaps::V3 relies on this
170 # TODO - send patch to the H:G:V3 author
171 0 return;
172 }
173 0 ▶ if(defined($rc->{'latt'}) && defined($rc->{'longt'})) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $rc->{"latt"} and defined $rc->{"longt"}) 0 0 0
Condition0%0/3
defined $rc->{"latt"} and defined $rc->{"longt"}
!ll&&!rl&&r
000
MC/DC0%0/2
defined $rc->{"latt"} and defined $rc->{"longt"}
defined $rc->{"latt"} defined $rc->{"longt"}
Truth table0%0/3
A and B
A= defined $rc->{"latt"}B= defined $rc->{"longt"}
ABresult
0X0
100
111
174 0 return $rc; # No support for list context, yet
175 }
176  
177 # if($location =~ /^(\w+),\+*(\w+),\+*(USA|US|United States)$/i) {
178 # $query_parameters{'locate'} = "$1 County, $2, $3";
179 # $uri->query_form(%query_parameters);
180 # $url = $uri->as_string();
181 #
182 # $res = $self->{ua}->get($url);
183 #
184 # if($res->is_error()) {
185 # Carp::croak("geocoder.ca API returned error: " . $res->status_line());
186 # return;
187 # }
188 # return $json->decode($res->content());
189 # }
190 }
191  
192 # my @results = @{ $data || [] };
193 # wantarray ? @results : $results[0];
194 }
195  
196 =head2 ua
197  
198 Accessor method to get and set UserAgent object used internally. You
199 can call I<env_proxy> for example, to get the proxy information from
200 environment variables:
201  
202 $geo_coder->ua()->env_proxy(1);
203  
204 You can also set your own User-Agent object:
205  
206 my $ua = LWP::UserAgent::Throttled->new();
207 $ua->throttle('geocoder.ca' => 1);
208 $geo_coder->ua($ua);
209  
210 =cut
211  
212 0 ▶sub ua {
Subroutine ua: not called CC=2 SCAR=17.9
Pod documented
213 0 my $self = shift;
214 0 ▶ if (@_) {
Branch: 1 branch
BranchTrueFalseTotal
if (@_) 0 0 0
215 0 $self->{ua} = shift;
216 }
217 0 $self->{ua};
218 }
219  
220 =head2 reverse_geocode
221  
222 $location = $geo_coder->reverse_geocode(latlng => '37.778907,-122.39732');
223  
224 Similar to geocode except it expects a latitude/longitude parameter.
225  
226 =cut
227  
228 0 ▶sub reverse_geocode {
Subroutine reverse_geocode: not called CC=2 SCAR=17.9
Pod documented
229 0 my $self = shift;
230 0 my $params = $self->_get_params('latlng', @_);
231  
232 my $latlng = $params->{latlng}
233 0 ▶ or Carp::croak('Usage: reverse_geocode(latlng => $latlng)');
Branch: 1 branch
BranchTrueFalseTotal
my $latlng = $params->{"latlng"} or Carp::croak("Usage: reverse_geocode(latlng => \$latlng)") 0 0 0
234  
235 0 return $self->geocode(location => $latlng, reverse => 1);
236 }
237  
238 =head2 run
239  
240 You can also run this module from the command line:
241  
242 perl CA.pm 1600 Pennsylvania Avenue NW, Washington DC
243  
244 =cut
245  
246 7 ▶__PACKAGE__->run(@ARGV) unless caller();
Branch: 1 branch
BranchTrueFalseTotal
unless &CORE::GLOBAL::caller() 0 7 7
247  
248 0 ▶sub run {
Subroutine run: not called CC=2 SCAR=17.9
Pod documented
249 0 require Data::Dumper;
250  
251 0 my $class = shift;
252  
253 0 my $location = join(' ', @_);
254  
255 0 my @rc = $class->new()->geocode($location);
256  
257 0 ▶ if(scalar(@rc)) {
Branch: 1 branch
BranchTrueFalseTotal
if (scalar @rc) { } 0 0 0
258 0 print Data::Dumper->new([\@rc])->Dump();
259 } else {
260 0 die "$0: geo-coding failed";
261 }
262 }
263  
264 # Helper routine to parse the arguments given to a function.
265 # Processes arguments passed to methods and ensures they are in a usable format,
266 # allowing the caller to call the function in anyway that they want
267 # e.g. foo('bar'), foo(arg => 'bar'), foo({ arg => 'bar' }) all mean the same
268 # when called _get_params('arg', @_);
269 sub _get_params
270 17 ▶{
Subroutine _get_params: called CC=9 SCAR=24.0
271 17 shift; # Discard the first argument (typically $self)
272 17 my $default = shift;
273  
274 # Directly return hash reference if the first parameter is a hash reference
275 17 ▶ return $_[0] if(ref $_[0] eq 'HASH');
Branch: 1 branch
BranchTrueFalseTotal
if ref $_[0] eq "HASH" 2 15 17
276  
277 15 my %rc;
278 15 my $num_args = scalar @_;
279  
280 # Populate %rc based on the number and type of arguments
281 15 ▶ if(($num_args == 1) && (defined $default)) {
Branch: 5 branches
BranchTrueFalseTotal
if ($num_args == 1 and defined $default) { } 2 13 15
elsif ($num_args == 1) { } 0 13 13
elsif ($num_args == 0 and defined $default) { } 1 12 13
elsif ($num_args % 2 == 0) { } 12 0 12
elsif ($num_args == 0) { } 0 0 0
Condition66%2/3
$num_args == 1 and defined $default
!ll&&!rl&&r
1302
MC/DC50%1/2
$num_args == 1 and defined $default
$num_args == 1 defined $default
Truth table66%2/3
A and B
A= $num_args == 1B= defined $default
ABresult
0X0
100
111
282 # %rc = ($default => shift);
283 2 return { $default => shift };
284 } elsif($num_args == 1) {
285 0 Carp::croak('Usage: ', __PACKAGE__, '->', (caller(1))[3], '()');
286 ▶ } elsif(($num_args == 0) && (defined($default))) {
Condition66%2/3
$num_args == 0 and defined $default
!ll&&!rl&&r
1201
MC/DC50%1/2
$num_args == 0 and defined $default
$num_args == 0 defined $default
Truth table66%2/3
A and B
A= $num_args == 0B= defined $default
ABresult
0X0
100
111
287 1 Carp::croak('Usage: ', __PACKAGE__, '->', (caller(1))[3], "($default => \$val)");
288 } elsif(($num_args % 2) == 0) {
289 12 %rc = @_;
290 } elsif($num_args == 0) {
291 0 return;
292 } else {
293 0 Carp::croak('Usage: ', __PACKAGE__, '->', (caller(1))[3], '()');
294 }
295  
296 13 return \%rc;
297 }
298  
299 =head1 AUTHOR
300  
301 Nigel Horne, C<< <njh@bandsman.co.uk> >>
302  
303 Based on L<Geo::Coder::GooglePlaces>.
304  
305 This library is free software; you can redistribute it and/or modify
306 it under the same terms as Perl itself.
307  
308 Lots of thanks to the folks at geocoder.ca.
309  
310 =head1 BUGS
311  
312 Please report any bugs or feature requests to the author.
313 This module is provided as-is without any warranty.
314  
315 Should be called Geo::Coder::NA for North America.
316  
317 =head1 SEE ALSO
318  
319 L<Geo::Coder::GooglePlaces>, L<HTML::GoogleMaps::V3>
320  
321 =head1 LICENSE AND COPYRIGHT
322  
323 Copyright 2017-2026 Nigel Horne.
324  
325 This program is released under the following licence: GPL2
326  
327 =cut
328  
329 7 1;
↑ Summary