view release on metacpan or  search on metacpan

Apache/Geo/IP.pm  view on Meta::CPAN

detection, and for software export controls.

To find a country for an IP address, this module a finds the Network
that contains the IP address, then returns the country the Network is
assigned to.

=head1 CONFIGURATION

This module subclasses I<Apache2::RequestRec>, and can be used 
as follows in an Apache module.
 
  # file Apache::HelloIP
  
  use Apache::Geo::IP;
  use strict;
 
  sub handler {
     my $r = Apache::Geo::IP->new(shift);
     # continue along
  }
 
The directives in F<httpd.conf> are as follows:
 
  <Location /ip>
    PerlSetVar GeoIPDBFile "/usr/local/share/GeoIP/GeoIP.dat"
    PerlSetVar GeoIPFlag Standard
    # other directives
  </Location>
 
The C<PerlSetVar> directives available are

=over 4

=item PerlSetVar GeoIPDBFile "/path/to/GeoIP.dat"

This specifies the location of the F<GeoIP.dat> file.
If not given, it defaults to the location specified
upon installing the L<Geo::IP> module.

=item PerlSetVar GeoIPFlag Standard

Flags can be set to either I<STANDARD>, or for faster performance 
(at a cost of using more memory), I<MEMORY_CACHE>. When using memory 
cache you can force a reload if the file is updated by setting I<CHECK_CACHE>. 
I<INDEX_CACHE> caches the most frequently accessed index portion of the database, 
resulting in faster lookups than I<STANDARD>, but less memory usage than 
I<MEMORY_CACHE> - this is useful for larger databases such as GeoIP 
Organization and GeoIP City. Note, for GeoIP Country, Region and Netspeed databases, 
I<INDEX_CACHE> is equivalent to I<MEMORY_CACHE>.

Multiple values of I<GeoIPFlag> can be set by specifying them
using I<PerlAddVar>. If no values are specified, I<STANDARD> is used.

=item PerlSetVar GeoIPType CITY_EDITION_REV1

This specifies the type of database file to be used. See the L<Geo::IP> documentation
for the various types that are supported.

=item PerlSetVar GeoIPXForwardedFor 1

If this directive is set to something true, the I<X-Forwarded-For> header will
be used to try to identify the originating IP address; this is useful for clients 
connecting to a web server through an HTTP proxy or load balancer. If this header
is not present, C<$r-E<gt>connection-E<gt>remote_ip> will be used.

=back

=head1 METHODS

The available methods are as follows.

=over 4

=item $code = $r->country_code_by_addr( [$ipaddr] );

Returns the ISO 3166 country code for an IP address.
If I<$ipaddr> is not given, the value obtained by
examining the I<X-Forwarded-For> header will be used, if
I<GeoIPXForwardedFor> is used, or else
C<$r-E<gt>connection-E<gt>remote_ip> is used

=item $code = $r->country_code_by_name( [$ipname] );

Returns the ISO 3166 country code for a hostname.
If I<$ipname> is not given, the value obtained by
C<$r-E<gt>get_remote_host(REMOTE_HOST)> is used.

=item $code = $r->country_code3_by_addr( [$ipaddr] );

Returns the 3 letter country code for an IP address.
If I<$ipaddr> is not given, the value obtained by
examining the I<X-Forwarded-For> header will be used, if
I<GeoIPXForwardedFor> is used, or else
C<$r-E<gt>connection-E<gt>remote_ip> is used.

=item $code = $r->country_code3_by_name( [$ipname] );

Returns the 3 letter country code for a hostname.
If I<$ipname> is not given, the value obtained by
C<$r-E<gt>get_remote_host(REMOTE_HOST)> is used.

=item $org = $r->org_by_addr( [$ipaddr] );

Returns the Organization, ISP name or Domain Name for an IP address.
If I<$ipaddr> is not given, the value obtained by
examining the I<X-Forwarded-For> header will be used, if
I<GeoIPXForwardedFor> is used, or else
C<$r-E<gt>connection-E<gt>remote_ip> is used.

=item $org = $r->org_by_name( [$ipname] );

Returns the Organization, ISP name or Domain Name for a hostname.
If I<$ipname> is not given, the value obtained by
C<$r-E<gt>get_remote_host(REMOTE_HOST)> is used.

=item ( $country, $region ) = $r->region_by_addr( [$ipaddr] );

Returns a list containing country and region for an IP address. If the
region and/or country is unknown, I<undef> is returned. This works only 
for region databases. If I<$ipaddr> is not given, the value obtained by
examining the I<X-Forwarded-For> header will be used, if
I<GeoIPXForwardedFor> is used, or else
C<$r-E<gt>connection-E<gt>remote_ip> is used.

=item ( $country, $region ) = $r->region_by_name( [$ipname] );

Returns a list containing country and region for a hostname. If the
region and/or country is unknown, I<undef> is returned. This works only 
for region databases. If I<$ipname> is not given, the value obtained by
examining the I<X-Forwarded-For> header will be used, if
I<GeoIPXForwardedFor> is used, or else
C<$r-E<gt>get_remote_host(REMOTE_HOST)> is used.

=item $gi = $r->gi

Returns the L<Geo::IP> object.

=back

=head1 Geo::IP::Record

A L<Geo::IP::Record> object can be created by two ways:

=over 4

=item $record = $r->record_by_addr( [$ipaddr] );

Returns a L<Geo::IP::Record> object containing city location an IP address.
If I<$ipaddr> is not given, the value obtained by
examining the I<X-Forwarded-For> header will be used, if
I<GeoIPXForwardedFor> is used, or else
C<$r-E<gt>connection-E<gt>remote_ip> is used.

=item $record = $r->record_by_name( [$ipname] );

Returns a L<Geo::IP::Record> object containing city location for a hostname.
If I<$ipname> is not given, the value obtained by
C<$r-E<gt>get_remote_host(REMOTE_HOST)> is used.

=back

The information contained in this object can be accessed as:

=over 4

=item $code = $record->country_code;

Returns the ISO 3166 country code from the location object.

=item $code3 = $record->country_code3;

Returns the ISO 3166 3 letter country code from the location object.

=item $name = $record->country_name;

Returns the country name from the location object.

=item $region = $record->region;

Returns the region code from the location object.

=item $region = $record->region_name;

Returns the region name from the location object.

=item $city = $record->city;

Returns the city from the location object.

=item $postal_code = $record->postal_code;

Returns the postal code from the location object.

=item $lat = $record->latitude;

Returns the latitude from the location object.

=item $lon = $record->longitude;

Returns the longitude from the location object.

=item $time_zone = $record->time_zone;

Returns the time zone from the location object.

=item $area_code = $record->area_code;

Returns the area code from the location object (for city-level US locations only)

=item $metro_code = $record->metro_code;