pywhoisxmlapi documentation¶

An unofficial client for WhoisXMLAPI

Features¶

Python 2 and 3 support
whois.py CLI utility for common queries with JSON and CSV output
Pythonic access to every WhoisXMLAPI service

CLI help¶

whois.py - A CLI for WhoisXMLAPI

Usage:
  whois.py balances
  whois.py [-d | --debug] [--verbose] <domain> [-o | --output=<output_file>]
  whois.py bulk [-d | --debug] <input_file> [--csv] [ -o | --output=<output_file>]
  whois.py reverse [-d | --debug] [-p | --purchase] [--historic] <term>... [--exclude <exclude_term>... --since=<since> --days-back=<days_back> [-o | --output=<output_file>]]
  whois.py history [-d | --debug] [-p | --purchase] <domain> [--since=<since>  [-o | --output=<output_file>]]
  whois.py brand [-d | --debug] [-p | --purchase] <term>... [--exclude <exclude_term>... --since=<since> [--csv]  [-o | --output=<output_file>]]
  whois.py registrant [-d | --debug] [-p | --purchase] <term>... [--exclude <exclude_term>... --since=<since> [--csv] [-o |--output=<output_file>]]
  whois.py reverse-ip [-d | --debug] [--verbose] <ip> [--csv] [-o | --output=<output_file>]
  whois.py reverse-mx [-d | --debug] [--verbose] <mx> [--csv] [-o | --output=<output_file>]
  whois.py reverse-ns [-d | --debug] [--verbose] <ns> [--csv] [-o | --output=<output_file>]
  whois.py -h | --help
  whois.py --version

Options:
  -h --help                    Show this screen
  -d --debug                   Enable debug output
  <input_file>                 A path to a file containing one domain per line
  -o --output=<output_file>    Output to a file with this file name; the file extension is added automatically
  -p --purchase                Purchase the results with Domain Research Suite (DRS) credits
  --since=<since>              Only include results since this date YYY-MM-DD format
  --days-back=<days_back>      Search back through this number of days (12 maximum)
  --historic                   Include historic results
  --csv                        Output in CSV format
  --verbose                    Return verbose data
  --version                    Show version

Note

The whois.py CLI utility expects the API key to be stored in an environment variable called WHOIS_KEY.

Installation¶

On Debian or Ubuntu systems, run:

sudo apt-get install python3-pip

On CentOS systems, run:

sudo yum install -y python34-setuptools
sudo easy_install-3.4 pip

Python 3 installers for Windows and macOS can be found at https://www.python.org/downloads/

To install or upgrade to the latest stable release of pywhoisxmlapi on macOS or Linux, run

sudo -H pip3 install -U pywhoisxmlapi

Or, install the latest development release directly from GitHub:

sudo -H pip3 install -U git+https://github.com/seanthegeek/pywhoisxmlapi.git

Note

On Windows, pip3 is pip, even with Python 3. So on Windows, substitute pip as an administrator in place of sudo pip3, in the above commands.

API¶

An unofficial client for WhoisXMLAPI

class pywhoisxmlapi.WhoisXMLAPI(api_key=None)[source]¶

A Python interface to WhoisXMLAPI

Note

api_key can be overridden by the WHOIS_KEY environment variable

brand_alert(terms, exclude_terms=None, since_date=None, created_date_from=None, created_date_to=None, updated_date_from=None, updated_date_to=None, expired_date_from=None, expired_date_to=None, mode='preview')[source]¶

Lists newly created or deleted domains based on brand terms

Parameters

terms (list) – Brand terms to include in the search (max 4)
exclude_terms (list) – Terms to exclude (max 4)
since_date (str) – Only return domains created or deleted since this date, (YYYY-MM-DD format)
created_date_to (str) – Search through domains created before the given date (YYYY-MM-DD format)
created_date_from (str) – Search through domains created after the given date (YYYY-MM-DD format)
updated_date_to (str) – Search through domains created before the given date (YYYY-MM-DD format)
updated_date_from (str) – Search through domains created after the given date (YYYY-MM-DD format)
expired_date_to (str) – Search through domains created before the given date (YYYY-MM-DD format)
expired_date_from (str) – Search through domains created after the given date (YYYY-MM-DD format)
mode (str) – preview or purchase

