| 1 |
======================= |
| 2 |
Geolocation with GeoIP2 |
| 3 |
======================= |
| 4 |
|
| 5 |
.. module:: django.contrib.gis.geoip2 |
| 6 |
:synopsis: Python interface for MaxMind's GeoIP2 databases. |
| 7 |
|
| 8 |
The :class:`GeoIP2` object is a wrapper for the :pypi:`MaxMind geoip2 Python |
| 9 |
library <geoip2>`. [#]_ |
| 10 |
|
| 11 |
In order to perform IP-based geolocation, the :class:`GeoIP2` object requires |
| 12 |
the :pypi:`geoip2` Python package and the GeoIP ``Country`` and/or ``City`` |
| 13 |
datasets in binary format (the CSV files will not work!), downloaded from e.g. |
| 14 |
`MaxMind`__ or `DB-IP`__ websites. Grab the ``GeoLite2-Country.mmdb.gz`` and |
| 15 |
``GeoLite2-City.mmdb.gz`` files and unzip them in a directory corresponding to |
| 16 |
the :setting:`GEOIP_PATH` setting. |
| 17 |
|
| 18 |
Additionally, it is recommended to install the `libmaxminddb C library`__, so |
| 19 |
that ``geoip2`` can leverage the C library's faster speed. |
| 20 |
|
| 21 |
__ https://dev.maxmind.com/geoip/geolite2-free-geolocation-data |
| 22 |
__ https://db-ip.com/db/lite.php |
| 23 |
__ https://github.com/maxmind/libmaxminddb/ |
| 24 |
|
| 25 |
Example |
| 26 |
======= |
| 27 |
|
| 28 |
Here is an example of its usage: |
| 29 |
|
| 30 |
.. code-block:: pycon |
| 31 |
|
| 32 |
>>> from django.contrib.gis.geoip2 import GeoIP2 |
| 33 |
>>> g = GeoIP2() |
| 34 |
>>> g.country("google.com") |
| 35 |
{'continent_code': 'NA', |
| 36 |
'continent_name': 'North America', |
| 37 |
'country_code': 'US', |
| 38 |
'country_name': 'United States', |
| 39 |
'is_in_european_union': False} |
| 40 |
>>> g.city("72.14.207.99") |
| 41 |
{'accuracy_radius': 1000, |
| 42 |
'city': 'Mountain View', |
| 43 |
'continent_code': 'NA', |
| 44 |
'continent_name': 'North America', |
| 45 |
'country_code': 'US', |
| 46 |
'country_name': 'United States', |
| 47 |
'is_in_european_union': False, |
| 48 |
'latitude': 37.419200897216797, |
| 49 |
'longitude': -122.05740356445312, |
| 50 |
'metro_code': 807, |
| 51 |
'postal_code': '94043', |
| 52 |
'region_code': 'CA', |
| 53 |
'region_name': 'California', |
| 54 |
'time_zone': 'America/Los_Angeles', |
| 55 |
'dma_code': 807, |
| 56 |
'region': 'CA'} |
| 57 |
>>> g.lat_lon("salon.com") |
| 58 |
(39.0437, -77.4875) |
| 59 |
>>> g.lon_lat("uh.edu") |
| 60 |
(-95.4342, 29.834) |
| 61 |
>>> g.geos("24.124.1.80").wkt |
| 62 |
'POINT (-97 38)' |
| 63 |
|
| 64 |
API Reference |
| 65 |
============= |
| 66 |
|
| 67 |
.. class:: GeoIP2(path=None, cache=0, country=None, city=None) |
| 68 |
|
| 69 |
The ``GeoIP`` object does not require any parameters to use the default |
| 70 |
settings. However, at the very least the :setting:`GEOIP_PATH` setting |
| 71 |
should be set with the path of the location of your GeoIP datasets. The |
| 72 |
following initialization keywords may be used to customize any of the |
| 73 |
defaults. |
| 74 |
|
| 75 |
=================== ======================================================= |
| 76 |
Keyword Arguments Description |
| 77 |
=================== ======================================================= |
| 78 |
``path`` Base directory to where GeoIP data is located or the |
| 79 |
full path to where the city or country data files |
| 80 |
(``.mmdb``) are located. Assumes that both the city and |
| 81 |
country datasets are located in this directory; |
| 82 |
overrides the :setting:`GEOIP_PATH` setting. |
| 83 |
|
| 84 |
``cache`` The cache settings when opening up the GeoIP datasets. May |
| 85 |
be an integer in (0, 1, 2, 4, 8) corresponding to the |
| 86 |
``MODE_AUTO``, ``MODE_MMAP_EXT``, ``MODE_MMAP``, and |
| 87 |
``GEOIP_INDEX_CACHE`` ``MODE_MEMORY`` C API settings, |
| 88 |
respectively. Defaults to 0 (``MODE_AUTO``). |
| 89 |
|
| 90 |
``country`` The name of the GeoIP country data file. Defaults |
| 91 |
to ``GeoLite2-Country.mmdb``. Setting this keyword |
| 92 |
overrides the :setting:`GEOIP_COUNTRY` setting. |
| 93 |
|
| 94 |
``city`` The name of the GeoIP city data file. Defaults to |
| 95 |
``GeoLite2-City.mmdb``. Setting this keyword overrides |
| 96 |
the :setting:`GEOIP_CITY` setting. |
| 97 |
=================== ======================================================= |
| 98 |
|
| 99 |
Methods |
| 100 |
======= |
| 101 |
|
| 102 |
Instantiating |
| 103 |
------------- |
| 104 |
|
| 105 |
.. classmethod:: GeoIP2.open(path, cache) |
| 106 |
|
| 107 |
This classmethod instantiates the GeoIP object from the given database path |
| 108 |
and given cache setting. |
| 109 |
|
| 110 |
.. deprecated:: 5.1 |
| 111 |
|
| 112 |
Use the :class:`GeoIP2()` constructor instead. |
| 113 |
|
| 114 |
Querying |
| 115 |
-------- |
| 116 |
|
| 117 |
All the following querying routines may take an instance of |
| 118 |
:class:`~ipaddress.IPv4Address` or :class:`~ipaddress.IPv6Address`, a string IP |
| 119 |
address, or a fully qualified domain name (FQDN). For example, |
| 120 |
``IPv4Address("205.186.163.125")``, ``"205.186.163.125"``, and |
| 121 |
``"djangoproject.com"`` would all be valid query parameters. |
| 122 |
|
| 123 |
.. method:: GeoIP2.city(query) |
| 124 |
|
| 125 |
Returns a dictionary of city information for the given query. Some |
| 126 |
of the values in the dictionary may be undefined (``None``). |
| 127 |
|
| 128 |
.. method:: GeoIP2.country(query) |
| 129 |
|
| 130 |
Returns a dictionary with the country code and country for the given |
| 131 |
query. |
| 132 |
|
| 133 |
.. method:: GeoIP2.country_code(query) |
| 134 |
|
| 135 |
Returns the country code corresponding to the query. |
| 136 |
|
| 137 |
.. method:: GeoIP2.country_name(query) |
| 138 |
|
| 139 |
Returns the country name corresponding to the query. |
| 140 |
|
| 141 |
Coordinate Retrieval |
| 142 |
-------------------- |
| 143 |
|
| 144 |
.. method:: GeoIP2.coords(query) |
| 145 |
|
| 146 |
Returns a coordinate tuple of (longitude, latitude). |
| 147 |
|
| 148 |
.. deprecated:: 5.1 |
| 149 |
|
| 150 |
Use :meth:`.GeoIP2.lon_lat` instead. |
| 151 |
|
| 152 |
.. method:: GeoIP2.lon_lat(query) |
| 153 |
|
| 154 |
Returns a coordinate tuple of (longitude, latitude). |
| 155 |
|
| 156 |
.. method:: GeoIP2.lat_lon(query) |
| 157 |
|
| 158 |
Returns a coordinate tuple of (latitude, longitude), |
| 159 |
|
| 160 |
.. method:: GeoIP2.geos(query) |
| 161 |
|
| 162 |
Returns a :class:`~django.contrib.gis.geos.Point` object corresponding to the |
| 163 |
query. |
| 164 |
|
| 165 |
Settings |
| 166 |
======== |
| 167 |
|
| 168 |
.. setting:: GEOIP_PATH |
| 169 |
|
| 170 |
``GEOIP_PATH`` |
| 171 |
-------------- |
| 172 |
|
| 173 |
A string or :class:`pathlib.Path` specifying the directory where the GeoIP data |
| 174 |
files are located. This setting is *required* unless manually specified |
| 175 |
with ``path`` keyword when initializing the :class:`GeoIP2` object. |
| 176 |
|
| 177 |
.. setting:: GEOIP_COUNTRY |
| 178 |
|
| 179 |
``GEOIP_COUNTRY`` |
| 180 |
----------------- |
| 181 |
|
| 182 |
The basename to use for the GeoIP country data file. Defaults to |
| 183 |
``'GeoLite2-Country.mmdb'``. |
| 184 |
|
| 185 |
.. setting:: GEOIP_CITY |
| 186 |
|
| 187 |
``GEOIP_CITY`` |
| 188 |
-------------- |
| 189 |
|
| 190 |
The basename to use for the GeoIP city data file. Defaults to |
| 191 |
``'GeoLite2-City.mmdb'``. |
| 192 |
|
| 193 |
Exceptions |
| 194 |
========== |
| 195 |
|
| 196 |
.. exception:: GeoIP2Exception |
| 197 |
|
| 198 |
The exception raised when an error occurs in the :class:`GeoIP2` wrapper. |
| 199 |
Exceptions from the underlying ``geoip2`` library are passed through |
| 200 |
unchanged. |
| 201 |
|
| 202 |
.. rubric:: Footnotes |
| 203 |
.. [#] GeoIP(R) is a registered trademark of MaxMind, Inc. |