score.geoip

This module handles requests to a backend that is intended to get location metadata for a given IP address. A backend is a configurable implementation providing a lookup functionality returning metadata as a dictionary.

Quickstart

>>> from pprint import pprint
>>> pprint(score.geoip['8.8.8.8'])
{'as': 'AS15169 Google Inc.',
 'city': 'Mountain View',
 'country': 'United States',
 'countryCode': 'US',
 'isp': 'Google',
 'lat': 37.386,
 'lon': -122.0838,
 'org': 'Google',
 'query': '8.8.8.8',
 'region': 'CA',
 'regionName': 'California',
 'status': 'success',
 'timezone': 'America/Los_Angeles',
 'zip': '94035'}

Configuration

score.geoip.init(confdict, kvcache=None)

Initializes this module acoording to our module initialization guidelines with the following configuration keys:

backend score.geoip.backend.IpApi()

The backend object configuration that will be passed to score.init.parse_object(). Will use the ip-api backend by default, which is free for non-commercial projects.

Details

Command-Line Interface

Upon installation, this module registers a score.cli command that can be used to lookup IP addresses. As a precondition the module configuration needs to be satisfied as described in the score.cli configuration management.

$ score geoip lookup 8.8.8.8
$ score geoip lookup --format json 8.8.8.8
{
    "metro_code": "807",
    "country_code_iso3166numeric": "840",
    "longitude": -122.0838,
    "isp": "Google",
    "country_code_iso3166alpha3": "USA",
    "postal_code": "94040",
    "continent_name": "North America",
    "area_code": "650",
    "organization": "Google",
    "country_name": "United States",
    "latitude": 37.386,
    "continent_code": "NA",
    "region_name": "California",
    "country_code_iso3166alpha2": "US",
    "region_code": "CA",
    "city": "Mountain View",
    "country_code_fips10-4": "US"
}

$ score geoip lookup -f xml montypython.com
<?xml version="1.0" ?>
<location>
    <country_name>United States</country_name>
    <continent_code>NA</continent_code>
    <metro_code>807</metro_code>
    <region_name>California</region_name>
    <postal_code>94107</postal_code>
    <country_code_iso3166alpha3>USA</country_code_iso3166alpha3>
    <country_code_iso3166numeric>840</country_code_iso3166numeric>
    <isp>CloudFlare</isp>
    <city>San Francisco</city>
    <continent_name>North America</continent_name>
    <country_code_fips10-4>US</country_code_fips10-4>
    <longitude>-122.3933</longitude>
    <region_code>CA</region_code>
    <latitude>37.7697</latitude>
    <area_code>415</area_code>
    <organization>CloudFlare</organization>
    <country_code_iso3166alpha2>US</country_code_iso3166alpha2>
</location>

Caching

This module supports optional caching with score.kvcache. It registers a cache container named score.geoip, that needs to be configured as described in the score.kvcache configuration.

API

score.geoip.init(confdict, kvcache=None)

Initializes this module acoording to our module initialization guidelines with the following configuration keys:

backend score.geoip.backend.IpApi()

The backend object configuration that will be passed to score.init.parse_object(). Will use the ip-api backend by default, which is free for non-commercial projects.

class score.geoip.ConfiguredGeoipModule(backend, cache_container=None)

This module’s configuration object.

backend

The configured backend.

class score.geoip.IPNotFound(ip, cause=None)

Thrown if IP lookup failed.

class score.geoip.backend.Backend

__getitem__(ip)

Retrieves location metadata for given IP address and returns backend dependent metadata (usually latitude, longitude and location specific ISO data) as a dictionary.

Ready-to-use Backends

class score.geoip.backend.Dummy

This backend implementation provides a hardcoded mapping of some IP addresses for test purposes. Do not use in production.

class score.geoip.backend.IpApi

A free IP geolocalization service, provide by http://ip-api.com.

class score.geoip.backend.ApiGurus(uri, key, timeout)

This backend implementation connects to the API of apigurus.com. It retrieves a very detailed set of metadata dependent on the paid licence. For detailed information about metadata and licencing visit http://apigurus.com/.

uri

The URI of the desired apigurus.com API.

key

The key provided by the vendor for the client.

timeout

The connect timeout while connecting to the API.