==============================
GeoIP API
==============================

The ``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 ``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 
``settings.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)'

Initialization
==============================

The ``GeoIP`` object does not require any parameters to use the default 
settings.  However, at the very least the ``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 ``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``) -- see the cache
                         settings table below for more details.
 
    ``country``          The name of the GeoIP country data file.  Defaults
                         to ``GeoIP.dat``.  Setting this keyword overrides the 
                         ``GEOIP_COUNTRY`` settings attribute.

    ``city``             The name of the GeoIP city data file.  Defaults to
                         ``GeoLiteCity.dat``.  Setting this keyword overrides
                         the ``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. 

``city(query)``
^^^^^^^^^^^^^^^^^^^^^^^^^^
Returns a dictionary of city information for the given query.  Some
of the values in the dictionary may be undefined (``None``).

``country(query)``
^^^^^^^^^^^^^^^^^^^^^^^^^^
Returns a dictionary with the country code and country for the given 
query.

``country_code(query)``
^^^^^^^^^^^^^^^^^^^^^^^^^^

``country_name(query)``
^^^^^^^^^^^^^^^^^^^^^^^^^^

Coordinate Retrieval
--------------------------

``coords(query)``
^^^^^^^^^^^^^^^^^^^^^^^^^^

``lon_lat(query)``
^^^^^^^^^^^^^^^^^^^^^^^^^^

``lat_lon(query)``
^^^^^^^^^^^^^^^^^^^^^^^^^^

``geos(query)``
^^^^^^^^^^^^^^^^^^^^^^^^^^

GeoIP Database Information
---------------------------

``country_info``
^^^^^^^^^^^^^^^^^^^^^^^^^^^
This property returns information about the GeoIP country database.

``city_info``
^^^^^^^^^^^^^^^^^^^^^^^^^^^
This property returns information about the GeoIP city database.

``info``
^^^^^^^^^^^^^^^^^^^^^^^^^^^
This property returns information about all GeoIP databases (both city
and country).

GeoIP-Python API compatibility methods
----------------------------------------

[explanation]

``open(path, cache)``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
This classmethod instantiates the GeoIP object from the given database path
and given cache setting.

``regioin_by_addr(query)``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

``region_by_name(query)``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

``record_by_addr(query)``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

``record_by_name(query)``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

``country_code_by_addr(query)``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

``country_code_by_name(query)``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

``country_name_by_addr(query)``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

``country_name_by_name(query)``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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