🌐 DNS Lookup API

A fast, dependency-light DNS lookup service — 10 record types, 9 public resolvers, one JSON response.

Built in Go. Concurrent by design. Ships with Prometheus metrics, per-IP rate limiting, and a clean web UI out of the box.

Live Demo · API Example · Report a Bug

---

What is this?

DNS Lookup API is a self-hostable HTTP service that resolves A, AAAA, NS, MX, TXT, CNAME, SOA, SRV, CAA, and reverse PTR records for any domain or IP address — queried live against nine independent public DNS resolvers (Google, Cloudflare, Quad9, OpenDNS, and more). Every lookup returns a single, predictable JSON object, making it easy to drop into scripts, dashboards, or your own tools without wrestling with dig output or writing your own DNS client.

It's written in Go with no runtime dependencies beyond the binary itself, resolves record types concurrently for low latency, and comes instrumented with Prometheus metrics so you can watch it in production from day one.

Table of Contents

• Features
• Live Demo
• Quick Start
• API Reference
• Supported Record Types
• Supported Resolvers
• Rate Limiting
• Monitoring
• Roadmap
• Contributing
• License
• Support the Project

✨ Features

• ⚡ Concurrent resolution — every record type is queried in parallel, so a full lookup takes about as long as the slowest single query, not the sum of all of them.
• 🌍 9 public resolvers — Google, Cloudflare, OpenDNS, Quad9, AdGuard, DNS.WATCH, Comodo, CleanBrowsing, and UltraDNS, selectable per request.
• 🔁 Reverse DNS (PTR) — pass an IP address instead of a domain and get its PTR record automatically.
• 📦 Predictable JSON — one consistent response shape for every record type, ready to consume from any language.
• 🛡️ Per-IP rate limiting — built-in protection against abuse, no extra proxy required.
• 📊 Prometheus metrics — request durations, upstream query durations, and active worker counts, exposed on /metrics.
• 🩺 Health checks — a dedicated /health endpoint for uptime monitors and orchestrators.
• 🖥️ Web UI included — a lightweight, embedded front end for quick manual lookups, no separate deployment needed.
• 🧵 Zero external runtime dependencies — a single static Go binary.

🚀 Live Demo

Web UI	dns.zumbo.net
Domain lookup (JSON)	dns.zumbo.net/api/lookup?domain=example.com&resolver=cloudflare
Reverse DNS lookup (JSON)	dns.zumbo.net/api/lookup?domain=8.8.8.8&resolver=cloudflare

📦 Quick Start

# Clone the repository
git clone https://github.com/ufukart/DNS-Lookup-API.git
cd DNS-Lookup-API

# Build
go build -o dns-lookup-api .

# Run (defaults to port 3000)
./dns-lookup-api

The service is now available at http://localhost:3000 — the web UI on / and the API on /api/lookup.

Configuration

The service is configured entirely through environment variables:

Variable	Description	Default
PORT	Port the HTTP server listens on	3000
TRUSTED_PROXIES	Comma-separated list of proxy IPs allowed to set X-Forwarded-For / X-Real-IP	(none)

📡 API Reference

GET /api/lookup

Retrieve DNS records for a domain or IP address.

Query parameters:

Parameter	Required	Description
domain	✅	A hostname (example.com) or an IPv4/IPv6 address for a reverse lookup
resolver	❌	One of google, cloudflare, opendns, quad9, adguard, dnswatch, comodo, cleanbrowsing, ultradns. Defaults to cloudflare.

Example request:

curl "https://dns.zumbo.net/api/lookup?domain=example.com&resolver=cloudflare"

Example response:

{
  "domain": "example.com",
  "a": [
    { "ip": "93.184.216.34", "ttl": 300 }
  ],
  "ns": [
    { "host": "a.iana-servers.net", "ip": "199.43.135.53", "ttl": 172800 }
  ],
  "soa": {
    "ns": "a.iana-servers.net",
    "mbox": "noc.dns.icann.org",
    "serial": 2024010101,
    "refresh": 7200,
    "retry": 3600,
    "expire": 1209600,
    "min_ttl": 3600,
    "ttl": 3600
  },
  "resolver": "1.1.1.1",
  "lookup_time_ms": 42,
  "timestamp": "2026-01-01T12:00:00Z"
}

Reverse (PTR) lookup:

curl "https://dns.zumbo.net/api/lookup?domain=8.8.8.8&resolver=google"

{
  "domain": "8.8.8.8",
  "ptr": [
    { "value": "dns.google", "ttl": 21600 }
  ],
  "resolver": "8.8.8.8",
  "lookup_time_ms": 18,
  "timestamp": "2026-01-01T12:00:00Z"
}

GET /health

Simple health check for uptime monitors and load balancers.

{ "status": "healthy" }

GET /metrics

Prometheus-formatted metrics: request durations, upstream DNS query durations (by record type, resolver, and transport), total requests, and active lookup workers.

📄 Supported Record Types

Type	Description
A	IPv4 address
AAAA	IPv6 address
NS	Authoritative name servers
MX	Mail exchange servers, with preference
TXT	Arbitrary text records (SPF, DKIM, verification, etc.)
CNAME	Canonical name / alias
SOA	Start of Authority — zone metadata
SRV	Service location (target, port, priority, weight)
CAA	Certification Authority Authorization
PTR	Reverse DNS — resolved automatically when domain is an IP address

Supported Resolvers

Resolver	Key	IP Address
🟢 Google Public DNS	google	8.8.8.8
🔵 Cloudflare	cloudflare	1.1.1.1
🟠 OpenDNS	opendns	208.67.222.222
🔴 Quad9	quad9	9.9.9.9
🟢 AdGuard DNS	adguard	94.140.14.14
🔵 DNS.WATCH	dnswatch	84.200.69.80
🟠 Comodo Secure DNS	comodo	8.26.56.26
🔴 CleanBrowsing	cleanbrowsing	185.228.168.9
🟢 UltraDNS	ultradns	64.6.64.6

🚦 Rate Limiting

Requests are rate limited per client IP address to keep the service fair and responsive for everyone. Clients that exceed the limit receive an HTTP 429 response. If you're running behind a reverse proxy, set TRUSTED_PROXIES so client IPs are read correctly from X-Forwarded-For / X-Real-IP.

📊 Monitoring

The /metrics endpoint exposes Prometheus metrics out of the box:

• dns_api_request_duration_seconds — end-to-end request latency, by status and resolver
• dns_query_duration_seconds — upstream DNS query latency, by record type, resolver, and transport (UDP/TCP)
• dns_api_requests_total — total requests, by status
• dns_api_active_workers — currently active concurrent lookup workers

Point your existing Prometheus/Grafana stack at it and you have latency and error-rate dashboards with no extra instrumentation work.

Roadmap

• Caching for frequently repeated lookups
• API key authentication
• JSON schema validation for responses

Have a feature in mind that isn't listed? Open an issue — suggestions are welcome.

🤝 Contributing

Contributions are welcome and appreciated. To propose a change:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/my-feature)
3. Commit your changes with a clear message
4. Open a pull request describing what changed and why

Bug reports and feature requests are just as valuable — feel free to open an issue for either.

📄 License

Released under the MIT License. Use it, fork it, ship it.

💙 Support the Project

If this project saves you time, consider buying it a coffee — it helps keep the live demo and future development going.

---

Questions or feedback? Open a GitHub Issue or submit a PR.