+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 = 1;
+
+=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