tldfyi

Python API client for top-level domain (TLD) data. Look up TLD registry information, explore domain extension categories (gTLD, ccTLD, new gTLD), query WHOIS server details, and retrieve ICANN delegation records — all from TLDFYI, a TLD reference platform covering every active domain extension in the DNS root zone.

TLDFYI catalogs the complete IANA root zone database including TLD types, registry operators, WHOIS servers, DNSSEC status, IDN (internationalized domain name) support, and registration policies — used by domain registrars, DNS researchers, and cybersecurity analysts.

Explore TLDs at tldfyi.com — browse by type, search TLDs, and view registry details.

Table of Contents

• Install
• Quick Start
• What You Can Do
  • TLD Categories
  • Domain Lifecycle
  • WHOIS and Registration Data
  • ICANN and DNS Governance
• Command-Line Interface
• MCP Server (Claude, Cursor, Windsurf)
• REST API Client
• API Reference
• Learn More About TLDs
• Also Available
• Network FYI Family
• License

Install

pip install tldfyi                # Core (zero deps)
pip install "tldfyi[cli]"         # + Command-line interface
pip install "tldfyi[mcp]"         # + MCP server for AI assistants
pip install "tldfyi[api]"         # + HTTP client for tldfyi.com API
pip install "tldfyi[all]"         # Everything

Quick Start

from tldfyi.api import TLDFYI

with TLDFYI() as api:
    # Look up a TLD
    com = api.get_tld("com")
    print(com["type"])              # gTLD
    print(com["registry"])          # Verisign
    print(com["whois_server"])      # whois.verisign-grs.com
    print(com["dnssec"])            # True

    # List TLDs by type
    cctlds = api.list_tlds(type="ccTLD")
    for tld in cctlds[:5]:
        print(f".{tld['name']} — {tld['country']}")

    # Search TLDs
    results = api.search("tech")

What You Can Do

TLD Categories

The Domain Name System root zone contains over 1,500 TLDs organized into distinct categories. Each category has different governance rules, registration policies, and intended purposes.

Category	Count	Examples	Governance
gTLD (Generic)	22 original	.com, .net, .org, .info	ICANN contracted
ccTLD (Country-Code)	250+	.uk, .de, .jp, .kr, .br	National authorities
new gTLD	1,200+	.app, .dev, .io, .xyz	ICANN 2012 program
sTLD (Sponsored)	15	.edu, .gov, .mil, .museum	Sponsoring organizations
Infrastructure	1	.arpa	IANA (DNS infrastructure)
IDN ccTLD	60+	.xn-- (Punycode encoded)	National authorities

from tldfyi.api import TLDFYI

with TLDFYI() as api:
    # Browse TLDs by category
    types = api.list_types()
    for t in types:
        print(f"{t['name']}: {t['count']} TLDs")

    # Get all country-code TLDs
    cctlds = api.list_tlds(type="ccTLD")
    print(f"{len(cctlds)} country-code TLDs")

Learn more: TLD Types · Glossary

Domain Lifecycle

Every domain name follows a lifecycle from registration through expiration. Understanding these states is critical for domain management, drop-catching, and brand protection.

State	Duration	Description
Available	—	Not registered, can be purchased
Registered	1-10 years	Active, resolves in DNS
Expired	0-45 days	Grace period, can be renewed
Redemption	30 days	Higher fee to recover
Pending Delete	5 days	About to be released
Available (again)	—	Returns to open registration

from tldfyi.api import TLDFYI

with TLDFYI() as api:
    # Look up TLD registration policies
    tld = api.get_tld("com")
    print(f"Registry: {tld['registry']}")
    print(f"WHOIS: {tld['whois_server']}")
    print(f"Registration periods: {tld.get('registration_periods')}")

Learn more: Domain Lifecycle · Glossary

WHOIS and Registration Data

WHOIS is the protocol for querying domain registration databases. Each TLD designates a WHOIS server where registrant information (subject to GDPR/privacy policies), registration dates, name servers, and expiration dates can be queried.

