mirror of https://github.com/django/django.git
224 lines
6.8 KiB
Plaintext
224 lines
6.8 KiB
Plaintext
.. _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.regioin_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.
|