msticpy.context.geoip module

Geoip Lookup module using IPStack and Maxmind GeoLite2.

Geographic location lookup for IP addresses. This module has two classes for different services:

GeoLiteLookup - Maxmind Geolite (see https://www.maxmind.com)
IPStackLookup - IPStack (see https://ipstack.com)

Both services offer a free tier for non-commercial use. However, a paid tier will normally get you more accuracy, more detail and a higher throughput rate. Maxmind geolite uses a downloadable database, while IPStack is an online lookup (API key required).

exception msticpy.context.geoip.GeoIPDatabaseError

Bases: Exception

Exception when GeoIP database cannot be found.

args

with_traceback(): Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

class msticpy.context.geoip.GeoIpLookup

Bases: object

Abstract base class for GeoIP Lookup classes.

See also

GeoIpLookup: Abstract base class
GeoLiteLookup: MaxMind GeoIP Implementation

Create a new instance of IPStackLookup.

Parameters:

api_key (str, optional) – API Key from IPStack - see https://ipstack.com default is None - obtain key from msticpyconfig.yaml
bulk_lookup (bool, optional) – For Professional and above tiers allowing you to submit multiple IPs in a single request. (the default is False, which submits a single request per address)

df_lookup_ip(data: DataFrame, column: str) → DataFrame

Lookup Geolocation data from a pandas Dataframe.

Parameters:

data (pd.DataFrame) – pandas dataframe containing IpAddress column
column (str) – the name of the dataframe column to use as a source

Returns:

Copy of original dataframe with IP Location information columns appended (where a location lookup was successful)

Return type:

pd.DataFrame

lookup_ip(ip_address: str | None = None, ip_addr_list: Iterable | None = None, ip_entity: IpAddress = None) → tuple[list[Any], list[IpAddress]]

Lookup IP location from IPStack web service.

Parameters:

ip_address (str, optional) – a single address to look up (the default is None)
ip_addr_list (Iterable, optional) – a collection of addresses to lookup (the default is None)
ip_entity (IpAddress, optional) – an IpAddress entity (the default is None) - any existing data in the Location property will be overwritten

Returns:

raw geolocation results and same results as IpAddress entities with populated Location property.

Return type:

tuple[list[Any], list[IpAddress]]

Raises:

ConnectionError – Invalid status returned from http request
PermissionError – Service refused request (e.g. requesting batch of addresses on free tier API key)

lookup_ips(data: DataFrame, column: str) → DataFrame

Lookup Geolocation data from a pandas Dataframe.

Parameters:

data (pd.DataFrame) – pandas dataframe containing IpAddress column
column (str) – the name of the dataframe column to use as a source

Returns:

IpLookup results as DataFrame.

Return type:

pd.DataFrame

print_license() → None: Print license information for providers.

msticpy.context.geoip.entity_distance(ip_src: IpAddress, ip_dest: IpAddress) → float

Return distance between two IP Entities.

Parameters:

ip_src (IpAddress) – Source/Origin IpAddress Entity
ip_dest (IpAddress) – Destination IpAddress Entity

Returns:

Distance in kilometers.

Return type:

float

Raises:

AttributeError – If either entity has no location information

msticpy.context.geoip.geo_distance(origin: tuple[float, float], destination: tuple[float, float]) → float

Calculate the Haversine distance.

Parameters:

origin (tuple[float, float]) – Latitude, Longitude of origin of distance measurement.
destination (tuple[float, float]) – Latitude, Longitude of origin of distance measurement.

Returns:

Distance in kilometers.

Return type:

float

Examples

>>> origin = (48.1372, 11.5756)  # Munich
>>> destination = (52.5186, 13.4083)  # Berlin
>>> round(geo_distance(origin, destination), 1)
504.2

Notes

Author: Martin Thoma - stackoverflow