2.6. lars.geoip - GeoIP Database Access

This module provides a common interface to the GeoIP database. Most users will only need to be aware of the init_database() function in this module, which is used to initialize the GeoIP database(s). All other functions should be ignored; instead, users should use the country, region, city, and coords attributes of the IPv4Address and IPv6Address classes.

2.6.1. Functions

lars.geoip.init_database(v4_filename, v6_filename=None, memcache=True)

Initializes the global GeoIP database instance in a thread-safe manner.

This function opens GeoIP databases for use by the IPv4Address and IPv6Address classes. GeoIP databases are hierarchical: if you open a country-only database, you will only be able to use country-level lookups. However, city-level databases enable all supported lookups (country, region, city, and coordinates).

By default, the function caches the entire content of (both) the database(s) in memory (on the assumption that just about any machine has more than sufficient RAM for this), but this behaviour can be overridden with the memcache parameter.

The optional v6_filename parameter specifies the location of the IPv6 database which will be used for IPv6 addresses. The GeoIP IPv6 databases are orthogonal to the IPv4 databases (you cannot lookup IPv4 addresses using an IPv6 database) - hence why the two databases are stored and specified separately.

Warning

At the time of writing, the free GeoLite IPv6 city-level database does not work (the authors seem to be using a new database format which the pygeoip API does not yet know). This does not affect the IPv4 city-level database.

Parameters:

• v4_filename (str) – The filename of the IPv4 database
• v6_filename (str) – The filename of the IPv6 database (optional)
• memcache (bool) – Set to False if you don’t wish to cache the db in RAM (optional)

lars.geoip.country_code_by_addr(address)

Returns the country code associated with the specified address. You should use the country attribute instead of this function.

Parameters:address (str) – The address to lookup the country for Returns str:The country code associated with the address, or None

lars.geoip.country_code_by_addr_v6(address)

Returns the country code associated with the specified address. You should use the country attribute instead of this function.

Parameters:address (str) – The address to lookup the country for Returns str:The country code associated with the address, or None

lars.geoip.city_by_addr(address)

Returns the city associated with the address. You should use the city attribute instead of this function.

Given an address, this function returns the city associated with it. Note: this function will raise an exception if the GeoIP database loaded is above city level.

Parameters:address (str) – The address to lookup the city for Returns str:The city associated with the address, or None

lars.geoip.city_by_addr_v6(address)

Returns the city associated with the address. You should use the city attribute instead of this function.

Given an address, this function returns the city associated with it. Note: this function will raise an exception if the GeoIP database loaded is above city level.

Parameters:address (str) – The address to lookup the city for Returns str:The city associated with the address, or None

lars.geoip.region_by_addr(address)

Returns the region (e.g. state) associated with the address. You should use the region attribute instead of this function.

Given an address, this function returns the region associated with it. In the case of the US, this is the state. In the case of other countries it may be a state, county, something GeoIP-specific or simply undefined. Note: this function will raise an exception if the GeoIP database loaded is country-level only.

Parameters:address (str) – The address to lookup the region for Returns str:The region associated with the address, or None

lars.geoip.region_by_addr_v6(address)

Returns the region (e.g. state) associated with the address. You should use the region attribute instead of this function.

Given an address, this function returns the region associated with it. In the case of the US, this is the state. In the case of other countries it may be a state, county, something GeoIP-specific or simply undefined. Note: this function will raise an exception if the GeoIP database loaded is country-level only.

Parameters:address (str) – The address to lookup the region for Returns str:The region associated with the address, or None

lars.geoip.coords_by_addr(address)

Returns the coordinates (long, lat) associated with the address. You should use the coords attribute instead of this function.

Given an address, this function returns a tuple with the attributes longitude and latitude (in that order) representing the (very) approximate coordinates of the address on the globe. Note: this function will raise an exception if the GeoIP database loaded is above city level.

Parameters:address (str) – The address to locate Returns str:The coordinates associated with the address, or None

lars.geoip.coords_by_addr_v6(address)

Returns the coordinates (long, lat) associated with the address. You should use the coords attribute instead of this function.

Given an address, this function returns a tuple with the attributes longitude and latitude (in that order) representing the (very) approximate coordinates of the address on the globe. Note: this function will raise an exception if the GeoIP database loaded is above city level.

Parameters:address (str) – The address to locate Returns str:The coordinates associated with the address, or None

2.6.2. Examples