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

class GeoIP2(path=None, cache=0, country=None, city=None)[source]

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

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 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 GEOIP_COUNTRY setting.

city

The name of the GeoIP city data file. Defaults to GeoLite2-City.mmdb. Setting this keyword overrides the GEOIP_CITY setting.

Methods

Instantiating

classmethod GeoIP2.open(path, cache)[source]

This classmethod instantiates the GeoIP object from the given database path and given cache setting.

Deprecated since version 5.1: Use the GeoIP2() constructor instead.

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.

GeoIP2.city(query)[source]

Returns a dictionary of city information for the given query. Some of the values in the dictionary may be undefined (None).

GeoIP2.country(query)[source]

Returns a dictionary with the country code and country for the given query.

GeoIP2.country_code(query)[source]

Returns the country code corresponding to the query.

GeoIP2.country_name(query)[source]

Returns the country name corresponding to the query.

Coordinate Retrieval

GeoIP2.coords(query)[source]

Returns a coordinate tuple of (longitude, latitude).

Deprecated since version 5.1: Use GeoIP2.lon_lat() instead.

GeoIP2.lon_lat(query)[source]

Returns a coordinate tuple of (longitude, latitude).

GeoIP2.lat_lon(query)[source]

Returns a coordinate tuple of (latitude, longitude),

GeoIP2.geos(query)[source]

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 GeoIP2 wrapper. Exceptions from the underlying geoip2 library are passed through unchanged.

Footnotes

GDAL API
GeoDjango Utilities
Back to Top