NAME

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

SYNOPSIS

use Geo::Coder::GeocodeFarm;

my $geocoder = Geo::Coder::GeocodeFarm->new(
    key => 'YOUR-API-KEY-HERE',
);
my $result = $geocoder->geocode(
    location => '530 W Main St Anoka MN 55303 US'
);
printf "%f,%f",
    $result->{RESULTS}{result}{coordinates}{lat},
    $result->{RESULTS}{result}{coordinates}{lon};

DESCRIPTION

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

METHODS

new

$geocoder = Geo::Coder::GeocodeFarm->new(
    key    => 'YOUR-API-KEY-HERE',
    ua     => HTTP::Tiny->new,
    parser => JSON->new->utf8,
    raise_failure => 1,
);

Creates a new geocoding object with optional arguments.

An API key is REQUIRED and can be obtained at https://geocode.farm/store/api-services/

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://geocode.farm/store/api-services/

geocode

$result = $geocoder->geocode(
    location => $location
)

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

{
    "LEGAL": {
        "notice": "This system is the property of Geocode.Farm and any information contained herein is Copyright (c) Geocode.Farm. Usage is subject to the Terms of Service.",
        "terms": "https:\/\/geocode.farm\/policies\/terms-of-service\/",
        "privacy": "https:\/\/geocode.farm\/policies\/privacy-policy\/"
    },
    "STATUS": {
        "key": "VALID",
        "request": "VALID",
        "status": "SUCCESS",
        "credit_used": "1"
    },
    "USER": {
        "key": "YOUR-API-KEY-HERE",
        "name": "Your Name",
        "email": "[email protected]",
        "usage_limit": "UNLIMITED",
        "used_today": "1",
        "remaining_limit": "UNLIMITED"
    },
    "RESULTS": {
        "request": {
            "addr": "30 N Gould St, Ste R, Sheridan, WY 82801 USA"
        },
        "result": {
            "coordinates": {
                "lat": "44.7977733966548",
                "lon": "-106.954917523499"
            },
            "address": {
                "full_address": "30 N Gould St, Sheridan, WY 82801, United States",
                "house_number": "30",
                "street_name": "N Gould St",
                "locality": "Sheridan",
                "admin_2": "Sheridan County",
                "admin_1": "WY",
                "country": "United States",
                "postal_code": "82801"
            },
            "accuracy": "EXACT_MATCH"
        }
    }
}

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
)

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://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 [email protected]

LICENSE

Copyright (c) 2013, 2015 Piotr Roszatycki [email protected].

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