Legacy Whois Lookups¶

IPWhois.lookup() is deprecated as of v0.12.0 and will be removed. Legacy whois lookups were moved to IPWhois.lookup_whois().

Parsing is currently limited to the keys in the output Results Dictionary. This is assuming that those fields are present (for both whois and rwhois).

Some IPs have parent networks listed. The parser attempts to recognize this, and break the networks into individual dictionaries. If a single network has multiple CIDRs, they will be separated by ‘, ‘.

Sometimes, you will see whois information with multiple consecutive same name fields, e.g., Description: some text\nDescription: more text. The parser will recognize this and the returned result will have the values separated by ‘\n’.

Input¶

Arguments supported by IPWhois.lookup_whois().

Key	Type	Description
inc_raw	bool	Whether to include the raw whois results in the returned dictionary. Defaults to False.
retry_count	int	The number of times to retry in case socket errors, timeouts, connection resets, etc. are encountered. Defaults to 3.
get_referral	bool	Whether to retrieve referral whois information, if available. Defaults to False.
extra_blacklist	list	Blacklisted whois servers in addition to the global BLACKLIST. Defaults to None.
ignore_referral_errors	bool	Whether to ignore and continue when an exception is encountered on referral whois lookups. Defaults to False.
field_list	list	If provided, a list of fields to parse: [‘name’, ‘handle’, ‘description’, ‘country’, ‘state’, ‘city’, ‘address’, ‘postal_code’, ‘emails’, ‘created’, ‘updated’]. If None, defaults to all.
extra_org_map	dict	Dictionary mapping org handles to RIRs. This is for limited cases where ARIN REST (ASN fallback HTTP lookup) does not show an RIR as the org handle e.g., DNIC (which is now built in ORG_MAP) e.g., {‘DNIC’: ‘arin’} Valid RIR values are (note the case-sensitive - this is meant to match the REST result): ‘ARIN’, ‘RIPE’, ‘apnic’, ‘lacnic’, ‘afrinic’ Defaults to None.
inc_nir	bool	Whether to retrieve NIR (National Internet Registry) information, if registry is JPNIC (Japan) or KRNIC (Korea). If True, extra network requests will be required. If False, the information returned for JP or KR IPs is severely restricted. Defaults to True.
nir_field_list	list	If provided and inc_nir, a list of fields to parse: [‘name’, ‘handle’, ‘country’, ‘address’, ‘postal_code’, ‘nameservers’, ‘created’, ‘updated’, ‘contacts’] If None, defaults to all.
asn_methods	list	ASN lookup types to attempt, in order. If None, defaults to all [‘dns’, ‘whois’, ‘http’].
get_asn_description	bool	Whether to run an additional query when pulling ASN information via dns, in order to get the ASN description. Defaults to True.

Output¶

Results Dictionary¶

The output dictionary from IPWhois.lookup_whois().

Key	Type	Description
query	str	The IP address input
asn	str	Globally unique identifier used for routing information exchange with Autonomous Systems.
asn_cidr	str	Network routing block assigned to an ASN.
asn_country_code	str	ASN assigned country code in ISO 3166-1 format.
asn_date	str	ASN allocation date in ISO 8601 format.
asn_registry	str	ASN assigned regional internet registry.
asn_description	str	The ASN description
nets	list	List of network dictionaries. See Network Dictionary.
raw	str	Raw whois results if inc_raw is True.
referral	dict	Referral whois information if get_referral is True and the server isn’t blacklisted. See Referral Dictionary.
raw_referral	str	Raw referral whois results if the inc_raw parameter is True.
nir	dict	The National Internet Registry results if inc_nir is True. See NIR result

Network Dictionary¶

The dictionary mapped to the nets key in the Results Dictionary.

Key	Type	Description
cidr	str	Network routing block an IP address belongs to.
range	str	Network range an IP address belongs to.
name	str	The identifier assigned to the network registration for an IP address.
handle	str	Unique identifier for a registered network.
description	str	Description for a registered network.
country	str	Country code registered with the RIR in ISO 3166-1 format.
state	str	State for a registered network (if applicable).
city	str	City for a registered network (if applicable).
address	str	The mailing address for a registered network.
postal_code	str	The postal code for a registered network.
emails	list	The email addresses listed for a registered network.
created	str	Network registration date in ISO 8601 format.
updated	str	Network registration updated date in ISO 8601 format.

