Django-1.2.1/docs/ref/contrib/gis/geoip.txt

   1 .. _ref-geoip:
   2
   3 ======================
   4 Geolocation with GeoIP
   5 ======================
   6
   7 .. module:: django.contrib.gis.utils.geoip
   8    :synopsis: High-level Python interface for MaxMind's GeoIP C library.
   9
  10 .. currentmodule:: django.contrib.gis.utils
  11
  12 The :class:`GeoIP` object is a ctypes wrapper for the
  13 `MaxMind GeoIP C API`__. [#]_  This interface is a BSD-licensed alternative
  14 to the GPL-licensed `Python GeoIP`__ interface provided by MaxMind.
  15
  16 In order to perform IP-based geolocation, the :class:`GeoIP` object requires
  17 the GeoIP C libary and either the GeoIP `Country`__ or `City`__
  18 datasets in binary format (the CSV files will not work!).  These datasets may be
  19 `downloaded from MaxMind`__.  Grab the ``GeoIP.dat.gz`` and ``GeoLiteCity.dat.gz``
  20 and unzip them in a directory corresponding to what you set
  21 ``GEOIP_PATH`` with in your settings.  See the example and reference below
  22 for more details.
  23
  24 __ http://www.maxmind.com/app/c
  25 __ http://www.maxmind.com/app/python
  26 __ http://www.maxmind.com/app/country
  27 __ http://www.maxmind.com/app/city
  28 __ http://www.maxmind.com/download/geoip/database/
  29
  30 Example
  31 =======
  32
  33 Assuming you have the GeoIP C library installed, here is an example of its
  34 usage::
  35
  36      >>> from django.contrib.gis.utils import GeoIP
  37      >>> g = GeoIP()
  38      >>> g.country('google.com')
  39      {'country_code': 'US', 'country_name': 'United States'}
  40      >>> g.city('72.14.207.99')
  41      {'area_code': 650,
  42      'city': 'Mountain View',
  43      'country_code': 'US',
  44      'country_code3': 'USA',
  45      'country_name': 'United States',
  46      'dma_code': 807,
  47      'latitude': 37.419200897216797,
  48      'longitude': -122.05740356445312,
  49      'postal_code': '94043',
  50      'region': 'CA'}
  51      >>> g.lat_lon('salon.com')
  52      (37.789798736572266, -122.39420318603516)
  53      >>> g.lon_lat('uh.edu')
  54      (-95.415199279785156, 29.77549934387207)
  55      >>> g.geos('24.124.1.80').wkt
  56      'POINT (-95.2087020874023438 39.0392990112304688)'
  57
  58 ``GeoIP`` Settings
  59 ==================
  60
  61 .. setting:: GEOIP_PATH
  62
  63 GEOIP_PATH
  64 ----------
  65
  66 A string specifying the directory where the GeoIP data files are
  67 located.  This setting is *required* unless manually specified
  68 with ``path`` keyword when initializing the :class:`GeoIP` object.
  69
  70 .. setting:: GEOIP_LIBRARY_PATH
  71
  72 GEOIP_LIBRARY_PATH
  73 ------------------
  74
  75 A string specifying the location of the GeoIP C library.  Typically,
  76 this setting is only used if the GeoIP C library is in a non-standard
  77 location (e.g., ``/home/sue/lib/libGeoIP.so``).
  78
  79 .. setting:: GEOIP_COUNTRY
  80
  81 GEOIP_COUNTRY
  82 -------------
  83
  84 The basename to use for the GeoIP country data file.
  85 Defaults to ``'GeoIP.dat'``.
  86
  87 .. setting:: GEOIP_CITY
  88
  89 GEOIP_CITY
  90 ----------
  91
  92 The basename to use for the GeoIP city data file.
  93 Defaults to ``'GeoLiteCity.dat'``.
  94
  95 ``GeoIP`` API
  96 =============
  97
  98 .. class:: GeoIP([path=None, cache=0, country=None, city=None])
  99
 100 The ``GeoIP`` object does not require any parameters to use the default
 101 settings.  However, at the very least the :setting:`GEOIP_PATH` setting
 102 should be set with the path of the location of your GeoIP data sets.  The
 103 following intialization keywords may be used to customize any of the
 104 defaults.
 105
 106 ===================  =======================================================
 107 Keyword Arguments    Description
 108 ===================  =======================================================
 109 ``path``             Base directory to where GeoIP data is located or the
 110                      full path to where the city or country data files
 111                      (.dat) are located.  Assumes that both the city and
 112                      country data sets are located in this directory;
 113                      overrides the :setting:`GEOIP_PATH` settings attribute.
 114
 115 ``cache``            The cache settings when opening up the GeoIP datasets,
 116                      and may be an integer in (0, 1, 2, 4) corresponding to
 117                      the ``GEOIP_STANDARD``, ``GEOIP_MEMORY_CACHE``,
 118                      ``GEOIP_CHECK_CACHE``, and ``GEOIP_INDEX_CACHE``
 119                      ``GeoIPOptions`` C API settings, respectively.
 120                      Defaults to 0 (``GEOIP_STANDARD``).
 121
 122 ``country``          The name of the GeoIP country data file.  Defaults
 123                      to ``GeoIP.dat``.  Setting this keyword overrides the
 124                      :setting:`GEOIP_COUNTRY` settings attribute.
 125
 126 ``city``             The name of the GeoIP city data file.  Defaults to
 127                      ``GeoLiteCity.dat``.  Setting this keyword overrides
 128                      the :setting:`GEOIP_CITY` settings attribute.
 129 ===================  =======================================================
 130
 131 ``GeoIP`` Methods
 132 =================
 133
 134 Querying
 135 --------
 136
 137 All the following querying routines may take either a string IP address
 138 or a fully qualified domain name (FQDN).  For example, both
 139 ``'24.124.1.80'`` and ``'djangoproject.com'`` would be valid query
 140 parameters.
 141
 142 .. method:: GeoIP.city(query)
 143
 144 Returns a dictionary of city information for the given query.  Some
 145 of the values in the dictionary may be undefined (``None``).
 146
 147 .. method:: GeoIPcountry(query)
 148
 149 Returns a dictionary with the country code and country for the given
 150 query.
 151
 152 .. method:: GeoIP.country_code(query)
 153
 154 Returns only the country code corresponding to the query.
 155
 156 .. method:: GeoIP.country_name(query)
 157
 158 Returns only the country name corresponding to the query.
 159
 160 Coordinate Retrieval
 161 --------------------
 162
 163 .. method:: GeoIP.coords(query)
 164
 165 Returns a coordinate tuple of (longitude, latitude).
 166
 167 .. method:: GeoIP.lon_lat(query)
 168
 169 Returns a coordinate tuple of (longitude, latitude).
 170
 171 .. method:: GeoIP.lat_lon(query)
 172
 173 Returns a coordinate tuple of (latitude, longitude),
 174
 175 .. method:: GeoIP.geos(query)
 176
 177 Returns a :class:`django.contrib.gis.geos.Point` object corresponding to the query.
 178
 179 Database Information
 180 --------------------
 181
 182 .. attribute:: GeoIP.country_info
 183
 184 This property returns information about the GeoIP country database.
 185
 186 .. attribute:: GeoIP.city_info
 187
 188 This property returns information about the GeoIP city database.
 189
 190 .. attribute:: GeoIP.info
 191
 192 This property returns information about all GeoIP databases (both city
 193 and country).
 194
 195 GeoIP-Python API compatibility methods
 196 ----------------------------------------
 197
 198 These methods exist to ease compatibility with any code using MaxMind's
 199 existing Python API.
 200
 201 .. classmethod:: GeoIP.open(path, cache)
 202
 203 This classmethod instantiates the GeoIP object from the given database path
 204 and given cache setting.
 205
 206 .. method:: GeoIP.region_by_addr(query)
 207
 208 .. method:: GeoIP.region_by_name(query)
 209
 210 .. method:: GeoIP.record_by_addr(query)
 211
 212 .. method:: GeoIP.record_by_name(query)
 213
 214 .. method:: GeoIP.country_code_by_addr(query)
 215
 216 .. method:: GeoIP.country_code_by_name(query)
 217
 218 .. method:: GeoIP.country_name_by_addr(query)
 219
 220 .. method:: GeoIP.country_name_by_name(query)
 221
 222 .. rubric:: Footnotes
 223 .. [#] GeoIP(R) is a registered trademark of MaxMind, LLC of Boston, Massachusetts.