3.5. 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.
3.5.1. Functions¶
-
lars.geoip.
init_databases
(v4_geo_filename=None, v4_isp_filename=None, v4_org_filename=None, v6_geo_filename=None, v6_isp_filename=None, v6_org_filename=None, memcache=True)[source]¶ Initializes the global GeoIP database instances in a thread-safe manner.
This function opens GeoIP databases for use by the
IPv4Address
andIPv6Address
classes. There are several types of GeoIP databases. The country, region, and city databases are considered “geographical” databases and should be specified for the v4_geo_filename and/or v6_geo_filename databases (for IPv4 and IPv6 databases respectively). The ISP and organisational databases are treated separately as they contain no geographical information. If you have such databases, specify them as the values of the v4_isp_filename, v6_isp_filename, v4_org_filename, and v6_org_filename parameters (all optional).GeoIP geographical databases are hierarchical: if you open a country database, you will only be able to use country-level lookups. However, city-level databases enable all geographical lookups (country, region, city, and coordinates).
By default, the function caches the entire content of database(s) in memory (on the assumption that just about any modern machine has more than sufficient RAM for this), but this behaviour can be overridden with the memcache parameter.
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_geo_filename (str) – The filename of the IPv4 geographic database (optional)
- v4_isp_filename (str) – The filename of the IPv4 ISP database (optional)
- v4_org_filename (str) – The filename of the IPv4 organisation database (optional)
- v6_geo_filename (str) – The filename of the IPv6 geographic database (optional)
- v6_isp_filename (str) – The filename of the IPv6 ISP database (optional)
- v6_org_filename (str) – The filename of the IPv6 organisation 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)[source]¶ Returns the country code associated with the specified address, or None if the address is not found in the GeoIP geographical database. You should use the
country
orcountry
attributes instead of this function.If the geographical database for the address type has not been initialized, the function raises a ValueError.
Parameters: address – The address to lookup the country for Returns str: The country code associated with the address
-
lars.geoip.
city_by_addr
(address)[source]¶ Returns the city associated with the address. You should use the
city
orcity
attributes 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.
If the geographical database for the address type has not been initialized, the function raises a ValueError.
Parameters: address – The address to lookup the city for Returns str: The city associated with the address, or None
-
lars.geoip.
region_by_addr
(address)[source]¶ Returns the region (e.g. state) associated with the address. You should use the
region
orregion
attributes 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.
If the geographical database for the address type has not been initialized, the function raises a ValueError.
Parameters: address – The address to lookup the region for Returns str: The region associated with the address, or None
-
lars.geoip.
coords_by_addr
(address)[source]¶ Returns the coordinates (long, lat) associated with the address. You should use the
coords
orcoords
attributes 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.
If the geographical database for the address type has not been initialized, the function raises a ValueError.
Parameters: address – The address to locate Returns str: The coordinates associated with the address, or None
-
lars.geoip.
isp_by_addr
(address)[source]¶ Returns the ISP that services the address. You should use the
isp
orisp
attributes instead of this function.If the ISP database for the address type has not been initialized, the function raises a ValueError.
Parameters: address – The address to lookup the ISP for Returns str: The ISP associated with the address, or None
-
lars.geoip.
org_by_addr
(address)[source]¶ Returns the organisation that owns the address, or the ISP that services the address (in the case that the organisation has opted not to reveal its address). If the organisational database for the address type has not been initialized, the function raises a ValueError.