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:

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

IPStackLookup

IPStack GeoIP Implementation

GeoLiteLookup

MaxMind GeoIP Implementation

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

abstract lookup_ip(ip_address: str | None = None, ip_addr_list: Iterable | None = None, ip_entity: IpAddress | None = None) Tuple[List[Any], List[IpAddress]]

Lookup IP location abstract method.

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]]

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()

Print license information for providers.

class msticpy.context.geoip.IPStackLookup(api_key: str | None = None, bulk_lookup: bool = False)

Bases: GeoIpLookup

IPStack GeoIP Implementation.

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 = 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()

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