NAME

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

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};

DESCRIPTION

This module 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 rawJSON attached for debugging.

WHAT THIS MODULE DOES

• Sends geocoding requests to https://maps.googleapis.com/maps/api/geocode/json.
• Supports structured address parts, place_id, and optional language, region, bounds, and components.
• Returns decoded API payloads with rawJSON attached for debugging.

INSTALLATION

perl Makefile.PL
make
make test
make install

DEPENDENCIES

Runtime dependencies are declared in Makefile.PL:

• HTTP::Tiny
• JSON::PP
• URI::Escape

TESTING

Run tests with:

make test

METHODS

new

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

geocode_addr

my $response = $geo->geocode_addr({
  address   => '1600 Amphitheatre Parkway',
  city      => 'Mountain View',
  state     => 'CA',
  zip       => '94043',
  language  => 'en',
  region    => 'us',
  place_id  => 'ChIJ2eUgeAK6j4ARbn5u_wAGqWA',
  components => {
    country => 'US',
  },
});

Returns a hashref mirroring Google API JSON.

geocode

Deprecated compatibility wrapper for legacy return shape:

my ($count, $status, @results_and_raw) = $geo->geocode(...);

AUTHOR

TTG, ttg@cpan.org

LICENSE

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.10.0 or, at your option, any later version of Perl 5 you may have available.