Pure Python GeoIP API

This library is based on Maxmind’s GeoIP C API.

Tested with Python version 2.6, 2.7, 3.2 and 3.3.

Build Status Coverage Status Downloads

Installation

You can easily install pygeoip from PyPi.

pip install pygeoip

Issues and Contribution

Bug reports are done by creating an issue on Github. If you want to contribute you can always create a pull request for discussion and code submission.

Documentation

Getting Started

Create your GeoIP instance with appropriate access flag. STANDARD reads data from disk when needed, MEMORY_CACHE loads database into memory on instantiation and MMAP_CACHE loads database into memory using mmap.

>>> import pygeoip
>>> gi = pygeoip.GeoIP('GeoIP.dat')
>>> gi.country_name_by_addr('64.233.161.99')
'United States'

Country Lookup

>>> gi = pygeoip.GeoIP('GeoIP.dat')
>>> gi.country_code_by_name('google.com')
'US'
>>> gi.country_code_by_addr('64.233.161.99')
'US'
>>> gi.country_name_by_addr('64.233.161.99')
'United States'

>>> gi = pygeoip.GeoIP('GeoIPv6.dat')
>>> gi.country_code_by_addr('2a00:1450:400f:802::1006')
'IE'

Region Lookup

>>> gi = pygeoip.GeoIP('GeoIPRegion.dat')
>>> gi.region_by_name('apple.com')
{'region_code': 'CA', 'country_code': 'US'}

City Lookup

>>> gi = pygeoip.GeoIP('GeoIPCity.dat')
>>> gi.record_by_addr('64.233.161.99')
{
    'city': u'Mountain View',
    'region_code': u'CA',
    'area_code': 650,
    'time_zone': 'America/Los_Angeles',
    'dma_code': 807,
    'metro_code': 'San Francisco, CA',
    'country_code3': 'USA',
    'latitude': 37.41919999999999,
    'postal_code': u'94043',
    'longitude': -122.0574,
    'country_code': 'US',
    'country_name': 'United States',
    'continent': 'NA'
}
>>> gi.time_zone_by_addr('64.233.161.99')
'America/Los_Angeles'

Organization Lookup

>>> gi = pygeoip.GeoIP('GeoIPOrg.dat')
>>> gi.org_by_name('dell.com')
'Dell Computer Corporation'

ISP Lookup

>>> gi = pygeoip.GeoIP('GeoIPISP.dat')
>>> gi.isp_by_name('cnn.com')
'Turner Broadcasting System'

ASN Lookup

>>> gi = pygeoip.GeoIP('GeoIPASNum.dat')
>>> gi.asn_by_name('cnn.com')
'AS5662 Turner Broadcasting'

Supported Databases

Type IPv4 IPv6 Details
Country Yes Yes MaxMind Country product page
City Yes Yes MaxMind City product page
Organization Yes   MaxMind Organization product page
ISP Yes   MaxMind ISP product page
Region Yes   MaxMind Region product page
ASN Yes Yes MaxMind ASN product page
Netspeed Yes   MaxMind Netspeed product page

API Reference

GeoIP

class pygeoip.GeoIP(filename, flags=0, cache=True)
__init__(filename, flags=0, cache=True)

Create and return an GeoIP instance.

Parameters:
  • filename – File path to a GeoIP database
  • flags – Flags that affect how the database is processed. Currently supported flags are STANDARD (default), MEMORY_CACHE (preload the whole file into memory) and MMAP_CACHE (access the file via mmap)
  • cache – Used in tests to skip instance caching
country_code_by_addr(addr)

Returns 2-letter country code (e.g. US) from IP address.

Parameters:addr – IP address (e.g. 203.0.113.30)
country_code_by_name(hostname)

Returns 2-letter country code (e.g. US) from hostname.

Parameters:hostname – Hostname (e.g. example.com)
country_name_by_addr(addr)

Returns full country name for specified IP address.

Parameters:addr – IP address (e.g. 203.0.113.30)
country_name_by_name(hostname)

Returns full country name for specified hostname.

Parameters:hostname – Hostname (e.g. example.com)
id_by_addr(addr)

Returns the database ID for specified address. The ID might be useful as array index. 0 is unknown.

Parameters:addr – IPv4 or IPv6 address (eg. 203.0.113.30)
last_netmask()

Returns the netmask depth of the last lookup.

netspeed_by_addr(addr)

Returns NetSpeed name from address.

Parameters:addr – IP address (e.g. 203.0.113.30)
netspeed_by_name(hostname)

Returns NetSpeed name from hostname. Can be Unknown, Dial-up, Cable, or Corporate.

Parameters:hostname – Hostname (e.g. example.com)
org_by_addr(addr)

Returns Organization, ISP, or ASNum name for given IP address.

Parameters:addr – IP address (e.g. 203.0.113.30)
org_by_name(hostname)

Returns Organization, ISP, or ASNum name for given hostname.

Parameters:hostname – Hostname (e.g. example.com)
record_by_addr(addr)

Returns dictionary with city data containing country_code, country_name, region, city, postal_code, latitude, longitude, dma_code, metro_code, area_code, region_code and time_zone.

Parameters:addr – IP address (e.g. 203.0.113.30)
record_by_name(hostname)

Returns dictionary with city data containing country_code, country_name, region, city, postal_code, latitude, longitude, dma_code, metro_code, area_code, region_code and time_zone.

Parameters:hostname – Hostname (e.g. example.com)
region_by_addr(addr)

Returns dictionary containing country_code and region_code.

Parameters:addr – IP address (e.g. 203.0.113.30)
region_by_name(hostname)

Returns dictionary containing country_code and region_code.

Parameters:hostname – Hostname (e.g. example.com)
time_zone_by_addr(addr)

Returns time zone in tzdata format (e.g. America/New_York or Europe/Paris)

Parameters:addr – IP address (e.g. 203.0.113.30)
time_zone_by_name(hostname)

Returns time zone in tzdata format (e.g. America/New_York or Europe/Paris)

Parameters:hostname – Hostname (e.g. example.com)

GeoIPError

exception pygeoip.GeoIPError

Thin wrapper of Exception, will be thrown in case of an unrecoverable error.

For more information, check out the documentation over at Read the Docs.