---
name: "Geo::Coder::Googlev3"
section: "3pm"
platform: "linux"
package: "libgeo-coder-googlev3-perl"
version: "0.17-2"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/Geo::Coder::Googlev3"
---

# Geo::Coder::Googlev3(3pm)

Google Maps v3 Geocoding API

## NAME

Geo::Coder::Googlev3 - Google Maps v3 Geocoding API

## SYNOPSIS

```
    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');
```

## DESCRIPTION

Use this module just like Geo::Coder::Google. Note that no `"apikey"` is used in Google's v3 API, and the returned data structure differs.

Please check also \<https://developers.google.com/maps/documentation/geocoding/\> for more information about Google's Geocoding API and especially usage limits.

### CONSTRUCTOR

- new

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

  Creates a new geocoding object.

  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.

  The Geo::Coder::Google's `"oe"` parameter is not supported.

  The parameters `"region"`, `"language"`, `"bounds"`, and `"key"` are also accepted. The `"bounds"` parameter should be in the 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.

  By default queries are done using `"http"`. By setting the `"use_https"` parameter to a true value `"https"` is used.

### METHODS

- geocode

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

  Queries *$location* to Google Maps geocoding API. In scalar context it returns a hash reference of the first (best matching?) location. In list context it returns a list of such hash references.

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

  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.

  ```
      $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\>

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

## SEE ALSO

Geo::Coder::Google, Geo::Coder::Many.