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.
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)
-