/docs/ref/contrib/gis/geoip.txt
Plain Text | 223 lines | 154 code | 69 blank | 0 comment | 0 complexity | 721f1b6c180c0fc4a64b1487d6cb7efa MD5 | raw file
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.