Referral Dictionary¶

The dictionary mapped to the referral key in the Results Dictionary.

Key	Type	Description
cidr	str	Network routing block an IP address belongs to.
range	str	Network range an IP address belongs to.
name	str	The identifier assigned to the network registration for an IP address.
description	str	Description for a registered network.
country	str	Country code registered in ISO 3166-1 format.
state	str	State for a registered network (if applicable).
city	str	City for a registered network (if applicable).
address	str	The mailing address for a registered network.
postal_code	str	The postal code for a registered network.
emails	list	The email addresses listed for a registered network.
created	str	Network registration date in ISO 8601 format.
updated	str	Network registration updated date in ISO 8601 format.

Usage Examples¶

Basic usage¶

>>>> from ipwhois import IPWhois
>>>> from pprint import pprint

>>>> obj = IPWhois('74.125.225.229')
>>>> results = obj.lookup_whois()
>>>> pprint(results)

{
"asn": "15169",
"asn_cidr": "74.125.225.0/24",
"asn_country_code": "US",
"asn_date": "2007-03-13",
"asn_description": "GOOGLE - Google Inc., US",
"asn_registry": "arin",
"nets": [
    {
        "address": "1600 Amphitheatre Parkway",
        "cidr": "74.125.0.0/16",
        "city": "Mountain View",
        "country": "US",
        "created": "2007-03-13",
        "description": "Google Inc.",
        "emails": [
            "network-abuse@google.com",
            "arin-contact@google.com"
        ],
        "handle": "NET-74-125-0-0-1",
        "name": "GOOGLE",
        "postal_code": "94043",
        "range": "74.125.0.0 - 74.125.255.255",
        "state": "CA",
        "updated": "2012-02-24"
    }
],
"nir": None,
"query": "74.125.225.229",
"raw": None,
"raw_referral": None,
"referral": None
}

Multiple networks listed and referral whois¶

>>>> from ipwhois import IPWhois
>>>> from pprint import pprint

>>>> obj = IPWhois('38.113.198.252')
>>>> results = obj.lookup_whois(get_referral=True)
>>>> pprint(results)

{
"asn": "174",
"asn_cidr": "38.0.0.0/8",
"asn_country_code": "US",
"asn_date": "",
"asn_description": "COGENT-174 - Cogent Communications, US",
"asn_registry": "arin",
"nets": [
    {
        "address": "2450 N Street NW",
        "cidr": "38.0.0.0/8",
        "city": "Washington",
        "country": "US",
        "created": "1991-04-16",
        "description": "PSINet, Inc.",
        "emails": [
            "ipalloc@cogentco.com",
            "abuse@cogentco.com",
            "noc@cogentco.com"
        ],
        "handle": "NET-38-0-0-0-1",
        "name": "COGENT-A",
        "postal_code": "20037",
        "range": "38.0.0.0 - 38.255.255.255",
        "state": "DC",
        "updated": "2011-05-20"
    },
    {
        "address": "2450 N Street NW",
        "cidr": "38.112.0.0/13",
        "city": "Washington",
        "country": "US",
        "created": "2003-08-20",
        "description": "PSINet, Inc.",
        "emails": [
            "ipalloc@cogentco.com",
            "abuse@cogentco.com",
            "noc@cogentco.com"
        ],
        "handle": "NET-38-112-0-0-1",
        "name": "COGENT-NB-0002",
        "postal_code": "20037",
        "range": None,
        "state": "DC",
        "updated": "2004-03-11"
    }
],
"nir": None,
"query": "38.113.198.252",
"raw": None,
"raw_referral": None,
"referral": {
    "address": "2450 N Street NW",
    "city": "Washington",
    "country": "US",
    "description": "Cogent communications - IPENG",
    "name": "NET4-2671C60017",
    "postal_code": "20037",
    "state": "DC",
    "updated": "2007-09-18 22:02:09"
}
}