Returns

A dictionary of preview data list: A list of dictionaries containing the domainName, and its action (i.e. added or dropped)

Return type

dict

bulk_whois(domains)[source]¶

Retrieves WHOIS data for multiple domains, in bulk.

Parameters

domains (list) – A list of domains to get WHOIS records for

Returns

A dictionary with keys:

structured - parsed data in a dictionary
csv: results in CSV format

Return type

dict

dns_lookup(domain_name, record_type='_all', callback=None)[source]¶

Preforms a DNS lookup

Parameters

domain_name (str) – The domain name or sub-domain to lookup
record_type (str) – The DNS resource record type to query for, or _all for all record types
callback (str) – A JSONP callback

Returns

Lookup results str: lookup results data wrapped in JSONP if callback was specified

Return type

dict

domain_availability(domain_name, mode='DNS_ONLY')[source]¶

Check domain name availability

Parameters

domain_name (str) – The domain name to check
mode (str) – DNS_ONLY or DNS_AND_WHOIS

Returns

The availability of the domain name

Return type

bool

domain_reputation(domain, mode='fast')[source]¶

Checks a domain’s reputation

Parameters

domain (str) – The domain to check
mode (str) – fast - some heavy tests and data collectors will be disabled (1 credit) or full - all the data and the tests will be processed (3 credits)

Returns

A number ranging from 0.0 being most malicious to 100.0 being most safe

Return type

float

get_account_balances()[source]¶

Get all account balances

Returns: Account balances
Return type: Dict

ip_geolocation(ip)[source]¶

Returns geolocation information about an IP address

Parameters: ip (str) – An IPv4 or IPv6 address
Returns: Geolocation information
Return type: dict

netblocks(ip=None, mask=None, org=None, limit=10000)[source]¶

Returns netblock information about a given IP or organisation

Note

You must specify ip or org, but not both

Parameters

ip (str) – An IP address
mask (int) – A subnet bask integer
org (list) – A list os organisation strings
limit (int) – Max number of records to return (1-10000)

Returns

A list of netblocks

Return type

list

registrant_alert(terms, exclude_terms=None, since_date=None, created_date_from=None, created_date_to=None, updated_date_from=None, updated_date_to=None, expired_date_from=None, expired_date_to=None, mode='preview')[source]¶

Lists newly created or deleted domains based on registrant

Parameters

terms (list) – Brand terms to include in the search (max 4)
exclude_terms (list) – Terms to exclude (max 4)
since_date (str) – Only return domains created or deleted since this date, (YYYY-MM-DD format)
created_date_to (str) – Search through domains created before the given date (YYYY-MM-DD format)
created_date_from (str) – Search through domains created after the given date (YYYY-MM-DD format)
updated_date_to (str) – Search through domains created before the given date (YYYY-MM-DD format)
updated_date_from (str) – Search through domains created after the given date (YYYY-MM-DD format)
expired_date_to (str) – Search through domains created before the given date (YYYY-MM-DD format)
expired_date_from (str) – Search through domains created after the given date (YYYY-MM-DD format)
mode (str) – preview or purchase

Returns

A dictionary of preview data list: A list of dictionaries containing the domainName, and its action (i.e. added or dropped)

Return type

dict

reverse_ip(ip)[source]¶

Performs a reverse IP/DNS query

Parameters: ip (str) – An IPv4 or IPv6 address
Returns: A list of results
Return type: list

reverse_mx(mx)[source]¶

Performs a reverse MX query

Parameters: mx (str) – A MX hostname
Returns: A list of results
Return type: list

reverse_ns(ns)[source]¶

Performs a reverse MX query

Parameters: ns (str) – A nameserver hostname
Returns: A list of results
Return type: list

reverse_whois(terms, exclude_terms=None, search_type='current', mode='preview', created_date_to=None, created_date_from=None, updated_date_to=None, updated_date_from=None, expired_date_to=None, expired_date_from=None)[source]¶

