NAME
    WebService::Geocodio - A Perl interface to Geocod.io

VERSION
    version 0.03

SYNOPSIS
        use 5.014;
        use WebService::Geocodio;
        use WebService::Geocodio::Location;

        my $geo = WebService::Geocodio->new(
            api_key => $ENV{GEOCODIO_API_KEY}
        );

        # Wrigley Field
        my $loc = WebService::Geocodio::Location->new(
            number => 1060,
            postdirection => 'W',
            street => 'Addison',
            suffix => 'Street',
            city => 'Chicago',
            state => 'IL',
        );

        # Could add more than one thing here, even bare strings are OK
        # 20050 = zip code in Washington DC
        $geo->add_location($loc, '20050');

        # prints:
        # Chicago: 41.947205791667, -87.656316875
        # Chicago: 41.947180613636, -87.657167363636
        # Washington: 38.893311, -77.014647

        map { say $_->city, ": ", $_->lat, ", ", $_->lng } $geo->geocode();

OVERVIEW
    This module is a fairly thin wrapper around the Geocod.io
    <http://geocod.io> geocoding web service. This service currently only
    supports US based addresses at the moment. Both forward and reverse
    geocoding is supported.

    In my testing, the service is somewhat finicky about how addresses are
    presented and stored; please read the service API documentation
    thoroughly to make sure you're getting the best quality results from the
    service.

    You will need to obtain a free API key to use this library.

    All errors are fatal and reported by "confess". If you want more
    graceful error handling, you might want to try using Try::Tiny.

ATTRIBUTES
  api_key
    This is the geocod.io API key. It is required.

  locations
    The list of locations you want to geocode. These can be bare strings (if
    you like) or you can use a fancy object like
    WebService::Geocodio::Location which will serialize itself to JSON
    automatically.

  fields
    You may request the following fields be included in the results:

    *   cd

        Congressional District (for the current Congress)

    *   cd113

        Congressional District (for the 113th Congress which runs through
        2015)

    *   stateleg

        The state legislative divisions for this location. The results
        include both House and Senate, unless the location is unicameral
        like Nebraska or Washington D.C., then only a senate result is
        given.

    *   timezone

        The timezone of this location, UTC offset and whether it observes
        daylight saving time.

    *   school

        The unified or elementary/secondary school district identifiers for
        this location.

METHODS
  add_location
    This method takes one or more locations and stores it in the locations
    attribute.

  show_locations
    Show the locations currently set for geocoding.

  clear_locations
    If you want to clear the current list of locations, use this method.

  add_field
    This method takes one or more fields to include in a result set. Valid
    fields are:

    *   cd

    *   cd113

    *   stateleg

    *   timezone

    *   school

    Fields that do not match these valid names are silently discarded.

  geocode
    Send the current list of locations to the geocod.io service.

    Returns undef if there are no locations stored.

    In a list context, returns a list of WebService::Geocodio::Location
    objects. In a scalar context, returns an arrayref of
    WebService::Geocodio::Location objects. The list of objects is presented
    in descending order of accuracy.

  reverse_geocode
    Send the current list of latitude, longitude pairs to the geocod.io
    service.

    Returns undef if there are no locations stored.

    In a list context, returns a list of WebService::Geocodio::Location
    objects. In scalar context, returns an arrayref of
    WebService::Geocodio::Location objects. The list of objects is presented
    in descending order of accuracy.

AUTHOR
    Mark Allen <mrallen1@yahoo.com>

COPYRIGHT AND LICENSE
    This software is copyright (c) 2014 by Mark Allen.

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