from tldfyi.api import TLDFYI

with TLDFYI() as api:
    # Get WHOIS server information for a TLD
    tld = api.get_tld("org")
    print(f"WHOIS server: {tld['whois_server']}")
    print(f"Registry: {tld['registry']}")
    print(f"DNSSEC: {tld.get('dnssec')}")

Learn more: WHOIS Data · Guides

ICANN and DNS Governance

ICANN (Internet Corporation for Assigned Names and Numbers) coordinates the global DNS through the IANA (Internet Assigned Numbers Authority) function. The 2012 new gTLD program expanded the root zone from ~300 to 1,500+ TLDs, creating extensions like .app, .dev, and .blog.

Organization	Role	Manages
ICANN	DNS coordination	gTLD policies, new TLD applications
IANA	Root zone maintenance	TLD delegation, IP allocation
Verisign	.com/.net registry	Root zone file operations
Country NICs	ccTLD registry	National domain policies
RDAP	WHOIS successor	Structured registration data access

from tldfyi.api import TLDFYI

with TLDFYI() as api:
    # Get registry operator information
    tld = api.get_tld("dev")
    print(f"Registry: {tld['registry']}")         # Google Registry
    print(f"Type: {tld['type']}")                  # new gTLD
    print(f"DNSSEC required: {tld.get('dnssec')}")

Learn more: DNS Governance · API Documentation

Command-Line Interface

pip install "tldfyi[cli]"

tldfyi tld com                              # TLD details
tldfyi search "app"                         # Search TLDs
tldfyi type ccTLD                           # All country-code TLDs
tldfyi types                                # List TLD categories

MCP Server (Claude, Cursor, Windsurf)

pip install "tldfyi[mcp]"

{
    "mcpServers": {
        "tldfyi": {
            "command": "uvx",
            "args": ["--from", "tldfyi[mcp]", "python", "-m", "tldfyi.mcp_server"]
        }
    }
}

REST API Client

from tldfyi.api import TLDFYI

with TLDFYI() as api:
    tld = api.get_tld("com")                    # GET /api/v1/tlds/com/
    cctlds = api.list_tlds(type="ccTLD")         # GET /api/v1/tlds/?type=ccTLD
    types = api.list_types()                     # GET /api/v1/types/
    results = api.search("tech")                 # GET /api/v1/search/?q=tech

Example

curl -s "https://tldfyi.com/api/v1/tlds/com/"

{
    "slug": "com",
    "name": "com",
    "type": "gTLD",
    "registry": "Verisign",
    "whois_server": "whois.verisign-grs.com",
    "dnssec": true
}

Full API documentation at tldfyi.com/developers/.

API Reference

Function	Description
api.get_tld(slug)	TLD details (registry, WHOIS, DNSSEC)
api.list_tlds(type)	List TLDs, optionally by type
api.list_types()	All TLD categories with counts
api.get_type(slug)	Type details with TLD list
api.search(query)	Search TLDs by name or registry

Learn More About TLDs

• Browse: TLD Directory · TLD Types
• Guides: Domain Guides · Glossary
• API: REST API Docs · OpenAPI Spec

Also Available

Platform	Install	Link
npm	npm install tldfyi	npm
MCP	uvx --from "tldfyi[mcp]" python -m tldfyi.mcp_server	Config

Network FYI Family

Part of the FYIPedia open-source developer tools ecosystem — internet infrastructure, cables, domains, and protocols.

Package	PyPI	npm	Description
cablefyi	PyPI	npm	Submarine cables, landing points, operators — cablefyi.com
tldfyi	PyPI	npm	TLD registry, domain extensions, WHOIS — tldfyi.com
ipfyi	PyPI	npm	IP geolocation, ASN lookup, CIDR ranges — ipfyi.com
protocolcodes	PyPI	npm	HTTP status codes, protocol references — statuscodefyi.com

License

MIT