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