WhoisFreaks Python SDK: WHOIS API Client for Python

The official Python client for the WhoisFreaks WHOIS API. Look up live WHOIS records for any domain across 1,529+ TLDs, pull WHOIS history back to 1986, search registrants with reverse WHOIS and run bulk WHOIS lookups from Python code.

The same package covers the DNS lookup API, domain availability API, typosquatting API, SSL certificate API, IP geolocation and IP reputation.

A live WHOIS lookup returns structured JSON like this (trimmed):

{
  "status": true,
  "domain_name": "whoisfreaks.com",
  "domain_registered": "yes",
  "create_date": "2019-03-19",
  "update_date": "2026-02-17",
  "expiry_date": "2027-03-19",
  "domain_registrar": {
    "iana_id": "1068",
    "registrar_name": "NAMECHEAP INC",
    "normalized_name": "namecheap, inc.",
    "website_url": "http://www.namecheap.com"
  },
  "registrant_contact": {
    "city": "Lewes",
    "state": "Delaware",
    "zip_code": "19958",
    "country_name": "United States",
    "country_code": "US"
  },
  "name_servers": ["albert.ns.cloudflare.com", "sue.ns.cloudflare.com"],
  "domain_status": ["clienttransferprohibited"]
}

Installation

pip install whoisfreaks

Get an API key

Create a free account at billing.whoisfreaks.com/signup. New accounts get 500 free credits with no credit card, usable across the live WHOIS, WHOIS history and reverse WHOIS APIs.

Keep the key out of source control. The examples read it from an environment variable:

export WHOISFREAKS_API_KEY="your_api_key"

Every example below assumes this setup:

import os
import whoisfreaks

config = whoisfreaks.Configuration()
config.api_key["ApiKeyAuth"] = os.environ["WHOISFREAKS_API_KEY"]

WHOIS lookup

Each request queries WHOIS servers and RDAP live, so you get the current record rather than a cached copy. One lookup costs 1 credit.

with whoisfreaks.ApiClient(config) as client:
    record = whoisfreaks.WHOISApi(client).whois_live("whoisfreaks.com")

    print(record.create_date, record.expiry_date)  # 2019-03-19 2027-03-19
    print(record.domain_registrar.registrar_name)  # NAMECHEAP INC
    print(record.name_servers)

Normalized registrar, address and date fields

Registries and registrars write the same facts in different formats. The API returns normalized fields so records from different TLDs line up without your own parsing code.

What you get	Field	Example
One registrar name, however the registry spells it	`domain_registrar.normalized_name`	`namecheap, inc.` for both "NAMECHEAP INC" and "NameCheap, Inc"
A parsed and geocoded contact address	`registrant_contact.street`, `city`, `state`, `zip_code`, `country_name`, `country_code`	`Lewes`, `Delaware`, `19958`, `United States`, `US`
One date format	`create_date`, `update_date`, `expiry_date`	`2019-03-19`

registrant = record.registrant_contact

print(record.domain_registrar.normalized_name)  # namecheap, inc.
print(registrant.city, registrant.state)        # Lewes Delaware
print(registrant.country_code)                  # US

Use these fields to group a domain portfolio by registrar, filter registrants by country code or sort domains by expiry date across every TLD.

Bulk WHOIS lookup

Look up to 100 domains in one call.

with whoisfreaks.ApiClient(config) as client:
    request = whoisfreaks.BulkWhoisRequest(domain_names=["example.com", "whoisfreaks.com", "github.com"])
    result = whoisfreaks.WHOISApi(client).bulk_whois(request)

For larger jobs, the Bulk WHOIS API accepts file uploads of up to 3M domains.

WHOIS history

Get every recorded ownership change for a domain in one request. A new record is stored only when the WHOIS data changed, and history goes back to 1986.

with whoisfreaks.ApiClient(config) as client:
    history = whoisfreaks.WHOISApi(client).whois_history("whoisfreaks.com")

Reverse WHOIS

Find every domain registered with a keyword, such as a company name or registrant email, across 4.5B+ WHOIS records.

with whoisfreaks.ApiClient(config) as client:
    matches = whoisfreaks.WHOISApi(client).whois_reverse("whoisfreaks", page=1)

DNS lookup

Pull live DNS records for a domain. Pass all or a comma-separated list of record types: A, AAAA, MX, NS, TXT, SOA, SPF, CNAME.

with whoisfreaks.ApiClient(config) as client:
    records = whoisfreaks.DNSApi(client).dns_live("A,MX,TXT", domain_name="whoisfreaks.com")

The same class also covers bulk DNS, historical DNS and reverse DNS lookups.

Domain availability check

Check whether a domain is registered and, with suggestions turned on, get up to 100 available alternatives on other TLDs.

with whoisfreaks.ApiClient(config) as client:
    result = whoisfreaks.DomainAvailabilityApi(client).domain_availability_v2(
        "whoisfreaks.io", sug=True, count=5
    )

Typosquatting detection

Find registered domains that look like typo variants of a brand name. Search by a brand keyword, or by a wildcard pattern such as whois* (up to 3 asterisks). Results come 100 domains per page with registration date, expiry date and drop status, across 1,529+ TLDs.

with whoisfreaks.ApiClient(config) as client:
    typos = whoisfreaks.TyposquattingApi(client).typosquatting(keyword="whoisfreaks")

To get the next page, pass the nextPageToken value from the response as page_token, along with the same keyword or pattern.

