Metadata-Version: 2.4
Name: tldfyi
Version: 0.1.1
Summary: TLD registry and domain extensions API client — tldfyi.com
Project-URL: Homepage, https://tldfyi.com
Project-URL: Documentation, https://tldfyi.com/developers/
Project-URL: Repository, https://github.com/fyipedia/tldfyi
Project-URL: Issues, https://github.com/fyipedia/tldfyi/issues
Project-URL: Changelog, https://github.com/fyipedia/tldfyi/releases
Author: FYIPedia
License-Expression: MIT
License-File: LICENSE
Keywords: dns,domain,extension,icann,internet,registry,tld,whois
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Provides-Extra: all
Requires-Dist: httpx>=0.27; extra == 'all'
Requires-Dist: mcp>=1.0; extra == 'all'
Requires-Dist: rich>=13.0; extra == 'all'
Requires-Dist: typer>=0.15; extra == 'all'
Provides-Extra: api
Requires-Dist: httpx>=0.27; extra == 'api'
Provides-Extra: cli
Requires-Dist: rich>=13.0; extra == 'cli'
Requires-Dist: typer>=0.15; extra == 'cli'
Provides-Extra: mcp
Requires-Dist: mcp>=1.0; extra == 'mcp'
Description-Content-Type: text/markdown

# tldfyi

[![PyPI version](https://agentgif.com/badge/pypi/tldfyi/version.svg)](https://pypi.org/project/tldfyi/)
[![Python](https://img.shields.io/pypi/pyversions/tldfyi)](https://pypi.org/project/tldfyi/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
[![Zero Dependencies](https://img.shields.io/badge/dependencies-0-brightgreen)](https://pypi.org/project/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](https://tldfyi.com/), 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](https://tldfyi.com/)** — browse by [type](https://tldfyi.com/types/), search [TLDs](https://tldfyi.com/tlds/), and view registry details.

<p align="center">
  <img src="https://raw.githubusercontent.com/fyipedia/tldfyi/main/demo.gif" alt="tldfyi demo — TLD lookup, domain extension data, and WHOIS information in Python" width="800">
</p>

## Table of Contents

- [Install](#install)
- [Quick Start](#quick-start)
- [What You Can Do](#what-you-can-do)
  - [TLD Categories](#tld-categories)
  - [Domain Lifecycle](#domain-lifecycle)
  - [WHOIS and Registration Data](#whois-and-registration-data)
  - [ICANN and DNS Governance](#icann-and-dns-governance)
- [Command-Line Interface](#command-line-interface)
- [MCP Server (Claude, Cursor, Windsurf)](#mcp-server-claude-cursor-windsurf)
- [REST API Client](#rest-api-client)
- [API Reference](#api-reference)
- [Learn More About TLDs](#learn-more-about-tlds)
- [Also Available](#also-available)
- [Network FYI Family](#network-fyi-family)
- [License](#license)

## Install

```bash
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

```python
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 |

```python
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](https://tldfyi.com/types/) · [Glossary](https://tldfyi.com/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 |

```python
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](https://tldfyi.com/guides/) · [Glossary](https://tldfyi.com/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.

```python
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](https://tldfyi.com/tlds/) · [Guides](https://tldfyi.com/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 |

```python
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](https://tldfyi.com/guides/) · [API Documentation](https://tldfyi.com/developers/)

## Command-Line Interface

```bash
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)

```bash
pip install "tldfyi[mcp]"
```

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

## REST API Client

```python
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

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

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

Full API documentation at [tldfyi.com/developers/](https://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](https://tldfyi.com/tlds/) · [TLD Types](https://tldfyi.com/types/)
- **Guides**: [Domain Guides](https://tldfyi.com/guides/) · [Glossary](https://tldfyi.com/glossary/)
- **API**: [REST API Docs](https://tldfyi.com/developers/) · [OpenAPI Spec](https://tldfyi.com/api/openapi.json)

## Also Available

| Platform | Install | Link |
|----------|---------|------|
| **npm** | `npm install tldfyi` | [npm](https://www.npmjs.com/package/tldfyi) |
| **MCP** | `uvx --from "tldfyi[mcp]" python -m tldfyi.mcp_server` | [Config](#mcp-server-claude-cursor-windsurf) |

## Network FYI Family

Part of the [FYIPedia](https://fyipedia.com) open-source developer tools ecosystem — internet infrastructure, cables, domains, and protocols.

| Package | PyPI | npm | Description |
|---------|------|-----|-------------|
| cablefyi | [PyPI](https://pypi.org/project/cablefyi/) | [npm](https://www.npmjs.com/package/cablefyi) | Submarine cables, landing points, operators — [cablefyi.com](https://cablefyi.com/) |
| **tldfyi** | [PyPI](https://pypi.org/project/tldfyi/) | [npm](https://www.npmjs.com/package/tldfyi) | **TLD registry, domain extensions, WHOIS — [tldfyi.com](https://tldfyi.com/)** |
| ipfyi | [PyPI](https://pypi.org/project/ipfyi/) | [npm](https://www.npmjs.com/package/ipfyi) | IP geolocation, ASN lookup, CIDR ranges — [ipfyi.com](https://ipfyi.com/) |
| protocolcodes | [PyPI](https://pypi.org/project/protocolcodes/) | [npm](https://www.npmjs.com/package/protocolcodes) | HTTP status codes, protocol references — [statuscodefyi.com](https://statuscodefyi.com/) |

## License

MIT
