view release on metacpan or  search on metacpan

lib/Google/GeoCoder/Smart.pm  view on Meta::CPAN

package Google::GeoCoder::Smart;

use strict;
use warnings;

use parent qw(Exporter);

use HTTP::Tiny ();
use JSON::PP qw(decode_json);
use URI::Escape qw(uri_escape_utf8);

our @EXPORT = qw(geocode parse);

our $VERSION = "v2.6.8";

=head1 NAME

Google::GeoCoder::Smart - Simple Google Geocoding API client

=head1 SYNOPSIS

  use Google::GeoCoder::Smart;

  my $geo = Google::GeoCoder::Smart->new(
    key => $ENV{GOOGLE_MAPS_API_KEY},
  );

  my $response = $geo->geocode_addr({
    address => '1600 Amphitheatre Parkway',
    city    => 'Mountain View',
    state   => 'CA',
    zip     => '94043',
  });

  die "Error: $response->{status}" if $response->{status} ne 'OK';

  my $best_match = $response->{results}[0];
  my $lat = $best_match->{geometry}{location}{lat};
  my $lng = $best_match->{geometry}{location}{lng};

=head1 DESCRIPTION

L<Google::GeoCoder::Smart|https://metacpan.org/pod/Google::GeoCoder::Smart> provides a lightweight wrapper around the Google Geocoding API
v3 endpoint:

  https://maps.googleapis.com/maps/api/geocode/json

It supports both structured addresses and place IDs, and returns decoded API
payloads with C<rawJSON> attached for debugging.

=head1 WHAT THIS MODULE DOES

=over 4

=item * Sends geocoding requests to C<https://maps.googleapis.com/maps/api/geocode/json>.

=item * Supports structured address parts, C<place_id>, and optional C<language>, C<region>, C<bounds>, and C<components>.

=item * Returns decoded API payloads with C<rawJSON> attached for debugging.

=back

=head1 INSTALLATION

  perl Makefile.PL
  make
  make test
  make install

=head1 DEPENDENCIES

Runtime dependencies are declared in C<Makefile.PL>:

=over 4

=item * C<HTTP::Tiny>

=item * C<JSON::PP>

=item * C<URI::Escape>

=back

=head1 TESTING

Run tests with:

  make test

=head1 METHODS

=head2 new

  my $geo = Google::GeoCoder::Smart->new(
    key    => 'your-api-key',
    host   => 'maps.googleapis.com', # optional
    scheme => 'https',               # optional
    timeout => 10,                   # optional
  );

=head2 C<geocode_addr>

  my $response = $geo->geocode_addr({
    address   => '1600 Amphitheatre Parkway',