Debian Codegraph @

docs/ref/contrib/gis/geoip2.txt

raw
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.