1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
|
package Geo::TomTom::Geocoding;
use 5.006;
use strict;
use warnings;
use LWP::UserAgent;
use base 'HTTP::Response';
use JSON 'decode_json';
=head1 NAME
Geo::TomTom::Geocoding - Interface to the TomTom Geocoding service
=head1 VERSION
Version 0.01
=cut
our $VERSION = '0.01';
our $DEBUG = 0;
=head1 SYNOPSIS
use Geo::TomTom::Geocoding;
my $request = {
key => '12345678abcdef',# API authorization
ST => '123', # address number
T => 'Main Street', # street name
L => 'San Francisco', # locality
AA => 'CA', # administrative area (state/province/district)
PC => '93102', # postal code
CC => 'USA', # country code (ISO three-letter)
IS => 'Market Street', # intersecting street
# other options specified in the API docs
};
$result = Geo::TomTom::Geocoding->query($request);
if ($result->is_success) {
foreach ($result->locations) {
print $_->{formattedAddress};
}
}
=head1 CLASS METHODS
=head2 query HASHREF
Send a request to the web service. See
L<http://developer.tomtom.com/docs/read/geocoding/Request> for fields that
can be included in HASHREF. C<key> is your API key.
Returns an object of class Geo::TomTom::Geocoding.
=cut
my $ua = LWP::UserAgent->new;
my $base_uri = 'https://api.tomtom.com/lbs/geocoding/geocode';
sub query {
my $class = shift;
my $opt;
if (ref($_[0]) eq 'HASH') {
$opt = [ %{ $_[0] } ];
} elsif (ref($_[0]) eq 'ARRAY') {
$opt = shift;
} else {
$opt = [ @_ ];
}
push @$opt, format => 'json';
my $uri = URI->new($base_uri);
$uri->query_form($opt);
warn "Geo::TomTom::Geocoding->request\n$uri\n\n" if $DEBUG;
my $http_req = HTTP::Request->new(GET => $uri->as_string);
my $self = $ua->request($http_req);
bless $self, $class;
if ( $self->is_success ) {
my $data = decode_json($self->content);
if ( $data->{geoResponse}->{count} == 0 ) {
$self->message("Location not found");
} else {
$self->locations( @{$data->{geoResponse}->{geoResult}} );
}
}
$self;
}
=head1 METHODS
=head2 locations
Returns a list of all locations matched by the address query. Each one
will be a hashref containing any of the elements listed in the documentation:
L<http://developer.tomtom.com/docs/read/geocoding/Response>
=cut
sub locations {
my $self = shift;
if ( @_ ) {
if ( ref($_[0]) eq 'ARRAY' ) {
$self->{_locations} = shift;
} elsif ( ref($_[0]) eq 'HASH' ) {
$self->{_locations} = [ @_ ];
}
}
@{ $self->{_locations} || [] };
}
=head1 AUTHOR
Mark Wells, C<< <mark at freeside.biz> >>
=head1 SUPPORT
You can find documentation for this module with the perldoc command.
perldoc Geo::TomTom::Geocoding
For the request and response attributes, see the TomTom API documentation:
L<developer.tomtom.com/docs/read/geocoding>
=back
=head1 LICENSE AND COPYRIGHT
Copyright 2013 Mark Wells.
This program is free software; you can redistribute it and/or modify it
under the terms of either: the GNU General Public License as published
by the Free Software Foundation; or the Artistic License.
See http://dev.perl.org/licenses/ for more information.
The data from the TomTom geocoding service is NOT free software. Consult
TomTom's terms of service for details.
=cut
1; # End of Geo::TomTom::Geocoding
|
