Geolocation with GeoIP2¶
The GeoIP2 object is a wrapper for the MaxMind geoip2 Python
library. [1]
In order to perform IP-based geolocation, the GeoIP2 object requires
the geoip2 Python package and the GeoIP Country and/or City
datasets in binary format (the CSV files will not work!), downloaded from e.g.
MaxMind or DB-IP websites. Grab the GeoLite2-Country.mmdb.gz and
GeoLite2-City.mmdb.gz files and unzip them in a directory corresponding to
the GEOIP_PATH setting.
Additionally, it is recommended to install the libmaxminddb C library, so
that geoip2 can leverage the C library’s faster speed.
Support for .mmdb files downloaded from DB-IP was added.
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 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 |
|---|---|
|
Base directory to where GeoIP data is located or the
full path to where the city or country data files
( |
|
The cache settings when opening up the GeoIP datasets. May
be an integer in (0, 1, 2, 4, 8) corresponding to the
|
|
The name of the GeoIP country data file. Defaults
to |
|
The name of the GeoIP city data file. Defaults to
|
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.
- GeoIP2.city(query)¶
Returns a dictionary of city information for the given query. Some
of the values in the dictionary may be undefined (None).
- GeoIP2.country(query)¶
Returns a dictionary with the country code and country for the given query.
- GeoIP2.country_code(query)¶
Returns the country code corresponding to the query.
- GeoIP2.country_name(query)¶
Returns the country name corresponding to the query.
Coordinate Retrieval¶
- GeoIP2.coords(query)¶
Returns a coordinate tuple of (longitude, latitude).
- GeoIP2.lon_lat(query)¶
Returns a coordinate tuple of (longitude, latitude).
- GeoIP2.lat_lon(query)¶
Returns a coordinate tuple of (latitude, longitude),
- GeoIP2.geos(query)¶
Returns a Point object corresponding to the
query.
Settings¶
GEOIP_PATH¶
A string or 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 GeoIP2 object.
GEOIP_COUNTRY¶
The basename to use for the GeoIP country data file. Defaults to
'GeoLite2-Country.mmdb'.
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
geoip2library.
Footnotes
