.. _ref-geoip:

======================

Geolocation with GeoIP

======================

.. module:: django.contrib.gis.utils.geoip

   :synopsis: High-level Python interface for MaxMind's GeoIP C library.

.. currentmodule:: django.contrib.gis.utils

The :class:`GeoIP` object is a ctypes wrapper for the

`MaxMind GeoIP C API`__. [#]_  This interface is a BSD-licensed alternative

to the GPL-licensed `Python GeoIP`__ interface provided by MaxMind.

In order to perform IP-based geolocation, the :class:`GeoIP` object requires

the GeoIP C libary and either the GeoIP `Country`__ or `City`__ 

datasets in binary format (the CSV files will not work!).  These datasets may be 

`downloaded from MaxMind`__.  Grab the ``GeoIP.dat.gz`` and ``GeoLiteCity.dat.gz``

and unzip them in a directory corresponding to what you set 

``GEOIP_PATH`` with in your settings.  See the example and reference below

for more details.

__ http://www.maxmind.com/app/c

__ http://www.maxmind.com/app/python

__ http://www.maxmind.com/app/country

__ http://www.maxmind.com/app/city

__ http://www.maxmind.com/download/geoip/database/

Example

=======

Assuming you have the GeoIP C library installed, here is an example of its

usage::

     >>> from django.contrib.gis.utils import GeoIP

     >>> g = GeoIP()

     >>> g.country('google.com')

     {'country_code': 'US', 'country_name': 'United States'}

     >>> g.city('72.14.207.99')

     {'area_code': 650,

     'city': 'Mountain View',

     'country_code': 'US',

     'country_code3': 'USA',

     'country_name': 'United States',

     'dma_code': 807,

     'latitude': 37.419200897216797,

     'longitude': -122.05740356445312,

     'postal_code': '94043',

     'region': 'CA'}

     >>> g.lat_lon('salon.com')

     (37.789798736572266, -122.39420318603516)

     >>> g.lon_lat('uh.edu')

     (-95.415199279785156, 29.77549934387207) 

     >>> g.geos('24.124.1.80').wkt

     'POINT (-95.2087020874023438 39.0392990112304688)'

``GeoIP`` Settings

==================

.. setting:: GEOIP_PATH

GEOIP_PATH

----------

A string specifying the directory where the GeoIP data files are

located.  This setting is *required* unless manually specified

with ``path`` keyword when initializing the :class:`GeoIP` object.

.. setting:: GEOIP_LIBRARY_PATH

GEOIP_LIBRARY_PATH

------------------

A string specifying the location of the GeoIP C library.  Typically,

this setting is only used if the GeoIP C library is in a non-standard

location (e.g., ``/home/sue/lib/libGeoIP.so``).

.. setting:: GEOIP_COUNTRY

GEOIP_COUNTRY

-------------

The basename to use for the GeoIP country data file.

Defaults to ``'GeoIP.dat'``.

.. setting:: GEOIP_CITY

GEOIP_CITY

----------

The basename to use for the GeoIP city data file.

Defaults to ``'GeoLiteCity.dat'``.

``GeoIP`` API

=============

.. class:: GeoIP([path=None, cache=0, country=None, city=None])

The ``GeoIP`` object does not require any parameters to use the default 

settings.  However, at the very least the :setting:`GEOIP_PATH` setting

should be set with the path of the location of your GeoIP data sets.  The 

following intialization keywords may be used to customize any of the 

defaults. 

===================  =======================================================

Keyword Arguments    Description

===================  =======================================================

``path``             Base directory to where GeoIP data is located or the 

                     full path to where the city or country data files 

                     (.dat) are located.  Assumes that both the city and 

                     country data sets are located in this directory; 

                     overrides the :setting:`GEOIP_PATH` settings attribute.

``cache``            The cache settings when opening up the GeoIP datasets,

                     and may be an integer in (0, 1, 2, 4) corresponding to

                     the ``GEOIP_STANDARD``, ``GEOIP_MEMORY_CACHE``, 

                     ``GEOIP_CHECK_CACHE``, and ``GEOIP_INDEX_CACHE`` 

                     ``GeoIPOptions`` C API settings, respectively. 

                     Defaults to 0 (``GEOIP_STANDARD``).

``country``          The name of the GeoIP country data file.  Defaults

                     to ``GeoIP.dat``.  Setting this keyword overrides the 

                     :setting:`GEOIP_COUNTRY` settings attribute.

``city``             The name of the GeoIP city data file.  Defaults to

                     ``GeoLiteCity.dat``.  Setting this keyword overrides

                     the :setting:`GEOIP_CITY` settings attribute.

===================  =======================================================

``GeoIP`` Methods

=================

Querying

--------

All the following querying routines may take either a string IP address

or a fully qualified domain name (FQDN).  For example, both 

``'24.124.1.80'`` and ``'djangoproject.com'`` would be valid query 

parameters. 

.. method:: GeoIP.city(query)

Returns a dictionary of city information for the given query.  Some

of the values in the dictionary may be undefined (``None``).

.. method:: GeoIPcountry(query)

Returns a dictionary with the country code and country for the given 

query.

.. method:: GeoIP.country_code(query)

Returns only the country code corresponding to the query.

.. method:: GeoIP.country_name(query)

Returns only the country name corresponding to the query.

Coordinate Retrieval

--------------------

.. method:: GeoIP.coords(query)

Returns a coordinate tuple of (longitude, latitude).

.. method:: GeoIP.lon_lat(query)

Returns a coordinate tuple of (longitude, latitude).

.. method:: GeoIP.lat_lon(query)

Returns a coordinate tuple of (latitude, longitude),

.. method:: GeoIP.geos(query)

Returns a :class:`django.contrib.gis.geos.Point` object corresponding to the query.

Database Information

--------------------

.. attribute:: GeoIP.country_info

This property returns information about the GeoIP country database.

.. attribute:: GeoIP.city_info

This property returns information about the GeoIP city database.

.. attribute:: GeoIP.info

This property returns information about all GeoIP databases (both city

and country).

GeoIP-Python API compatibility methods

----------------------------------------

These methods exist to ease compatibility with any code using MaxMind's 

existing Python API.

.. classmethod:: GeoIP.open(path, cache)

This classmethod instantiates the GeoIP object from the given database path

and given cache setting.

.. method:: GeoIP.region_by_addr(query)

.. method:: GeoIP.region_by_name(query)

.. method:: GeoIP.record_by_addr(query)

.. method:: GeoIP.record_by_name(query)

.. method:: GeoIP.country_code_by_addr(query)

.. method:: GeoIP.country_code_by_name(query)

.. method:: GeoIP.country_name_by_addr(query)

.. method:: GeoIP.country_name_by_name(query)

.. rubric:: Footnotes

.. [#] GeoIP(R) is a registered trademark of MaxMind, LLC of Boston, Massachusetts.