viewdns

CLI and Python library for every ViewDNS.info API endpoint

Overview

viewdns is a Python toolkit that covers every endpoint of the ViewDNS.info API — reverse IP, WHOIS, DNS records, port scanning, IP geolocation, spam-database lookups, and more. It works both as a command-line tool and as an importable library, prints readable tables by default, and also speaks JSON, TOON, and raw XML. The HTTP layer uses only the Python standard library.

Key Features

Supported Outputs

Structured data   table (prettytable), json, toon
Passthrough       xml (raw API payload)
File feeds        newly-registered -> gzip bytes (redirect to a file)
Errors            API errors rendered as a key/value table

Installation

From PyPI (Recommended)

pip install viewdns

Set your API key once (get one from your ViewDNS.info account):

export VIEWDNS=your_api_key

From Source

git clone https://github.com/seifreed/viewdns.git
cd viewdns
python3 -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -e ".[dev]"

Quick Start

# Reverse IP lookup (table by default)
viewdns reverse-ip --host google.com

# WHOIS for a domain
viewdns whois --domain example.com

# DNS records of a given type
viewdns dns-record --domain example.com --recordtype MX

# Your account balance
viewdns account --action balance

Usage

Command Line Interface

# JSON output
viewdns ip-location --ip 8.8.8.8 --format json

# TOON output
viewdns dns-record --domain google.com --recordtype A --format toon

# Raw XML from the API
viewdns whois --domain example.com --format xml

# Download the gzip Newly Registered Domains feed
viewdns newly-registered --date 2026-08-14 > nrd.txt.gz

--format selects the output (table default, json, toon, xml); --apikey overrides $VIEWDNS; --timeout sets the request timeout in seconds. Global options work before or after the subcommand. Run viewdns --help for the full command list.

Endpoints

Format Flags

Python Library

Basic Usage

from viewdns import ViewDNSClient

client = ViewDNSClient("your_api_key")
data = client.request("reverse-ip", host="google.com")
whois = client.request("whois", domain="example.com")
xml = client.request("ip-location", ip="9.9.9.9", output="xml")

request returns parsed JSON (a dict) by default, the decoded text for output="xml", and raw bytes for endpoints that serve a downloadable file. Transport failures and unparseable responses raise ViewDNSError; invalid arguments raise ValueError. API-level problems (bad key, exhausted quota, missing subscription) come back inside the response payload.

Downloading a File Feed

gz = client.request("newly-registered", date="2026-08-14")  # bytes
with open("nrd.txt.gz", "wb") as f:
    f.write(gz)

Rendering Responses

from viewdns import render

print(render(data, "table"))  # or "json" / "toon"

Requirements

• Python 3.14+
• Runtime dependencies: prettytable, python-toon
• See pyproject.toml for the full list and dev extras

Development

pip install -e ".[dev]"
black --check . && ruff check . && mypy .
bandit -r viewdns && pip-audit
pytest

Tests run real code against the live API (no mocks) and require $VIEWDNS.

Contributing

Contributions are welcome.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Support the Project

If this project is useful in your workflows, you can support development:

License

This project is licensed under the MIT license. See LICENSE.

Attribution

• Author: Marc Rivero López | @seifreed
• Repository: github.com/seifreed/viewdns

_{Built for practical DNS/OSINT research and security automation}