Geo::C...oglev3(3pm)

💖 Geo::Coder::Googlev3 💖

okay bestie, so this is the manual page for Geo::Coder::Googlev3, living in the User Contributed Perl Documentation section of your 3pm man pages. it's a whole module, it's iconic, let's get into it 🦋

---

✨ NAME ✨

Geo::Coder::Googlev3 — it's the Google Maps v3 Geocoding API wrapper, periodt 💅

---

🌸 SYNOPSIS 🌸

the vibe check, in code:

use Geo::Coder::Googlev3;

my $geocoder = Geo::Coder::Googlev3->new;
my $location  = $geocoder->geocode(location => 'Brandenburger Tor, Berlin');
my @locations = $geocoder->geocode(location => 'Berliner Straße, Berlin, Germany');

like, you literally just do that. no cap ✨

---

👑 DESCRIPTION 👑

use this module exactly like Geo::Coder::Google, fr fr. BUT — and this is the plot twist — there's no "apikey" used in Google's v3 API, and the data structure that comes back is different. so don't go expecting the old shape, bestie, it's giving new era 💀

also, pls pls pls go read https://developers.google.com/maps/documentation/geocoding/ for more deets about Google's Geocoding API — especially the usage limits, because Google will absolutely notice if you're out here spamming requests 🙈

---

🎀 CONSTRUCTOR 🎀

new

$geocoder = Geo::Coder::Googlev3->new;
$geocoder = Geo::Coder::Googlev3->new(language => 'de', gl => 'es');

creates a shiny new geocoding object. main character energy, honestly ✨

• the ua parameter may be supplied to override the default LWP::UserAgent object. the default LWP::UserAgent object sets the timeout to 15 seconds and enables the env_proxy option. so it's already got good defaults, you don't have to do anything 💅
• the Geo::Coder::Google's oe parameter is not supported. nope. not a thing here. sorry bestie 😭
• the parameters region, language, bounds, and key are also accepted 🫶
• the bounds parameter should be in this form:

[{lat => ..., lng => ...}, {lat => ..., lng => ...}]

• the parameter sensor should be set to the string "true" if the geocoding request comes from a device with a location sensor (see https://developers.google.com/maps/documentation/geocoding/#GeocodingRequests). there's no default — so if you need it, you gotta say it out loud 👀
• by default queries are done using http. by setting the use_https parameter to a true value, https is used 🔒 (yes babe, use https, it's 2022 in the footer, be safe)

---

🦋 METHODS 🦋

geocode

$location = $geocoder->geocode(location => $location);
@locations = $geocoder->geocode(location => $location);

queries $location to the Google Maps geocoding API. so in scalar context it returns a hash reference of the first (best matching?) location, and in list context it returns a list of such hash references. choose your context wisely, bestie, it changes everything 🫶

the returned data structure looks like this:

{
  "formatted_address" => "Brandenburger Tor, Pariser Platz 7, 10117 Berlin, Germany",
  "types" => [
    "point_of_interest",
    "establishment"
  ],
  "address_components" => [
    {
      "types" => [
        "point_of_interest",
        "establishment"
      ],
      "short_name" => "Brandenburger Tor",
      "long_name" => "Brandenburger Tor"
    },
    {
      "types" => [
        "street_number"
      ],
      "short_name" => 7,
      "long_name" => 7
    },
    {
      "types" => [
        "route"
      ],
      "short_name" => "Pariser Platz",
      "long_name" => "Pariser Platz"
    },
    {
      "types" => [
        "sublocality",
        "political"
      ],
      "short_name" => "Mitte",
      "long_name" => "Mitte"
    },
    {
      "types" => [
        "locality",
        "political"
      ],
      "short_name" => "Berlin",
      "long_name" => "Berlin"
    },
    {
      "types" => [
        "administrative_area_level_2",
        "political"
      ],
      "short_name" => "Berlin",
      "long_name" => "Berlin"
    },
    {
      "types" => [
        "administrative_area_level_1",
        "political"
      ],
      "short_name" => "Berlin",
      "long_name" => "Berlin"
    },
    {
      "types" => [
        "country",
        "political"
      ],
      "short_name" => "DE",
      "long_name" => "Germany"
    },
    {
      "types" => [
        "postal_code"
      ],
      "short_name" => 10117,
      "long_name" => 10117
    }
  ],
  "geometry" => {
    "viewport" => {
      "southwest" => {
        "lat" => "52.5094785",
        "lng" => "13.3617711"
      },
      "northeast" => {
        "lat" => "52.5230586",
        "lng" => "13.3937859"
      }
    },
    "location" => {
      "lat" => "52.5162691",
      "lng" => "13.3777785"
    },
    "location_type" => "APPROXIMATE"
  }
};

like… look at all those address_components. it ATE. 🍓

the raw option may be set to a true value to get the uninterpreted, raw result from the API. just the JSON data will be translated into a perl hash. so no fancy stuff, just the straight-up goods:

$raw_result = $geocoder->geocode(location => $location, raw => 1);

region

accessor for the region parameter. the value should be a country code ("es", "dk", "us", etc). use this to tell the webservice to prefer matches from that region. see the Google documentation for more information 👑

language

accessor for the language parameter 🌈

bounds

accessor for the bounds parameter 💜

sensor

accessor for the sensor parameter 👀

---

💜 AUTHOR 💜

Slaven Rezic <srezic@cpan.org> — ty for your service, king 👑

this package is free software; you can redistribute it and/or modify it under the same terms as Perl itself. slay.

---

🌈 SEE ALSO 🌈

• Geo::Coder::Google
• Geo::Coder::Many

go read those too, bestie, they're the whole friend group 🫶

---

and that's the whole page!! 💖 this was perl v5.36.0, dated 2022-12-12 — a little vintage, a little iconic, and it's still serving. go geocode something cute ✨🎀🦋