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.
Example¶
Here is an example of its usage:
>>> from django.contrib.gis.geoip2 import GeoIP2
>>> g = GeoIP2()
>>> g.country("google.com")
{'continent_code': 'NA',
'continent_name': 'North America',
'country_code': 'US',
'country_name': 'United States',
'is_in_european_union': False}
>>> g.city("72.14.207.99")
{'accuracy_radius': 1000,
'city': 'Mountain View',
'continent_code': 'NA',
'continent_name': 'North America',
'country_code': 'US',
'country_name': 'United States',
'is_in_european_union': False,
'latitude': 37.419200897216797,
'longitude': -122.05740356445312,
'metro_code': 807,
'postal_code': '94043',
'region_code': 'CA',
'region_name': 'California',
'time_zone': 'America/Los_Angeles',
'dma_code': 807,
'region': 'CA'}
>>> 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¶
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¶
Querying¶
All the following querying routines may take an instance of
IPv4Address or IPv6Address, a string IP
address, or a fully qualified domain name (FQDN). For example,
IPv4Address("205.186.163.125"), "205.186.163.125", and
"djangoproject.com" would all be valid query parameters.
Returns a dictionary of city information for the given query. Some
of the values in the dictionary may be undefined (None).
Returns a dictionary with the country code and country for the given query.
Returns the country code corresponding to the query.
Returns the country name corresponding to the query.
Coordinate Retrieval¶
Returns a coordinate tuple of (longitude, latitude).
Returns a coordinate tuple of (latitude, longitude),
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[source]¶
The exception raised when an error occurs in the
GeoIP2wrapper. Exceptions from the underlyinggeoip2library are passed through unchanged.
Footnotes