Error handling

Failed requests raise ApiException with the HTTP status code and response body.

from whoisfreaks.rest import ApiException

with whoisfreaks.ApiClient(config) as client:
    try:
        record = whoisfreaks.WHOISApi(client).whois_live("whoisfreaks.com")
    except ApiException as e:
        print(e.status, e.body)

Live API uptime and incident history are on the status page.

All endpoints

All URIs are relative to https://api.whoisfreaks.com. Each method links to its parameters and response model.

WHOIS

Class	Method	HTTP request	Description
WHOISApi	bulk_whois	POST /v2.0/bulkwhois/live	Bulk WHOIS Lookup
WHOISApi	whois_history	GET /v2.0/whois/history	Historical WHOIS records for a domain
WHOISApi	whois_live	GET /v2.0/whois/live	Live WHOIS Lookup
WHOISApi	whois_reverse	GET /v2.0/whois/reverse	Reverse WHOIS lookup by keyword
ASNWHOISApi	asn_whois	GET /v2.0/asn-whois	ASN WHOIS Lookup
IPWHOISApi	ip_whois	GET /v1.0/ip-whois	IP WHOIS Lookup

DNS, SSL and subdomains

Class	Method	HTTP request	Description
DNSApi	dns_bulk	POST /v2.0/dns/bulk/live	Bulk DNS Lookup
DNSApi	dns_historical	GET /v2.0/dns/historical	Historical DNS Lookup
DNSApi	dns_live	GET /v2.0/dns/live	Live DNS Lookup
DNSApi	dns_reverse	GET /v2.1/dns/reverse	Reverse DNS Lookup
SSLApi	ssl_lookup	GET /v1.0/ssl/live	SSL Certificate Lookup
SubdomainsApi	subdomains	GET /v1.0/subdomains	Subdomains Lookup

Domain availability, typosquatting and reputation

Class	Method	HTTP request	Description
DomainAvailabilityApi	bulk_domain_availability_v2	POST /v2.0/domain/availability	Bulk Domain Availability Check
DomainAvailabilityApi	domain_availability_v2	GET /v2.0/domain/availability	Domain Availability Check with Suggestions
TyposquattingApi	typosquatting	GET /v3.0/domain/typos	Typosquatting Lookup
DomainReputationApi	domain_reputation	GET /v1/domain/security	Domain Reputation Lookup

IP geolocation and reputation

Class	Method	HTTP request	Description
GeolocationApi	bulk_geolocation	POST /v1.0/geolocation	Bulk IP Geolocation
GeolocationApi	geolocation	GET /v1.0/geolocation	IP Geolocation Lookup
IPReputationApi	bulk_ip_reputation	POST /v1.0/security	Bulk IP Reputation
IPReputationApi	ip_reputation	GET /v1.0/security	IP Reputation Lookup

Account

Class	Method	HTTP request	Description
AccountApi	account_usage	GET /v1.0/whoisapi/usage	Account Usage
AccountApi	database_file_status	GET /v3.4/status	Database File Status (Public)
AccountApi	rotate_api_key	GET /v1.0/api-key/rotate	Rotate API Key

Database downloads

WHOIS, DNS, subdomain, IP, newly registered, expiring and dropped domain databases, plus the phishing, malware and spam threat feeds, are available through the Databases* classes. See the full method list for every download and status endpoint.

Requirements

Python 3.8 or later.

Support

WHOIS API documentation: whoisfreaks.com/documentation/whois-api
All API documentation: whoisfreaks.com/documentation
Product page: WhoisFreaks WHOIS API
API status: status.whois.whoisfreaks.com
Email: support@whoisfreaks.com
Quick start: WHOIS API examples
Other languages: Python, JavaScript, TypeScript, Java, Go, C#, Ruby, PHP, Swift, Kotlin

License

MIT. See LICENSE.

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
.openapi-generator		.openapi-generator
docs		docs
test		test
whoisfreaks		whoisfreaks
.gitignore		.gitignore
.gitlab-ci.yml		.gitlab-ci.yml
.openapi-generator-ignore		.openapi-generator-ignore
.travis.yml		.travis.yml
LICENSE		LICENSE
README.md		README.md
git_push.sh		git_push.sh
pyproject.toml		pyproject.toml
requirements.txt		requirements.txt
setup.cfg		setup.cfg
setup.py		setup.py
test-requirements.txt		test-requirements.txt
tox.ini		tox.ini

Navigation Menu

Repository navigation

About

Repository files navigation

WhoisFreaks Python SDK: WHOIS API Client for Python

Contents

Installation

Get an API key

WHOIS lookup

Normalized registrar, address and date fields

Bulk WHOIS lookup

WHOIS history

Reverse WHOIS

DNS lookup

Domain availability check

Typosquatting detection

Error handling

All endpoints

WHOIS

DNS, SSL and subdomains

Domain availability, typosquatting and reputation

IP geolocation and reputation

Account

Database downloads

Requirements

Support

License

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

WhoisFreaks Python SDK: WHOIS API Client for Python

Contents

Installation

Get an API key

WHOIS lookup

Normalized registrar, address and date fields

Bulk WHOIS lookup

WHOIS history

Reverse WHOIS

DNS lookup

Domain availability check

Typosquatting detection

Error handling

All endpoints

WHOIS

DNS, SSL and subdomains

Domain availability, typosquatting and reputation

IP geolocation and reputation

Account

Database downloads

Requirements

Support

License

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages