NAME

Geo::Coder::GeocodeFarm - Geocode addresses with the GeocodeFarm API

SYNOPSIS

  use Geo::Coder::GeocodeFarm;

  my $geocoder = Geo::Coder::GeocodeFarm->new(
      key => '3d517dd448a5ce1c2874637145fed69903bc252a',
  );
  my $result = $geocoder->geocode(
      location => '530 W Main St Anoka MN 55303 US',
      lang     => 'en',
      count    => 1,
  );
  printf "%f,%f",
      $result->{RESULTS}{COORDINATES}{latitude},
      $result->{RESULTS}{COORDINATES}{longitude};

DESCRIPTION

The Geo::Coder::GeocodeFarm module provides an interface to the geocoding functionality of the GeocodeFarm API v3.

METHODS

new

  $geocoder = Geo::Coder::GeocodeFarm->new(
      key    => '3d517dd448a5ce1c2874637145fed69903bc252a',
      url    => 'https://www.geocode.farm/v3/',
      ua     => HTTP::Tiny->new,
      parser => JSON->new->utf8,
      raise_failure => 1,
  );

Creates a new geocoding object with optional arguments.

An API key is optional and can be obtained at https://www.geocode.farm/dashboard/login/

url argument is optional and then the default address is http-based if key argument is missing and https-based if key is provided.

ua argument is a HTTP::Tiny object by default and can be also set to LWP::UserAgent object.

New account can be registered at https://www.geocode.farm/register/

geocode

  $result = $geocoder->geocode(
      location => $location,
      lang     => 'en',  # optional: 'en' or 'de'
      country  => 'US',  # optional
      count    => 1,     # optional
  )

Forward geocoding takes a provided address or location and returns the coordinate set for the requested location as a nested list:

    {
        "geocoding_results": {
            "LEGAL_COPYRIGHT": {
                "copyright_notice": "Copyright (c) 2015 Geocode.Farm - All Rights Reserved.",
                "copyright_logo": "https:\/\/www.geocode.farm\/images\/logo.png",
                "terms_of_service": "https:\/\/www.geocode.farm\/policies\/terms-of-service\/",
                "privacy_policy": "https:\/\/www.geocode.farm\/policies\/privacy-policy\/"
            },
            "STATUS": {
                "access": "FREE_USER, ACCESS_GRANTED",
                "status": "SUCCESS",
                "address_provided": "530 W Main St Anoka MN 55303 US",
                "result_count": 1
            },
            "ACCOUNT": {
                "ip_address": "1.2.3.4",
                "distribution_license": "NONE, UNLICENSED",
                "usage_limit": "250",
                "used_today": "26",
                "used_total": "26",
                "first_used": "26 Mar 2015"
            },
            "RESULTS": [
                {
                    "result_number": 1,
                    "formatted_address": "530 West Main Street, Anoka, MN 55303, USA",
                    "accuracy": "EXACT_MATCH",
                    "ADDRESS": {
                        "street_number": "530",
                        "street_name": "West Main Street",
                        "locality": "Anoka",
                        "admin_2": "Anoka County",
                        "admin_1": "Minnesota",
                        "postal_code": "55303",
                        "country": "United States"
                    },
                    "LOCATION_DETAILS": {
                        "elevation": "UNAVAILABLE",
                        "timezone_long": "UNAVAILABLE",
                        "timezone_short": "America\/Menominee"
                    },
                    "COORDINATES": {
                        "latitude": "45.2041251174690",
                        "longitude": "-93.4003513528652"
                    },
                    "BOUNDARIES": {
                        "northeast_latitude": "45.2041251778513",
                        "northeast_longitude": "-93.4003513845523",
                        "southwest_latitude": "45.2027761197097",
                        "southwest_longitude": "-93.4017002802923"
                    }
                }
            ],
            "STATISTICS": {
                "https_ssl": "DISABLED, INSECURE"
            }
        }
    }

Method throws an error (or returns failure as nested list if raise_failure argument is false) if the service failed to find coordinates or wrong key was used.

Methods throws an error if there was an other problem.

reverse_geocode

  $result = $geocoder->reverse_geocode(
      lat      => $latitude,
      lon      => $longtitude,
      lang     => 'en',  # optional: 'en' or 'de'
      country  => 'US',  # optional
      count    => 1,     # optional
  )

or

  $result = $geocoder->reverse_geocode(
      latlng => "$latitude,$longtitude",
      # ... optional args
  )

Reverse geocoding takes a provided coordinate set and returns the address for the requested coordinates as a nested list. Its format is the same as for "geocode" method.

Method throws an error (or returns failure as nested list if raise_failure argument is false) if the service failed to find coordinates or wrong key was used.

Method throws an error if there was an other problem.

SEE ALSO

https://www.geocode.farm/

BUGS

If you find the bug or want to implement new features, please report it at https://github.com/dex4er/perl-Geo-Coder-GeocodeFarm/issues

The code repository is available at http://github.com/dex4er/perl-Geo-Coder-GeocodeFarm

AUTHOR

Piotr Roszatycki <dexter@cpan.org>

LICENSE

Copyright (c) 2013, 2015 Piotr Roszatycki <dexter@cpan.org>.

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

See http://dev.perl.org/licenses/artistic.html

cpanm Geo::Coder::GeocodeFarm

perl -MCPAN -e shell
install Geo::Coder::GeocodeFarm