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_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 and IPv6Address 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 or country 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 or city 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 or region 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 or coords 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 or isp 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