NAME
    Net::IPInfoDB - Perl interface to ipinfodb.com's Geolocation XML API

SYNOPSIS
        use Net::IPInfoDB;

        my $g = Net::IPInfoDB->new($key);
        my $c = $g->get_city("128.103.1.1");

USAGE
    "Net::IPInfoDB" makes use of the free Geolocation API from ipinfodb.com.
    Note that you'll need to register your app for a (free) API key in order
    to use this module. Information on the API is available at
    "http://ipinfodb.com/ip_location_api.php".

    Basic usage follows the API petty closely:

        use Net::IPInfoDB;

        my $g = Net::IPInfoDB->new;
        $g->key($api_key);

        my $addr = $g->get_city($ip_address);

    Get data from the returned object via method calls:

        printf "%s is located at (%s, %s)\n",
            $addr->ip_address, $addr->latitude, $addr->longitude;

    These methods are detailed below.

METHODS
    new Creates a new "Net::IPInfoDB" instance.

        Optionally takes a key as the first argument; if provided, will call
        the "key" method for you. If the $ENV{IPINFODB_TOKEN} exists,
        "Net::IPInfoDB" assumes it contains the token and will call
        "key($ENV{IPINFODB_TOKEN})" for you.

    key Use "key" to specify your API key. Calling "get_city" or
        "get_country" without specifying a key will result in a failure.

    get_country
        Returns country-level details about the host or ip address. Takes an
        IP address or hostname as the only argument. Returns a
        "Net::IPInfoDB::Result" object.

    get_city
        Returns city-level details, which is more resource-intensive on the
        server. If you only need the country name, avoid using the city
        precision API. Returns a "Net::IPInfoDB::Result" object.

CACHING
    "Net::IPInfoDB" does *not* do any caching of responses. You should
    definitely cache your responses using "Cache::Cache" or something
    similar.

Net::IPInfoDB::Results object
    The "get_city" and "get_country" methods return a
    "Net::IPInfoDB::Result" object, which has the following read-only
    methods, which correspond directly to the data returned:

    status_code
    status_message
    ip_address
    country_code
    country_name
    region_name
    city_name
    zip_code
    latitude
    longitude
    timezone

    There is also the following additional methods:

    web_uri
        "web_uri" returns the web URI of the IP, for fancier viewing.

    fields
        "fields" returns an array of fieldnames in the
        "Net::IPInfoDB::Result" object, for iteration.

AUTHOR
    Darren Chamberlain <darren@cpan.org>

VERSION
    This is version 3.0. Note that the major version of "Net::IPInfoDB"
    matches the ipinfodb.com API version.