Conducts a reverse WHOIS search

Parameters

terms (list) – Terms to search for
exclude_terms (list) – Terms to filter by
search_type (str) – current or historic
mode (str) – preview or purchase
created_date_to (str) – Search through domains created before the given date (YYYY-MM-DD format)
created_date_from (str) – Search through domains created after the given date (YYYY-MM-DD format)
updated_date_to (str) – Search through domains created before the given date (YYYY-MM-DD format)
updated_date_from (str) – Search through domains created after the given date (YYYY-MM-DD format)
expired_date_to (str) – Search through domains created before the given date (YYYY-MM-DD format)
expired_date_from (str) – Search through domains created after the given date (YYYY-MM-DD format)

Returns

A dictionary of preview data list: A list of results

Return type

dict

set_account_balance_warnings(warn_threshold=10, warn_threshold_enabled=True, warn_empty_enabled=True)[source]¶

Sets account settings for balance warnings

Parameters

warn_threshold – The value at which account balance warnings are sent
warn_threshold_enabled (bool) – Enable low balance warnings
warn_empty_enabled (bool) – Enable empty balance warnings

Returns

Acknowledgement

Return type

dict

verify_email(email_address)[source]¶

Returns metadata about an email address

Parameters: email_address (str) – The email address to verify
Returns: email verification results
Return type: dict

whois(domain_name, prefer_fresh=False, da=0, ip=True, check_proxy_data=True, thin_whois=False, callback=None, parse=False, registry_raw_text=None, registrar_raw_text=None)[source]¶

Returns parsed WHOIS data

Parameters

domain_name (str) – A domain name or IP address
prefer_fresh (bool) – Get the latest WHOIS record even if it’s incomplete
da (int) – 0 - Do not check for domain amiability; 1 - quick check; 2 - slower, but most accurate
ip (bool) – Resolve IP addresses
check_proxy_data (bool) – Check if registration matches known proxies
thin_whois (bool) – Only return data on the registrant, not the registrar
callback (str) – JSONP callback
parse (bool) – Parse the provided raw WHOIS data
registry_raw_text (str) – Optional raw WHOIS registration data to parse, rather than fetching it via the API
registrar_raw_text (str) – Optional raw WHOIS registration data to parse, rather than fetching it via the API

Returns

Parsed WHOIS data str: WHOIS data wrapped in JSONP if callback was specified

Return type

dict

whois_history(domain, since_date=None, created_date_from=None, created_date_to=None, updated_date_from=None, updated_date_to=None, expired_date_from=None, expired_date_to=None, mode='preview')[source]¶

Returns WHOIS history for a given domains

Parameters

domain (str) – The domain
since_date (str) – Only return domains created or deleted since this date, (YYYY-MM-DD format)
created_date_to (str) – Search through domains created before the given date (YYYY-MM-DD format)
created_date_from (str) – Search through domains created after the given date (YYYY-MM-DD format)
updated_date_to (str) – Search through domains created before the given date (YYYY-MM-DD format)
updated_date_from (str) – Search through domains created after the given date (YYYY-MM-DD format)
expired_date_to (str) – Search through domains created before the given date (YYYY-MM-DD format)
expired_date_from (str) – Search through domains created after the given date (YYYY-MM-DD format)
mode (str) – preview or purchase

Returns

A dictionary of preview data list: A list of parsed historic WHOIS records, starting with the current record

Return type

dict

exception pywhoisxmlapi.WhoisXMLAPIError[source]¶: Raised when an error is returned by WhoisXMLAPI

pywhoisxmlapi.flatten_whois(whois_record)[source]¶

Flattens a whois record result :param whois_record: A WHOIS record :type whois_record: dict

Returns: A flattened WHOIS result
Return type: dict

pywhoisxmlapi.whois_to_csv(whois_results)[source]¶

Returns CSV content given a list of WHOIS results

Parameters: whois_results (list) – A list of WHOIS results
Returns: results as a CSV string
Return type: str

pywhoisxmlapi documentation¶

Features¶

CLI help¶

Installation¶

API¶

Indices and tables¶