/docs/ref/contrib/gis/geoip.txt

  1.. _ref-geoip:
  2
  3======================
  4Geolocation 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
 12The :class:`GeoIP` object is a ctypes wrapper for the
 13`MaxMind GeoIP C API`__. [#]_  This interface is a BSD-licensed alternative
 14to the GPL-licensed `Python GeoIP`__ interface provided by MaxMind.
 15
 16In order to perform IP-based geolocation, the :class:`GeoIP` object requires
 17the GeoIP C libary and either the GeoIP `Country`__ or `City`__ 
 18datasets 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``
 20and unzip them in a directory corresponding to what you set 
 21:setting:`GEOIP_PATH` with in your settings.  See the example and reference below
 22for 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
 30Example
 31=======
 32
 33Assuming you have the GeoIP C library installed, here is an example of its
 34usage::
 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
 63GEOIP_PATH
 64----------
 65
 66A string specifying the directory where the GeoIP data files are
 67located.  This setting is *required* unless manually specified
 68with ``path`` keyword when initializing the :class:`GeoIP` object.
 69
 70.. setting:: GEOIP_LIBRARY_PATH
 71
 72GEOIP_LIBRARY_PATH
 73------------------
 74
 75A string specifying the location of the GeoIP C library.  Typically,
 76this setting is only used if the GeoIP C library is in a non-standard
 77location (e.g., ``/home/sue/lib/libGeoIP.so``).
 78
 79.. setting:: GEOIP_COUNTRY
 80
 81GEOIP_COUNTRY
 82-------------
 83
 84The basename to use for the GeoIP country data file.
 85Defaults to ``'GeoIP.dat'``.
 86
 87.. setting:: GEOIP_CITY
 88
 89GEOIP_CITY
 90----------
 91
 92The basename to use for the GeoIP city data file.
 93Defaults to ``'GeoLiteCity.dat'``.
 94
 95``GeoIP`` API
 96=============
 97
 98.. class:: GeoIP([path=None, cache=0, country=None, city=None])
 99
100The ``GeoIP`` object does not require any parameters to use the default 
101settings.  However, at the very least the :setting:`GEOIP_PATH` setting
102should be set with the path of the location of your GeoIP data sets.  The 
103following intialization keywords may be used to customize any of the 
104defaults. 
105
106===================  =======================================================
107Keyword 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
134Querying
135--------
136
137All the following querying routines may take either a string IP address
138or a fully qualified domain name (FQDN).  For example, both 
139``'24.124.1.80'`` and ``'djangoproject.com'`` would be valid query 
140parameters. 
141
142.. method:: GeoIP.city(query)
143
144Returns a dictionary of city information for the given query.  Some
145of the values in the dictionary may be undefined (``None``).
146
147.. method:: GeoIPcountry(query)
148
149Returns a dictionary with the country code and country for the given 
150query.
151
152.. method:: GeoIP.country_code(query)
153
154Returns only the country code corresponding to the query.
155
156.. method:: GeoIP.country_name(query)
157
158Returns only the country name corresponding to the query.
159
160Coordinate Retrieval
161--------------------
162
163.. method:: GeoIP.coords(query)
164
165Returns a coordinate tuple of (longitude, latitude).
166
167.. method:: GeoIP.lon_lat(query)
168
169Returns a coordinate tuple of (longitude, latitude).
170
171.. method:: GeoIP.lat_lon(query)
172
173Returns a coordinate tuple of (latitude, longitude),
174
175.. method:: GeoIP.geos(query)
176
177Returns a :class:`django.contrib.gis.geos.Point` object corresponding to the query.
178
179Database Information
180--------------------
181
182.. attribute:: GeoIP.country_info
183
184This property returns information about the GeoIP country database.
185
186.. attribute:: GeoIP.city_info
187
188This property returns information about the GeoIP city database.
189
190.. attribute:: GeoIP.info
191
192This property returns information about all GeoIP databases (both city
193and country).
194
195GeoIP-Python API compatibility methods
196----------------------------------------
197
198These methods exist to ease compatibility with any code using MaxMind's 
199existing Python API.
200
201.. classmethod:: GeoIP.open(path, cache)
202
203This classmethod instantiates the GeoIP object from the given database path
204and 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.