MaxMind DB Python Module

Description

This is a Python module for reading MaxMind DB files. The module includes both a pure Python reader and an optional C extension.

MaxMind DB is a binary file format that stores data indexed by IP address subnets (IPv4 or IPv6).

Installation

If you want to use the C extension, you must first install libmaxminddb C library installed before installing this extension. If the library is not available, the module will fall-back to a pure Python implementation.

To install maxminddb, type:

$ pip install maxminddb

If you are not able to use pip, you may also use easy_install from the source directory:

$ easy_install .

Usage

To use this module, you must first download or create a MaxMind DB file. We provide free GeoLite2 databases. These files must be decompressed with gunzip.

After you have obtained a database and importing the module, call open_database with a path to the database as the first argument. Optionally, you may pass a mode as the second arguments. The modes are exported from maxminddb. Valid modes are:

• MODE_MMAP_EXT - use the C extension with memory map.
• MODE_MMAP - read from memory map. Pure Python.
• MODE_FILE - read database as standard file. Pure Python.
• MODE_MEMORY - load database into memory. Pure Python.
• MODE_AUTO - try MODE_MMAP_EXT, MODE_MMAP, MODE_FILE in that order. Default.

The open_database function returns a Reader object. To look up an IP address, use the get method on this object. The method will return the corresponding values for the IP address from the database (e.g., a dictionary for GeoIP2/GeoLite2 databases). If the database does not contain a record for that IP address, the method will return None.

Example

>>> import maxminddb
>>>
>>> reader = maxminddb.open_database('GeoLite2-City.mmdb')
>>> reader.get('1.1.1.1')
{'country': ... }
>>>
>>> reader.close()

Exceptions

The module will return an InvalidDatabaseError if the database is corrupt or otherwise invalid. A ValueError will be thrown if you look up an invalid IP address or an IPv6 address in an IPv4 database.

Requirements

This code requires Python 2.6+ or 3.3+. The C extension requires CPython. The pure Python implementation has been tested with PyPy.

On Python 2, the ipaddress module is required.

Versioning

The MaxMind DB Python module uses Semantic Versioning.

Support

Please report all issues with this code using the GitHub issue tracker

If you are having an issue with a MaxMind service that is not specific to this API, please contact MaxMind support for assistance.