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

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
• Requirements
• Support

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.

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

DNS, SSL and subdomains

Domain availability, typosquatting and reputation

IP geolocation and reputation

Account

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
• Other languages: Python, JavaScript, TypeScript, Java, Go, C#, Ruby, PHP, Swift, Kotlin

License

MIT. See LICENSE.