diff options
Diffstat (limited to 'parts/django/docs/ref/contrib/gis/geoip.txt')
| -rw-r--r-- | parts/django/docs/ref/contrib/gis/geoip.txt | 223 |
1 files changed, 0 insertions, 223 deletions
diff --git a/parts/django/docs/ref/contrib/gis/geoip.txt b/parts/django/docs/ref/contrib/gis/geoip.txt deleted file mode 100644 index 784d69e..0000000 --- a/parts/django/docs/ref/contrib/gis/geoip.txt +++ /dev/null @@ -1,223 +0,0 @@ -.. _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. |