Geocoding.pm

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