python-geoip

python-geoip is a library that provides access to GeoIP databases. Currently it only supports accessing MaxMind databases. It’s similar to other GeoIP libraries but comes under the very liberal BSD license and also provides an extra library that optionally ships a recent version of the Geolite2 database as provided by MaxMind.

The python-geoip-geolite2 package includes GeoLite2 data created by MaxMind, available from maxmind.com under the Creative Commons Attribution-ShareAlike 3.0 Unported License.

Installation

You can get the library directly from PyPI:

pip install python-geoip

If you also want the free MaxMind Geolite2 database you can in addition:

pip install python-geoip-geolite2

Usage

If you have installed the python-geoip-geolite2 package you can start using the GeoIP database right away:

>>> from geoip import geolite2
>>> match = geolite2.lookup('17.0.0.1')
>>> match is not None
True
>>> match.country
'US'
>>> match.continent
'NA'
>>> match.timezone
'America/Los_Angeles'
>>> match.subdivisions
frozenset(['CA'])

If you want to use your own MaxMind database (for instance because you paid for the commercial version) you can open the database yourself:

>>> from geoip import open_database
>>> db = open_database('path/to/my.mmdb')

API

geoip.open_database(filename)

Open a given database. This currently only supports maxmind databases (mmdb). If the file cannot be opened an IOError is raised.

geoip.geolite2 = <PackagedDatabase 'geolite2'>

Provides access to the geolite2 cities database. In order to use this database the python-geoip-geolite2 package needs to be installed.

class geoip.Database

Provides access to a GeoIP database. This is an abstract class that is implemented by different providers. The open_database() function can be used to open a MaxMind database.

Example usage:

from geoip import open_database

with open_database('data/GeoLite2-City.mmdb') as db:
    match = db.lookup_mine()
    print 'My IP info:', match
close()

Closes the database. The whole object can also be used as a context manager. Databases that are packaged up (such as the geolite2 database) do not need to be closed.

get_info()

Returns an info object about the database. This can be used to check for the build date of the database or what provides the GeoIP data.

Return type:DatabaseInfo
get_metadata()

Return the metadata dictionary of the loaded database. This dictionary is specific to the database provider.

lookup(ip_addr)

Looks up the IP information in the database and returns a IPInfo. If it does not exist, None is returned. What IP addresses are supported is specific to the GeoIP provider.

Return type:IPInfo
lookup_mine()

Looks up the computer’s IP by asking a web service and then checks the database for a match.

Return type:IPInfo
class geoip.IPInfo(ip, data)

Provides information about the located IP as returned by Database.lookup().

continent

The continent as ISO code if available.

country

The country code as ISO code if available.

get_info_dict()

Returns the internal info dictionary. For a maxmind database this is the metadata dictionary.

ip

The IP that was looked up.

location

The location as (lat, long) tuple if available.

subdivisions

The subdivisions as a list of ISO codes as an immutable set.

timezone

The timezone if available as tzinfo name.

to_dict()

A dict representation of the available information. This is a dictionary with the same keys as the attributes of this object.

class geoip.DatabaseInfo

Provides information about the GeoIP database.

date = None

Optionally the build date of the database as datetime object.

filename = None

If available the filename which backs the database.

internal_name = None

Optionally the internal name of the database.

provider = None

Optionally the name of the database provider.